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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

42       The  getpwnam() function shall return a pointer to a struct passwd with
43       the structure as defined in <pwd.h> with a matching entry if  found.  A
44       null  pointer shall be returned if the requested entry is not found, or
45       an error occurs. If the requested entry was not found, errno shall  not
46       be changed. 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().  The returned pointer, and pointers within the structure, might
54       also be invalidated if the calling thread is terminated.
55
56       The  getpwnam_r()  function  shall  return  zero  on  success or if the
57       requested entry was not found and no error has occurred.  If  an  error
58       has occurred, an error number shall be returned to indicate the error.
59

ERRORS

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

EXAMPLES

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

APPLICATION USAGE

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

RATIONALE

153       None.
154

FUTURE DIRECTIONS

156       None.
157

SEE ALSO

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