1getpwnam(3) Library Functions Manual getpwnam(3)
2
6 getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file entry
7
9 Standard C library (libc, -lc)
10
12 #include <sys/types.h>
13 #include <pwd.h>
14 struct passwd *getpwnam(const char *name);
16 struct passwd *getpwuid(uid_t uid);
17 int getpwnam_r(const char *restrict name, struct passwd *restrict pwd,
19 char buf[restrict .buflen], size_t buflen,
20 struct passwd **restrict result);
21 int getpwuid_r(uid_t uid, struct passwd *restrict pwd,
22 char buf[restrict .buflen], size_t buflen,
23 struct passwd **restrict result);
24 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
26 getpwnam_r(), getpwuid_r():
28 _POSIX_C_SOURCE
29 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
30
32 The getpwnam() function returns a pointer to a structure containing the
33 broken-out fields of the record in the password database (e.g., the lo‐
34 cal password file /etc/passwd, NIS, and LDAP) that matches the username
35 name.
36 The getpwuid() function returns a pointer to a structure containing the
38 broken-out fields of the record in the password database that matches
39 the user ID uid.
40 The passwd structure is defined in <pwd.h> as follows:
42 struct passwd {
44 char *pw_name; /* username */
45 char *pw_passwd; /* user password */
46 uid_t pw_uid; /* user ID */
47 gid_t pw_gid; /* group ID */
48 char *pw_gecos; /* user information */
49 char *pw_dir; /* home directory */
50 char *pw_shell; /* shell program */
51 };
52 See passwd(5) for more information about these fields.
54 The getpwnam_r() and getpwuid_r() functions obtain the same information
56 as getpwnam() and getpwuid(), but store the retrieved passwd structure
57 in the space pointed to by pwd. The string fields pointed to by the
58 members of the passwd structure are stored in the buffer buf of size
59 buflen. A pointer to the result (in case of success) or NULL (in case
60 no entry was found or an error occurred) is stored in *result.
61 The call
63 sysconf(_SC_GETPW_R_SIZE_MAX)
65 returns either -1, without changing errno, or an initial suggested size
67 for buf. (If this size is too small, the call fails with ERANGE, in
68 which case the caller can retry with a larger buffer.)
69
71 The getpwnam() and getpwuid() functions return a pointer to a passwd
72 structure, or NULL if the matching entry is not found or an error oc‐
73 curs. If an error occurs, errno is set to indicate the error. If one
74 wants to check errno after the call, it should be set to zero before
75 the call.
76 The return value may point to a static area, and may be overwritten by
78 subsequent calls to getpwent(3), getpwnam(), or getpwuid(). (Do not
79 pass the returned pointer to free(3).)
80 On success, getpwnam_r() and getpwuid_r() return zero, and set *result
82 to pwd. If no matching password record was found, these functions re‐
83 turn 0 and store NULL in *result. In case of error, an error number is
84 returned, and NULL is stored in *result.
85
87 0 or ENOENT or ESRCH or EBADF or EPERM or ...
88 The given name or uid was not found.
89 EINTR A signal was caught; see signal(7).
91 EIO I/O error.
93 EMFILE The per-process limit on the number of open file descriptors has
95 been reached.
96 ENFILE The system-wide limit on the total number of open files has been
98 reached.
99 ENOMEM Insufficient memory to allocate passwd structure.
101 ERANGE Insufficient buffer space supplied.
103
105 /etc/passwd
106 local password database file
107
109 For an explanation of the terms used in this section, see at‐
110 tributes(7).
111 ┌──────────────┬───────────────┬───────────────────────────────────────┐
113 │Interface │ Attribute │ Value │
114 ├──────────────┼───────────────┼───────────────────────────────────────┤
115 │getpwnam() │ Thread safety │ MT-Unsafe race:pwnam locale │
116 ├──────────────┼───────────────┼───────────────────────────────────────┤
117 │getpwuid() │ Thread safety │ MT-Unsafe race:pwuid locale │
118 ├──────────────┼───────────────┼───────────────────────────────────────┤
119 │getpwnam_r(), │ Thread safety │ MT-Safe locale │
120 │getpwuid_r() │ │ │
121 └──────────────┴───────────────┴───────────────────────────────────────┘
122
124 The pw_gecos field is not specified in POSIX, but is present on most
125 implementations.
126
128 POSIX.1-2008.
129
131 POSIX.1-2001, SVr4, 4.3BSD.
132
134 The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
135 It does not call "not found" an error, and hence does not specify what
136 value errno might have in this situation. But that makes it impossible
137 to recognize errors. One might argue that according to POSIX errno
138 should be left unchanged if an entry is not found. Experiments on var‐
139 ious UNIX-like systems show that lots of different values occur in this
140 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably
141 others.
142 The pw_dir field contains the name of the initial working directory of
144 the user. Login programs use the value of this field to initialize the
145 HOME environment variable for the login shell. An application that
146 wants to determine its user's home directory should inspect the value
147 of HOME (rather than the value getpwuid(getuid())->pw_dir) since this
148 allows the user to modify their notion of "the home directory" during a
149 login session. To determine the (initial) home directory of another
150 user, it is necessary to use getpwnam("username")->pw_dir or similar.
151
153 The program below demonstrates the use of getpwnam_r() to find the full
154 username and user ID for the username supplied as a command-line argu‐
155 ment.
156 #include <errno.h>
158 #include <pwd.h>
159 #include <stdint.h>
160 #include <stdio.h>
161 #include <stdlib.h>
162 #include <unistd.h>
163 int
165 main(int argc, char *argv[])
166 {
167 struct passwd pwd;
168 struct passwd *result;
169 char *buf;
170 long bufsize;
171 int s;
172 if (argc != 2) {
174 fprintf(stderr, "Usage: %s username\n", argv[0]);
175 exit(EXIT_FAILURE);
176 }
177 bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
179 if (bufsize == -1) /* Value was indeterminate */
180 bufsize = 16384; /* Should be more than enough */
181 buf = malloc(bufsize);
183 if (buf == NULL) {
184 perror("malloc");
185 exit(EXIT_FAILURE);
186 }
187 s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
189 if (result == NULL) {
190 if (s == 0)
191 printf("Not found\n");
192 else {
193 errno = s;
194 perror("getpwnam_r");
195 }
196 exit(EXIT_FAILURE);
197 }
198 printf("Name: %s; UID: %jd\n", pwd.pw_gecos,
200 (intmax_t) pwd.pw_uid);
201 exit(EXIT_SUCCESS);
202 }
203
205 endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getsp‐
206 nam(3), putpwent(3), setpwent(3), passwd(5)
207Linux man-pages 6.04 2023-03-30 getpwnam(3)