1getpwnam(3C) Standard C Library Functions getpwnam(3C)
2
6 getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid, getpwuid_r, setp‐
7 went, endpwent, fgetpwent, fgetpwent_r - get password entry
8
10 #include <pwd.h>
11 struct passwd *getpwnam(const char *name);
13 struct passwd *getpwnam_r(const char *name, struct passwd *pwd,
16 char *buffer, int buflen);
17 struct passwd *getpwent(void);
20 struct passwd *getpwent_r(struct passwd *pwd, char *buffer,
23 int buflen);
24 struct passwd *getpwuid(uid_t uid);
27 struct passwd *getpwuid_r(uid_t uid, struct passwd *pwd,
30 char *buffer, int buflen);
31 void setpwent(void);
34 void endpwent(void);
37 struct passwd *fgetpwent(FILE *f);
40 struct passwd *fgetpwent_r(FILE *f, struct passwd *pwd,
43 char *buffer, int buflen);
44 Standard conforming
47 cc [ flag...] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
48 int getpwnam_r(const char *name, struct passwd *pwd, char *buffer,
50 size_t bufsize, struct passwd **result);
51 int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer,
54 size_t bufsize, struct passwd **result);
55
58 These functions are used to obtain password entries. Entries can come
59 from any of the sources for passwd specified in the /etc/nsswitch.conf
60 file (see nsswitch.conf(4)).
61 The getpwnam() function searches for a password entry with the login
64 name specified by the character string parameter name.
65 The getpwuid() function searches for a password entry with the
68 (numeric) user ID specified by the uid parameter.
69 The setpwent(), getpwent(), and endpwent() functions are used to enu‐
72 merate password entries from the database. The setpwent() function sets
73 (or resets) the enumeration to the beginning of the set of password
74 entries. This function should be called before the first call to getp‐
75 went(). Calls to getpwnam() and getpwuid() leave the enumeration posi‐
76 tion in an indeterminate state. Successive calls to getpwent() return
77 either successive entries or a null pointer, indicating the end of the
78 enumeration.
79 The endpwent() function may be called to indicate that the caller
82 expects to do no further password retrieval operations; the system may
83 then close the password file, deallocate resources it was using, and
84 so forth. It is still allowed, but possibly less efficient, for the
85 process to call more password functions after calling endpwent().
86 The fgetpwent() function, unlike the other functions above, does not
89 use nsswitch.conf but reads and parses the next line from the stream f,
90 which is assumed to have the format of the passwd file. See passwd(4).
91 Reentrant Interfaces
93 The getpwnam(), getpwuid(), getpwent(), and fgetpwent() functions use
94 thread-specific data storage that is reused in each call to one of
95 these functions by the same thread, making them safe to use but not
96 recommended for multithreaded applications.
97 The parallel functions getpwnam_r(), getpwuid_r(), getpwent_r(), and
100 fgetpwent_r() provide reentrant interfaces for these operations.
101 Each reentrant interface performs the same operation as its non-reen‐
104 trant counterpart, named by removing the "_r" suffix. The reentrant
105 interfaces, however, use buffers supplied by the caller to store
106 returned results instead of using thread-specific data that can be
107 overwritten by each call. They are safe for use in both single-threaded
108 and multithreaded applications.
109 Each reentrant interface takes the same parameters as its non-reentrant
112 counterpart, as well as the following additional parameters. The pwd
113 parameter must be a pointer to a struct passwd structure allocated by
114 the caller. On successful completion, the function returns the password
115 entry in this structure. The parameter buffer is a pointer to a buffer
116 supplied by the caller, used as storage space for the password data.
117 All pointers within the returned struct passwd pwd point to data stored
118 within this buffer; see passwd Structure below. The buffer must be
119 large enough to hold all the data associated with the password entry.
120 The parameter buflen (or bufsize for the standard-conforming versions;
121 see standards(5)) should give the size in bytes of buffer. The maximum
122 size needed for this buffer can be determined with the
123 {_SC_GETPW_R_SIZE_MAX} sysconf(3C) parameter. The standard-conforming
124 versions place a pointer to the modified pwd structure in the result
125 parameter, instead of returning a pointer to this structure. A null
126 pointer is returned at the location pointed to by result on error or if
127 the requested entry is not found.
128 For enumeration in multithreaded applications, the position within the
131 enumeration is a process-wide property shared by all threads. The setp‐
132 went() function can be used in a multithreaded application but resets
133 the enumeration position for all threads. If multiple threads inter‐
134 leave calls to getpwent_r(), the threads will enumerate disjoint sub‐
135 sets of the password database.
136 Like their non-reentrant counterparts, getpwnam_r() and getpwuid_r()
139 leave the enumeration position in an indeterminate state.
140 passwd Structure
142 Password entries are represented by the struct passwd structure defined
143 in <pwd.h>:
144 struct passwd {
146 char *pw_name; /* user's login name */
147 char *pw_passwd; /* no longer used */
148 uid_t pw_uid; /* user's uid */
149 gid_t pw_gid; /* user's gid */
150 char *pw_age; /* not used */
151 char *pw_comment; /* not used */
152 char *pw_gecos; /* typically user's full name */
153 char *pw_dir; /* user's home dir */
154 char *pw_shell; /* user's login shell */
155 };
156 The pw_passwd member should not be used as the encrypted password for
160 the user; use getspnam() or getspnam_r() instead. See getspnam(3C).
161
163 The getpwnam(), getpwnam_r(), getpwuid(), and getpwuid_r() functions
164 each return a pointer to a struct passwd if they successfully locate
165 the requested entry. A null pointer is returned if the requested entry
166 is not found, or an error occurs. On error, errno is set to indicate
167 the error.
168 Applications wishing to check for error situations should set errno to
171 0 before calling getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(),
172 getpwent(), getpwent_r(), fgetpwent(), and fgetpwent_r(). If these non-
173 reentrant functions return a null pointer and errno is non-zero, an
174 error occurred.
175 The standard-conforming functions getpwnam_r() and getpwuid_r() can
178 return 0 even on an error, particularly in the case where the requested
179 entry is not found. The application needs to check the return value and
180 that the pwd pointer is non-null. Otherwise, an error value is returned
181 to indicate the error.
182 The getpwent(), getpwent_r(), fgetpwent(), and fgetpwent_r() functions
185 each return a pointer to a struct passwd if they successfully enumerate
186 an entry; otherwise they return a null pointer on end-of-file or error.
187 On error, errno is set to indicate the error.
188 See Intro(2) for the proper usage and interpretation of errno in multi‐
191 threaded applications.
192 The getpwnam(), getpwuid(), getpwent(), and fgetpwent() functions use
195 thread-specific data storage, so returned data must be copied before a
196 subsequent call to any of these functions if the data is to be saved.
197 When the pointer returned by the reentrant functions getpwnam_r(), get‐
200 pwuid_r(), getpwent_r(), and fgetpwent_r() is non-null, it is always
201 equal to the pwd pointer that was supplied by the caller.
202
204 The getpwent_r(), fgetpwent(), and fgetpwent_r() functions will fail
205 if:
206 EIO An I/O error has occurred.
208 ERANGE Insufficient storage was supplied by buffer and bufsize to
211 contain the data to be referenced by the resulting passwd
212 structure.
213 The getpwent_r() function will fail if:
217 EMFILE There are {OPEN_MAX} file descriptors currently open in the
219 calling process.
220 ENFILE The maximum allowable number of files is currently open in
223 the system.
224 The getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), getpwent(),
228 setpwent(), and endpwent() functions may fail if:
229 EIO An I/O error has occurred.
231 The getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), getpwent(), and
235 setpwent() functions may fail if:
236 EMFILE There are {OPEN_MAX} file descriptors currently open in the
238 calling process.
239 ENFILE The maximum allowable number of files is currently open in
242 the system.
243 The getpwnam(), getpwnam_r(), getpwuid(), and getpwuid_r() functions
247 may fail if:
248 EINTR A signal was caught during the execution of the function call.
250 The getpwnam_r() and getpwuid_r() functions may fail if:
254 ERANGE Insufficient storage was supplied by buffer and bufsize to
256 contain the data to be referenced by the resulting passwd
257 structure.
258
261 Three names associated with the current process can be determined: get‐
262 pwuid(geteuid()) returns the name associated with the effective user ID
263 of the process; getlogin() returns the name associated with the current
264 login activity; and getpwuid(getuid()) returns the name associated with
265 the real user ID of the process.
266
268 See attributes(5) for descriptions of the following attributes:
269 ┌─────────────────────────────┬─────────────────────────────────────────┐
274 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
275 ├─────────────────────────────┼─────────────────────────────────────────┤
276 │Interface Stability │Committed │
277 ├─────────────────────────────┼─────────────────────────────────────────┤
278 │MT-Level │See Reentrant Interfaces in DESCRIPTION. │
279 ├─────────────────────────────┼─────────────────────────────────────────┤
280 │Standard │See below. │
281 └─────────────────────────────┴─────────────────────────────────────────┘
282 For endpwent(), getpwent(), getpwnam(), getpwnam_r(), getpwuid(),
285 getpwuid_r(), and setpwent(), see standards(5).
286
288 nispasswd(1), passwd(1), yppasswd(1), Intro(2), Intro(3), cuserid(3C),
289 getgrnam(3C), getlogin(3C), getspnam(3C), nsswitch.conf(4), passwd(4),
290 shadow(4), attributes(5), standards(5)
291
293 When compiling multithreaded programs, see Intro(3).
294 Use of the enumeration interfaces getpwent() and getpwent_r() is dis‐
297 couraged; enumeration is supported for the passwd file, NIS, and NIS+,
298 but in general is not efficient and might not be supported for all
299 database sources. The semantics of enumeration are discussed further
300 in nsswitch.conf(4).
301 Previous releases allowed the use of `+' and `-' entries in /etc/passwd
304 to selectively include and exclude NIS entries. The primary usage of
305 these `+/-' entries is superseded by the name service switch, so the
306 `+/-' form might not be supported in future releases.
307 If required, the `+/-' functionality can still be obtained for NIS by
310 specifying compat as the source for passwd.
311 If the `+/-' functionality is required in conjunction with NIS+, spec‐
314 ify both compat as the source for passwd and nisplus as the source for
315 the pseudo-database passwd_compat. See passwd(4), shadow(4), and nss‐
316 witch.conf(4) for details.
317 If the `+/-' is used, both /etc/shadow and /etc/passwd should have the
320 same `+' and `-' entries to ensure consistency between the password and
321 shadow databases.
322 If a password entry from any of the sources contains an empty uid or
325 gid field, that entry will be ignored by the files, NIS, and NIS+ name
326 service switch backends, causing the user to appear unknown to the sys‐
327 tem.
328 If a password entry contains an empty gecos, home directory, or shell
331 field, getpwnam() and getpwnam_r() return a pointer to a null string in
332 the respective field of the passwd structure.
333 If the shell field is empty, login(1) automatically assigns the default
336 shell. See login(1).
337 Solaris 2.4 and earlier releases provided definitions of the getpw‐
340 nam_r() and getpwuid_r() functions as specified in POSIX.1c Draft 6.
341 The final POSIX.1c standard changed the interface for these functions.
342 Support for the Draft 6 interface is provided for compatibility only
343 and might not be supported in future releases. New applications and
344 libraries should use the standard-conforming interface.
345 For POSIX.1c-conforming applications, the _POSIX_PTHREAD_SEMANTICS and
348 _REENTRANT flags are automatically turned on by defining the
349 _POSIX_C_SOURCE flag with a value ≥199506L.
350SunOS 5.11 5 Apr 2004 getpwnam(3C)