| [9] | 1 | .TH GETPWENT 3
|
|---|
| 2 | .SH NAME
|
|---|
| 3 | getpwent, getpwnam, getpwuid, setpwent, endpwent, setpwfile \- password file routines
|
|---|
| 4 | .SH SYNOPSIS
|
|---|
| 5 | .ft B
|
|---|
| 6 | .nf
|
|---|
| 7 | #include <pwd.h>
|
|---|
| 8 |
|
|---|
| 9 | struct passwd *getpwent(void)
|
|---|
| 10 | struct passwd *getpwnam(const char *\fIname\fP)
|
|---|
| 11 | struct passwd *getpwuid(uid_t \fIuid\fP)
|
|---|
| 12 | int setpwent(void)
|
|---|
| 13 | void endpwent(void)
|
|---|
| 14 | void setpwfile(const char *\fIfile\fP)
|
|---|
| 15 | .fi
|
|---|
| 16 | .ft P
|
|---|
| 17 | .SH DESCRIPTION
|
|---|
| 18 | These functions are used to obtain information from the password file. They
|
|---|
| 19 | return this information in a
|
|---|
| 20 | .B struct passwd
|
|---|
| 21 | as defined by <pwd.h>:
|
|---|
| 22 | .PP
|
|---|
| 23 | .nf
|
|---|
| 24 | .ta +4n +6n +15n
|
|---|
| 25 | struct passwd {
|
|---|
| 26 | char *pw_name; /* login name */
|
|---|
| 27 | char *pw_passwd; /* encrypted password */
|
|---|
| 28 | uid_t pw_uid; /* numeric user id */
|
|---|
| 29 | gid_t pw_gid; /* numeric group id */
|
|---|
| 30 | char *pw_gecos; /* user full name and other info */
|
|---|
| 31 | char *pw_dir; /* user's home directory */
|
|---|
| 32 | char *pw_shell; /* name of the user's shell */
|
|---|
| 33 | };
|
|---|
| 34 | .fi
|
|---|
| 35 | .PP
|
|---|
| 36 | .B Getpwent()
|
|---|
| 37 | reads the password file entry by entry.
|
|---|
| 38 | .B Getpwnam()
|
|---|
| 39 | scans the entire password file for the user with the given
|
|---|
| 40 | .IR name .
|
|---|
| 41 | .B Getpwuid()
|
|---|
| 42 | looks for the first user with the given
|
|---|
| 43 | .IR uid .
|
|---|
| 44 | The
|
|---|
| 45 | .B setpwent()
|
|---|
| 46 | and
|
|---|
| 47 | .B endpwent()
|
|---|
| 48 | functions are used to open and later close the password file. With
|
|---|
| 49 | .B setpwfile()
|
|---|
| 50 | one can specify the file to read other than the normal password file. This
|
|---|
| 51 | only sets the name, the next
|
|---|
| 52 | .B setpwent()
|
|---|
| 53 | call will open the file. Do not touch the file name while it is active.
|
|---|
| 54 | Use
|
|---|
| 55 | .B setpwfile(NULL)
|
|---|
| 56 | to revert back to the normal password file.
|
|---|
| 57 | .PP
|
|---|
| 58 | The usual way to scan the password file is (error checking omitted):
|
|---|
| 59 | .PP
|
|---|
| 60 | .RS
|
|---|
| 61 | .nf
|
|---|
| 62 | .DT
|
|---|
| 63 | setpwent();
|
|---|
| 64 | while ((pw = getpwent()) != NULL)
|
|---|
| 65 | if (appropriate_test(pw)) break;
|
|---|
| 66 | endpwent();
|
|---|
| 67 | .fi
|
|---|
| 68 | .RE
|
|---|
| 69 | .PP
|
|---|
| 70 | The
|
|---|
| 71 | .B pw
|
|---|
| 72 | variable contains the entry that is wanted if non-NULL. The
|
|---|
| 73 | .B getpwnam()
|
|---|
| 74 | and
|
|---|
| 75 | .B getpwuid()
|
|---|
| 76 | functions are implemented as in this example, with error checking of course.
|
|---|
| 77 | .PP
|
|---|
| 78 | .B Getpwent()
|
|---|
| 79 | calls
|
|---|
| 80 | .B setpwent()
|
|---|
| 81 | if this has not yet been done.
|
|---|
| 82 | .B Setpwent()
|
|---|
| 83 | first calls
|
|---|
| 84 | .B endpwent()
|
|---|
| 85 | if the password file is still open. (Other implementations may simply
|
|---|
| 86 | rewind the file.)
|
|---|
| 87 | .SH FILES
|
|---|
| 88 | .TP 15
|
|---|
| 89 | .B /etc/passwd
|
|---|
| 90 | The password file database.
|
|---|
| 91 | .SH "SEE ALSO"
|
|---|
| 92 | .BR cuserid (3),
|
|---|
| 93 | .BR getlogin (3),
|
|---|
| 94 | .BR getgrent (3),
|
|---|
| 95 | .BR passwd (5).
|
|---|
| 96 | .SH DIAGNOSTICS
|
|---|
| 97 | .B Setpwent()
|
|---|
| 98 | has the same return value and error codes as the
|
|---|
| 99 | .BR open (2)
|
|---|
| 100 | call it uses to open the password file. The
|
|---|
| 101 | .BI get xxx ()
|
|---|
| 102 | functions return NULL on end of file, entry not found, or error. You can
|
|---|
| 103 | set
|
|---|
| 104 | .B errno
|
|---|
| 105 | to zero before the call and check it after.
|
|---|
| 106 | .SH NOTES
|
|---|
| 107 | All
|
|---|
| 108 | .BI get xxx ()
|
|---|
| 109 | routines return a pointer to static storage that is overwritten in each call.
|
|---|
| 110 | .PP
|
|---|
| 111 | Only
|
|---|
| 112 | .B getpwnam()
|
|---|
| 113 | and
|
|---|
| 114 | .B getpwuid()
|
|---|
| 115 | are defined by \s-2POSIX\s+2. The
|
|---|
| 116 | .B _MINIX_SOURCE
|
|---|
| 117 | macro must be defined before including <pwd.h> to make the other functions
|
|---|
| 118 | visible. The
|
|---|
| 119 | .B pw_passwd
|
|---|
| 120 | and
|
|---|
| 121 | .B pw_gecos
|
|---|
| 122 | fields are also not defined by \s-2POSIX\s+2, but are always visible.
|
|---|
| 123 | Portable code cannot reliably detect errors by setting
|
|---|
| 124 | .B errno
|
|---|
| 125 | to zero. Under MINIX 3 it is better to make a
|
|---|
| 126 | .B getpwent()
|
|---|
| 127 | scan if you need to look up several user-id's or names, but portable code
|
|---|
| 128 | had better use several
|
|---|
| 129 | .B getpwuid()
|
|---|
| 130 | or
|
|---|
| 131 | .B getpwnam()
|
|---|
| 132 | calls. The
|
|---|
| 133 | .B getpwent()
|
|---|
| 134 | is usually available on other systems, but may be very expensive.
|
|---|
| 135 | .SH AUTHOR
|
|---|
| 136 | Kees J. Bot (kjb@cs.vu.nl)
|
|---|
| 137 |
|
|---|
| 138 | .\"
|
|---|
| 139 | .\" $PchId: getpwent.3,v 1.2 1996/04/11 06:37:43 philip Exp $
|
|---|
