1 files changed, 114 insertions, 0 deletions
diff --git a/qmail-getpw.9 b/qmail-getpw.9
new file mode 100644
index 0000000..0f12e1c
--- /dev/null
+++ b/qmail-getpw.9
@@ -0,0 +1,114 @@
+.TH qmail-getpw 8
+.SH NAME
+qmail-getpw \- give addresses to users
+.SH SYNOPSIS
+.B qmail-getpw
+.I local
+.SH DESCRIPTION
+In
+.BR qmail ,
+each user controls a vast array of local addresses.
+.B qmail-getpw
+finds the user that controls a particular address,
+.IR local .
+It prints six pieces of information,
+each terminated by NUL:
+.IR user ;
+.IR uid ;
+.IR gid ;
+.IR homedir ;
+.IR dash ;
+and
+.IR ext .
+The user's account name is
+.IR user ;
+the user's uid and gid in decimal are
+.I uid
+and
+.IR gid ;
+the user's home directory is
+.IR homedir ;
+and messages to
+.I local
+will be handled by
+.IR homedir\fB/.qmail\fIdashext .
+In case of trouble,
+.B qmail-getpw
+exits nonzero without printing anything.
+.B WARNING:
+The operating system's
+.B getpwnam
+function, which is at the heart of
+.BR qmail-getpw ,
+is inherently unreliable:
+it fails to distinguish between temporary errors and nonexistent users.
+Future versions of
+.B getpwnam
+should return ETXTBSY to indicate temporary errors
+and ESRCH to indicate nonexistent users.
+.SH "RULES"
+.B qmail-getpw
+considers an account in
+.B /etc/passwd
+to be a user if
+(1) the account has a nonzero uid,
+(2) the account's home directory exists (and is visible to
+.BR qmail-getpw ),
+and
+(3) the account owns its home directory.
+.B qmail-getpw
+ignores account names containing uppercase letters.
+.B qmail-getpw
+also assumes that all account names are shorter than 32 characters.
+.B qmail-getpw
+gives each user
+control over the basic
+.I user
+address and
+all addresses of the form
+.IR user\fBBREAK\fIanything .
+When
+.I local
+is
+.IR user ,
+.I dash
+and
+.I ext
+are both empty.
+When
+.I local
+is
+.IR user\fBBREAK\fIanything ,
+.I dash
+is a hyphen and
+.I ext
+is
+.IR anything .
+.I user
+may appear in any combination of uppercase and lowercase letters
+at the front of
+.IR local .
+A catch-all user,
+.BR alias ,
+controls all other addresses.
+In this case
+.I ext
+is
+.I local
+and
+.I dash
+is a hyphen.
+You can override all of
+.BR qmail-getpw 's
+decisions with the
+.B qmail-users
+mechanism, which is reliable, highly configurable, and much faster than
+.BR qmail-getpw .
+.SH "SEE ALSO"
+qmail-users(5),
+qmail-lspawn(8)

diff --git a/qmail-getpw.9 b/qmail-getpw.9 new file mode 100644 index 0000000..0f12e1c --- /dev/null +++ b/qmail-getpw.9
@@ -0,0 +1,114 @@
	1	.TH qmail-getpw 8
	2	.SH NAME
	3	qmail-getpw \- give addresses to users
	4	.SH SYNOPSIS
	5	.B qmail-getpw
	6	.I local
	7	.SH DESCRIPTION
	8	In
	9	.BR qmail ,
	10	each user controls a vast array of local addresses.
	11	.B qmail-getpw
	12	finds the user that controls a particular address,
	13	.IR local .
	14	It prints six pieces of information,
	15	each terminated by NUL:
	16	.IR user ;
	17	.IR uid ;
	18	.IR gid ;
	19	.IR homedir ;
	20	.IR dash ;
	21	and
	22	.IR ext .
	23	The user's account name is
	24	.IR user ;
	25	the user's uid and gid in decimal are
	26	.I uid
	27	and
	28	.IR gid ;
	29	the user's home directory is
	30	.IR homedir ;
	31	and messages to
	32	.I local
	33	will be handled by
	34	.IR homedir\fB/.qmail\fIdashext .
	35
	36	In case of trouble,
	37	.B qmail-getpw
	38	exits nonzero without printing anything.
	39
	40	.B WARNING:
	41	The operating system's
	42	.B getpwnam
	43	function, which is at the heart of
	44	.BR qmail-getpw ,
	45	is inherently unreliable:
	46	it fails to distinguish between temporary errors and nonexistent users.
	47	Future versions of
	48	.B getpwnam
	49	should return ETXTBSY to indicate temporary errors
	50	and ESRCH to indicate nonexistent users.
	51	.SH "RULES"
	52	.B qmail-getpw
	53	considers an account in
	54	.B /etc/passwd
	55	to be a user if
	56	(1) the account has a nonzero uid,
	57	(2) the account's home directory exists (and is visible to
	58	.BR qmail-getpw ),
	59	and
	60	(3) the account owns its home directory.
	61	.B qmail-getpw
	62	ignores account names containing uppercase letters.
	63	.B qmail-getpw
	64	also assumes that all account names are shorter than 32 characters.
	65
	66	.B qmail-getpw
	67	gives each user
	68	control over the basic
	69	.I user
	70	address and
	71	all addresses of the form
	72	.IR user\fBBREAK\fIanything .
	73	When
	74	.I local
	75	is
	76	.IR user ,
	77	.I dash
	78	and
	79	.I ext
	80	are both empty.
	81	When
	82	.I local
	83	is
	84	.IR user\fBBREAK\fIanything ,
	85	.I dash
	86	is a hyphen and
	87	.I ext
	88	is
	89	.IR anything .
	90	.I user
	91	may appear in any combination of uppercase and lowercase letters
	92	at the front of
	93	.IR local .
	94
	95	A catch-all user,
	96	.BR alias ,
	97	controls all other addresses.
	98	In this case
	99	.I ext
	100	is
	101	.I local
	102	and
	103	.I dash
	104	is a hyphen.
	105
	106	You can override all of
	107	.BR qmail-getpw 's
	108	decisions with the
	109	.B qmail-users
	110	mechanism, which is reliable, highly configurable, and much faster than
	111	.BR qmail-getpw .
	112	.SH "SEE ALSO"
	113	qmail-users(5),
	114	qmail-lspawn(8)