[qmail] / qmail-getpw.9

.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)
Commit	Line	Data
2117e02e MW	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 ,
212b6f5d MW	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.
2117e02e MW	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)