1getpwnam(3)                Library Functions Manual                getpwnam(3)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/types.h>
13       #include <pwd.h>
14
15       struct passwd *getpwnam(const char *name);
16       struct passwd *getpwuid(uid_t uid);
17
18       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
25   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
26
27       getpwnam_r(), getpwuid_r():
28           _POSIX_C_SOURCE
29               || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
30

DESCRIPTION

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
37       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
41       The passwd structure is defined in <pwd.h> as follows:
42
43           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
53       See passwd(5) for more information about these fields.
54
55       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
62       The call
63
64           sysconf(_SC_GETPW_R_SIZE_MAX)
65
66       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

RETURN VALUE

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
77       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
81       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

ERRORS

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

FILES

105       /etc/passwd
106              local password database file
107

ATTRIBUTES

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

VERSIONS

124       The pw_gecos field is not specified in POSIX, but is  present  on  most
125       implementations.
126

STANDARDS

128       POSIX.1-2008.
129

HISTORY

131       POSIX.1-2001, SVr4, 4.3BSD.
132

NOTES

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
143       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

EXAMPLES

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
157       #include <errno.h>
158       #include <pwd.h>
159       #include <stdint.h>
160       #include <stdio.h>
161       #include <stdlib.h>
162       #include <unistd.h>
163
164       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
173           if (argc != 2) {
174               fprintf(stderr, "Usage: %s username\n", argv[0]);
175               exit(EXIT_FAILURE);
176           }
177
178           bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
179           if (bufsize == -1)          /* Value was indeterminate */
180               bufsize = 16384;        /* Should be more than enough */
181
182           buf = malloc(bufsize);
183           if (buf == NULL) {
184               perror("malloc");
185               exit(EXIT_FAILURE);
186           }
187
188           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
199           printf("Name: %s; UID: %jd\n", pwd.pw_gecos,
200                  (intmax_t) pwd.pw_uid);
201           exit(EXIT_SUCCESS);
202       }
203

SEE ALSO

205       endpwent(3),  fgetpwent(3),  getgrnam(3), getpw(3), getpwent(3), getsp‐
206       nam(3), putpwent(3), setpwent(3), passwd(5)
207
208
209
210Linux man-pages 6.04              2023-03-30                       getpwnam(3)
Impressum