1GETPWNAM(3)                Linux Programmer's Manual               GETPWNAM(3)
2
3
4

NAME

6       getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file entry
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <pwd.h>
11
12       struct passwd *getpwnam(const char *name);
13       struct passwd *getpwuid(uid_t uid);
14
15       int getpwnam_r(const char *restrict name, struct passwd *restrict pwd,
16                      char *restrict buf, size_t buflen,
17                      struct passwd **restrict result);
18       int getpwuid_r(uid_t uid, struct passwd *restrict pwd,
19                      char *restrict buf, size_t buflen,
20                      struct passwd **restrict result);
21
22   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
23
24       getpwnam_r(), getpwuid_r():
25           _POSIX_C_SOURCE
26               || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
27

DESCRIPTION

29       The getpwnam() function returns a pointer to a structure containing the
30       broken-out fields of the record in the password database (e.g., the lo‐
31       cal password file /etc/passwd, NIS, and LDAP) that matches the username
32       name.
33
34       The getpwuid() function returns a pointer to a structure containing the
35       broken-out  fields  of the record in the password database that matches
36       the user ID uid.
37
38       The passwd structure is defined in <pwd.h> as follows:
39
40           struct passwd {
41               char   *pw_name;       /* username */
42               char   *pw_passwd;     /* user password */
43               uid_t   pw_uid;        /* user ID */
44               gid_t   pw_gid;        /* group ID */
45               char   *pw_gecos;      /* user information */
46               char   *pw_dir;        /* home directory */
47               char   *pw_shell;      /* shell program */
48           };
49
50       See passwd(5) for more information about these fields.
51
52       The getpwnam_r() and getpwuid_r() functions obtain the same information
53       as  getpwnam() and getpwuid(), but store the retrieved passwd structure
54       in the space pointed to by pwd.  The string fields pointed  to  by  the
55       members  of  the  passwd structure are stored in the buffer buf of size
56       buflen.  A pointer to the result (in case of success) or NULL (in  case
57       no entry was found or an error occurred) is stored in *result.
58
59       The call
60
61           sysconf(_SC_GETPW_R_SIZE_MAX)
62
63       returns either -1, without changing errno, or an initial suggested size
64       for buf.  (If this size is too small, the call fails  with  ERANGE,  in
65       which case the caller can retry with a larger buffer.)
66

RETURN VALUE

68       The  getpwnam()  and  getpwuid() functions return a pointer to a passwd
69       structure, or NULL if the matching entry is not found or an  error  oc‐
70       curs.   If an error occurs, errno is set to indicate the error.  If one
71       wants to check errno after the call, it should be set  to  zero  before
72       the call.
73
74       The  return value may point to a static area, and may be overwritten by
75       subsequent calls to getpwent(3), getpwnam(), or  getpwuid().   (Do  not
76       pass the returned pointer to free(3).)
77
78       On  success, getpwnam_r() and getpwuid_r() return zero, and set *result
79       to pwd.  If no matching password record was found, these functions  re‐
80       turn 0 and store NULL in *result.  In case of error, an error number is
81       returned, and NULL is stored in *result.
82

ERRORS

84       0 or ENOENT or ESRCH or EBADF or EPERM or ...
85              The given name or uid was not found.
86
87       EINTR  A signal was caught; see signal(7).
88
89       EIO    I/O error.
90
91       EMFILE The per-process limit on the number of open file descriptors has
92              been reached.
93
94       ENFILE The system-wide limit on the total number of open files has been
95              reached.
96
97       ENOMEM Insufficient memory to allocate passwd structure.
98
99       ERANGE Insufficient buffer space supplied.
100

FILES

102       /etc/passwd
103              local password database file
104

ATTRIBUTES

106       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
107       tributes(7).
108
109       ┌──────────────┬───────────────┬───────────────────────────────────────┐
110Interface     Attribute     Value                                 
111       ├──────────────┼───────────────┼───────────────────────────────────────┤
112getpwnam()    │ Thread safety │ MT-Unsafe race:pwnam locale           │
113       ├──────────────┼───────────────┼───────────────────────────────────────┤
114getpwuid()    │ Thread safety │ MT-Unsafe race:pwuid locale           │
115       ├──────────────┼───────────────┼───────────────────────────────────────┤
116getpwnam_r(), │ Thread safety │ MT-Safe locale                        │
117getpwuid_r()  │               │                                       │
118       └──────────────┴───────────────┴───────────────────────────────────────┘
119

CONFORMING TO

121       POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.  The pw_gecos  field  is  not
122       specified in POSIX, but is present on most implementations.
123

NOTES

125       The  formulation given above under "RETURN VALUE" is from POSIX.1-2001.
126       It does not call "not found" an error, and hence does not specify  what
127       value errno might have in this situation.  But that makes it impossible
128       to recognize errors.  One might argue that  according  to  POSIX  errno
129       should be left unchanged if an entry is not found.  Experiments on var‐
130       ious UNIX-like systems show that lots of different values occur in this
131       situation:  0,  ENOENT,  EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably
132       others.
133
134       The pw_dir field contains the name of the initial working directory  of
135       the user.  Login programs use the value of this field to initialize the
136       HOME environment variable for the login  shell.   An  application  that
137       wants  to  determine its user's home directory should inspect the value
138       of HOME (rather than the value getpwuid(getuid())->pw_dir)  since  this
139       allows the user to modify their notion of "the home directory" during a
140       login session.  To determine the (initial) home  directory  of  another
141       user, it is necessary to use getpwnam("username")->pw_dir or similar.
142

EXAMPLES

144       The program below demonstrates the use of getpwnam_r() to find the full
145       username and user ID for the username supplied as a command-line  argu‐
146       ment.
147
148       #include <pwd.h>
149       #include <stdint.h>
150       #include <stdio.h>
151       #include <stdlib.h>
152       #include <unistd.h>
153       #include <errno.h>
154
155       int
156       main(int argc, char *argv[])
157       {
158           struct passwd pwd;
159           struct passwd *result;
160           char *buf;
161           size_t bufsize;
162           int s;
163
164           if (argc != 2) {
165               fprintf(stderr, "Usage: %s username\n", argv[0]);
166               exit(EXIT_FAILURE);
167           }
168
169           bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
170           if (bufsize == -1)          /* Value was indeterminate */
171               bufsize = 16384;        /* Should be more than enough */
172
173           buf = malloc(bufsize);
174           if (buf == NULL) {
175               perror("malloc");
176               exit(EXIT_FAILURE);
177           }
178
179           s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
180           if (result == NULL) {
181               if (s == 0)
182                   printf("Not found\n");
183               else {
184                   errno = s;
185                   perror("getpwnam_r");
186               }
187               exit(EXIT_FAILURE);
188           }
189
190           printf("Name: %s; UID: %jd\n", pwd.pw_gecos,
191                   (intmax_t) pwd.pw_uid);
192           exit(EXIT_SUCCESS);
193       }
194

SEE ALSO

196       endpwent(3),  fgetpwent(3),  getgrnam(3), getpw(3), getpwent(3), getsp‐
197       nam(3), putpwent(3), setpwent(3), passwd(5)
198

COLOPHON

200       This page is part of release 5.13 of the Linux  man-pages  project.   A
201       description  of  the project, information about reporting bugs, and the
202       latest    version    of    this    page,    can     be     found     at
203       https://www.kernel.org/doc/man-pages/.
204
205
206
207GNU                               2021-03-22                       GETPWNAM(3)
Impressum