1getpwnam(3C)             Standard C Library Functions             getpwnam(3C)
2
3
4

NAME

6       getpwnam, getpwnam_r, getpwent, getpwent_r, getpwuid, getpwuid_r, setp‐
7       went, endpwent, fgetpwent, fgetpwent_r - get password entry
8

SYNOPSIS

10       #include <pwd.h>
11
12       struct passwd *getpwnam(const char *name);
13
14
15       struct passwd *getpwnam_r(const char *name, struct passwd *pwd,
16            char *buffer, int buflen);
17
18
19       struct passwd *getpwent(void);
20
21
22       struct passwd *getpwent_r(struct passwd *pwd, char *buffer,
23            int buflen);
24
25
26       struct passwd *getpwuid(uid_t uid);
27
28
29       struct passwd *getpwuid_r(uid_t uid, struct passwd *pwd,
30           char *buffer, int  buflen);
31
32
33       void setpwent(void);
34
35
36       void endpwent(void);
37
38
39       struct passwd *fgetpwent(FILE *f);
40
41
42       struct passwd *fgetpwent_r(FILE *f, struct passwd *pwd,
43            char *buffer, int buflen);
44
45
46   Standard conforming
47       cc [ flag...] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]
48
49       int getpwnam_r(const char *name, struct passwd *pwd, char *buffer,
50            size_t bufsize, struct passwd **result);
51
52
53       int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer,
54            size_t bufsize, struct passwd **result);
55
56

DESCRIPTION

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
62
63       The getpwnam() function searches for a password entry  with  the  login
64       name specified by the character string parameter name.
65
66
67       The  getpwuid()  function  searches  for  a  password  entry  with  the
68       (numeric) user ID specified by the uid parameter.
69
70
71       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
80
81       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
87
88       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
92   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
98
99       The parallel functions getpwnam_r(),  getpwuid_r(),  getpwent_r(),  and
100       fgetpwent_r() provide reentrant interfaces for these operations.
101
102
103       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
110
111       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
129
130       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
137
138       Like  their  non-reentrant  counterparts, getpwnam_r() and getpwuid_r()
139       leave the enumeration position in an indeterminate state.
140
141   passwd Structure
142       Password entries are represented by the struct passwd structure defined
143       in <pwd.h>:
144
145         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
157
158
159       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

RETURN VALUES

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
169
170       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
176
177       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
183
184       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
189
190       See Intro(2) for the proper usage and interpretation of errno in multi‐
191       threaded applications.
192
193
194       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
198
199       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

ERRORS

204       The getpwent_r(), fgetpwent(), and fgetpwent_r()  functions  will  fail
205       if:
206
207       EIO       An I/O error has occurred.
208
209
210       ERANGE    Insufficient  storage  was  supplied by buffer and bufsize to
211                 contain the data to be referenced  by  the  resulting  passwd
212                 structure.
213
214
215
216       The getpwent_r() function will fail if:
217
218       EMFILE    There  are  {OPEN_MAX} file descriptors currently open in the
219                 calling process.
220
221
222       ENFILE    The maximum allowable number of files is  currently  open  in
223                 the system.
224
225
226
227       The  getpwnam(),  getpwnam_r(),  getpwuid(),  getpwuid_r(), getpwent(),
228       setpwent(), and endpwent() functions may fail if:
229
230       EIO    An I/O error has occurred.
231
232
233
234       The getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r(), getpwent(), and
235       setpwent() functions may fail if:
236
237       EMFILE    There  are  {OPEN_MAX} file descriptors currently open in the
238                 calling process.
239
240
241       ENFILE    The maximum allowable number of files is  currently  open  in
242                 the system.
243
244
245
246       The  getpwnam(),  getpwnam_r(),  getpwuid(), and getpwuid_r() functions
247       may fail if:
248
249       EINTR    A signal was caught during the execution of the function call.
250
251
252
253       The getpwnam_r() and getpwuid_r() functions may fail if:
254
255       ERANGE    Insufficient storage was supplied by buffer  and  bufsize  to
256                 contain  the  data  to  be referenced by the resulting passwd
257                 structure.
258
259

USAGE

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

ATTRIBUTES

268       See attributes(5) for descriptions of the following attributes:
269
270
271
272
273       ┌─────────────────────────────┬─────────────────────────────────────────┐
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
283
284       For endpwent(),  getpwent(),   getpwnam(),   getpwnam_r(),  getpwuid(),
285       getpwuid_r(), and setpwent(), see standards(5).
286

SEE ALSO

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

NOTES

293       When compiling multithreaded programs, see Intro(3).
294
295
296       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
302
303       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
308
309       If required, the `+/-' functionality can still be obtained for  NIS  by
310       specifying compat as the source for passwd.
311
312
313       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
318
319       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
323
324       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
329
330       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
334
335       If the shell field is empty, login(1) automatically assigns the default
336       shell.  See login(1).
337
338
339       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
346
347       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.
350
351
352
353SunOS 5.11                        5 Apr 2004                      getpwnam(3C)
Impressum