| 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) |