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)