1GETPWNAM(3) Linux Programmer's Manual GETPWNAM(3)
2
6 getpwnam, getpwnam_r, getpwuid, getpwuid_r - get password file entry
7
9 #include <sys/types.h>
10 #include <pwd.h>
11 struct passwd *getpwnam(const char *name);
13 struct passwd *getpwuid(uid_t uid);
15 int getpwnam_r(const char *name, struct passwd *pwd,
17 char *buf, size_t buflen, struct passwd **result);
18 int getpwuid_r(uid_t uid, struct passwd *pwd,
20 char *buf, size_t buflen, struct passwd **result);
21 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
23 getpwnam_r(), getpwuid_r(): _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE ||
25 _BSD_SOURCE || _SVID_SOURCE || _POSIX_SOURCE
26
28 The getpwnam() function returns a pointer to a structure containing the
29 broken-out fields of the record in the password database (e.g., the
30 local password file /etc/passwd, NIS, and LDAP) that matches the user‐
31 name name.
32 The getpwuid() function returns a pointer to a structure containing the
34 broken-out fields of the record in the password database that matches
35 the user ID uid.
36 The getpwnam_r() and getpwuid_r() functions obtain the same informa‐
38 tion, but store the retrieved passwd structure in the space pointed to
39 by pwd. This passwd structure contains pointers to strings, and these
40 strings are stored in the buffer buf of size buflen. A pointer to the
41 result (in case of success) or NULL (in case no entry was found or an
42 error occurred) is stored in *result.
43 The passwd structure is defined in <pwd.h> as follows:
45 struct passwd {
47 char *pw_name; /* username */
48 char *pw_passwd; /* user password */
49 uid_t pw_uid; /* user ID */
50 gid_t pw_gid; /* group ID */
51 char *pw_gecos; /* real name */
52 char *pw_dir; /* home directory */
53 char *pw_shell; /* shell program */
54 };
55 The maximum needed size for buf can be found using sysconf(3) with the
57 argument _SC_GETPW_R_SIZE_MAX.
58
60 The getpwnam() and getpwuid() functions return a pointer to a passwd
61 structure, or NULL if the matching entry is not found or an error
62 occurs. If an error occurs, errno is set appropriately. If one wants
63 to check errno after the call, it should be set to zero before the
64 call.
65 The return value may point to a static area, and may be overwritten by
67 subsequent calls to getpwent(3), getpwnam(), or getpwuid(). (Do not
68 pass the returned pointer to free(3).)
69 On success, getpwnam_r() and getpwuid_r() return zero, and set *result
71 to pwd. If no matching password record was found, these functions
72 return 0 and store NULL in *result. In case of error, an error number
73 is returned, and NULL is stored in *result.
74
76 0 or ENOENT or ESRCH or EBADF or EPERM or ...
77 The given name or uid was not found.
78 EINTR A signal was caught.
80 EIO I/O error.
82 EMFILE The maximum number (OPEN_MAX) of files was open already in the
84 calling process.
85 ENFILE The maximum number of files was open already in the system.
87 ENOMEM Insufficient memory to allocate passwd structure.
89 ERANGE Insufficient buffer space supplied.
91
93 /etc/passwd
94 local password database file
95
97 SVr4, 4.3BSD, POSIX.1-2001.
98
100 The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
101 It does not call "not found" an error, and hence does not specify what
102 value errno might have in this situation. But that makes it impossible
103 to recognize errors. One might argue that according to POSIX errno
104 should be left unchanged if an entry is not found. Experiments on var‐
105 ious Unix-like systems show that lots of different values occur in this
106 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM and probably
107 others.
108 The pw_dir field contains the name of the initial working directory of
110 the user. Login programs use the value of this field to initialize the
111 HOME environment variable for the login shell. An application that
112 wants to determine its user's home directory should inspect the value
113 of HOME (rather than the value getpwuid(getuid())->pw_dir) since this
114 allows the user to modify their notion of "the home directory" during a
115 login session. To determine the (initial) home directory of another
116 user, it is necessary to use getpwnam("username")->pw_dir or similar.
117
119 The program below demonstrates the use of getpwnam_r() to find the full
120 username and user ID for the username supplied as a command-line argu‐
121 ment.
122 #include <pwd.h>
124 #include <stdio.h>
125 #include <stdlib.h>
126 #include <unistd.h>
127 #include <errno.h>
128 int
130 main(int argc, char *argv[])
131 {
132 struct passwd pwd;
133 struct passwd *result;
134 char *buf;
135 size_t bufsize;
136 int s;
137 if (argc != 2) {
139 fprintf(stderr, "Usage: %s username\n", argv[0]);
140 exit(EXIT_FAILURE);
141 }
142 bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
144 if (bufsize == -1) /* Value was indeterminate */
145 bufsize = 16384; /* Should be more than enough */
146 buf = malloc(bufsize);
148 if (buf == NULL) {
149 perror("malloc");
150 exit(EXIT_FAILURE);
151 }
152 s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
154 if (result == NULL) {
155 if (s == 0)
156 printf("Not found\n");
157 else {
158 errno = s;
159 perror("getpwnam_r");
160 }
161 exit(EXIT_FAILURE);
162 }
163 printf("Name: %s; UID: %ld\n", pwd.pw_gecos, (long) pwd.pw_uid);
165 exit(EXIT_SUCCESS);
166 }
167
169 endpwent(3), fgetpwent(3), getgrnam(3), getpw(3), getpwent(3), getsp‐
170 nam(3), putpwent(3), setpwent(3), passwd(5)
171
173 This page is part of release 3.25 of the Linux man-pages project. A
174 description of the project, and information about reporting bugs, can
175 be found at http://www.kernel.org/doc/man-pages/.
176GNU 2009-03-30 GETPWNAM(3)