1GETPWNAM(3P)               POSIX Programmer's Manual              GETPWNAM(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       getpwnam, getpwnam_r — search user database for a name
14

SYNOPSIS

16       #include <pwd.h>
17
18       struct passwd *getpwnam(const char *name);
19       int getpwnam_r(const char *name, struct passwd *pwd, char *buffer,
20           size_t bufsize, struct passwd **result);
21

DESCRIPTION

23       The getpwnam() function shall search the user  database  for  an  entry
24       with a matching name.
25
26       The getpwnam() function need not be thread-safe.
27
28       Applications  wishing to check for error situations should set errno to
29       0 before calling getpwnam().  If getpwnam() returns a null pointer  and
30       errno is non-zero, an error occurred.
31
32       The  getpwnam_r() function shall update the passwd structure pointed to
33       by pwd and store a pointer to that structure at the location pointed to
34       by result.  The structure shall contain an entry from the user database
35       with a matching name.  Storage referenced by the structure is allocated
36       from  the  memory  provided with the buffer parameter, which is bufsize
37       bytes in size. A call to sysconf(_SC_GETPW_R_SIZE_MAX)  returns  either
38       −1 without changing errno or an initial value suggested for the size of
39       this buffer.  A null pointer shall be returned at the location  pointed
40       to by result on error or if the requested entry is not found.
41

RETURN VALUE

43       The  getpwnam() function shall return a pointer to a struct passwd with
44       the structure as defined in <pwd.h> with a matching entry if  found.  A
45       null  pointer shall be returned if the requested entry is not found, or
46       an error occurs. On error, errno shall be set to indicate the error.
47
48       The application shall not modify the  structure  to  which  the  return
49       value  points,  nor any storage areas pointed to by pointers within the
50       structure. The returned pointer, and  pointers  within  the  structure,
51       might  be  invalidated  or  the structure or the storage areas might be
52       overwritten by a subsequent call to getpwent(),  getpwnam(),  or  getp‐
53       wuid().
54
55       The  getpwnam_r()  function  shall  return  zero  on  success or if the
56       requested entry was not found and no error has occurred.  If  an  error
57       has occurred, an error number shall be returned to indicate the error.
58

ERRORS

60       These functions may fail if:
61
62       EIO    An I/O error has occurred.
63
64       EINTR  A signal was caught during getpwnam().
65
66       EMFILE All  file  descriptors  available  to  the process are currently
67              open.
68
69       ENFILE The maximum allowable number of files is currently open  in  the
70              system.
71
72       The getpwnam_r() function may fail if:
73
74       ERANGE Insufficient storage was supplied via buffer and bufsize to con‐
75              tain the data to be referenced by the  resulting  passwd  struc‐
76              ture.
77
78       The following sections are informative.
79

EXAMPLES

81       Note  that  sysconf(_SC_GETPW_R_SIZE_MAX)  may return −1 if there is no
82       hard limit on the size of the buffer needed to  store  all  the  groups
83       returned.  This  example shows how an application can allocate a buffer
84       of sufficient size to work with getpwnam_r().
85
86           long int initlen = sysconf(_SC_GETPW_R_SIZE_MAX);
87           size_t len;
88           if (initlen == −1)
89               /* Default initial length. */
90               len = 1024;
91           else
92               len = (size_t) initlen;
93           struct passwd result;
94           struct passwd *resultp;
95           char *buffer = malloc(len);
96           if (buffer == NULL)
97               ...handle error...
98           int e;
99           while ((e = getpwnam_r("someuser", &result, buffer, len, &resultp))
100                   == ERANGE)
101               {
102               size_t newlen = 2 * len;
103               if (newlen < len)
104                   ...handle error...
105               len = newlen;
106               char *newbuffer = realloc(buffer, len);
107               if (newbuffer == NULL)
108                   ...handle error...
109               buffer = newbuffer;
110               }
111           if (e != 0)
112               ...handle error...
113           free (buffer);
114
115   Getting an Entry for the Login Name
116       The following example uses the getlogin() function to return  the  name
117       of the user who logged in; this information is passed to the getpwnam()
118       function to get the user database entry for that user.
119
120           #include <sys/types.h>
121           #include <pwd.h>
122           #include <unistd.h>
123           #include <stdio.h>
124           #include <stdlib.h>
125           ...
126           char *lgn;
127           struct passwd *pw;
128           ...
129           if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) {
130               fprintf(stderr, "Get of user information failed.\n"); exit(1);
131           }
132           ...
133

APPLICATION USAGE

135       Three names associated with the current process can be determined: get‐
136       pwuid(geteuid()) returns the name associated with the effective user ID
137       of the process; getlogin() returns the name associated with the current
138       login activity; and getpwuid(getuid()) returns the name associated with
139       the real user ID of the process.
140
141       The getpwnam_r() function is thread-safe and returns values in a  user-
142       supplied  buffer  instead of possibly using a static data area that may
143       be overwritten by each call.
144
145       Portable applications should take into account that it is usual for  an
146       implementation  to return −1 from sysconf() indicating that there is no
147       maximum for _SC_GETPW_R_SIZE_MAX.
148

RATIONALE

150       None.
151

FUTURE DIRECTIONS

153       None.
154

SEE ALSO

156       getpwuid(), sysconf()
157
158       The Base Definitions volume of POSIX.1‐2008, <pwd.h>, <sys_types.h>
159
161       Portions of this text are reprinted and reproduced in  electronic  form
162       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
163       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
164       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
165       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
166       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
167       event of any discrepancy between this version and the original IEEE and
168       The  Open Group Standard, the original IEEE and The Open Group Standard
169       is the referee document. The original Standard can be  obtained  online
170       at http://www.unix.org/online.html .
171
172       Any  typographical  or  formatting  errors that appear in this page are
173       most likely to have been introduced during the conversion of the source
174       files  to  man page format. To report such errors, see https://www.ker
175       nel.org/doc/man-pages/reporting_bugs.html .
176
177
178
179IEEE/The Open Group                  2013                         GETPWNAM(3P)
Impressum