mdw@git.distorted.org.uk Git - qmail/blob - qmail-getpw.9

   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)