man3/getpwnam.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" References consulted:
   8 .\"     Linux libc source code
   9 .\"     Lewine's "POSIX Programmer's Guide" (O'Reilly & Associates, 1991)
  10 .\"     386BSD man pages
  11 .\"
  12 .\" Modified 1993-07-24 by Rik Faith (faith@cs.unc.edu)
  13 .\" Modified 1996-05-27 by Martin Schulze (joey@linux.de)
  14 .\" Modified 2003-11-15 by aeb
  15 .\" 2008-11-07, mtk, Added an example program for getpwnam_r().
  16 .\"
  17 .TH GETPWNAM 3  2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  18 .SH NAME
  19 getpwnam, getpwnam_r, getpwuid, getpwuid_r \- get password file entry
  20 .SH LIBRARY
  21 Standard C library
  22 .RI ( libc ", " \-lc )
  23 .SH SYNOPSIS
  24 .nf
  25 .B #include <sys/types.h>
  26 .B #include <pwd.h>
  27 .PP
  28 .BI "struct passwd *getpwnam(const char *" name );
  29 .BI "struct passwd *getpwuid(uid_t " uid );
  30 .PP
  31 .BI "int getpwnam_r(const char *restrict " name \
  32 ", struct passwd *restrict " pwd ,
  33 .BI "               char *restrict " buf ", size_t " buflen ,
  34 .BI "               struct passwd **restrict " result );
  35 .BI "int getpwuid_r(uid_t " uid ", struct passwd *restrict " pwd ,
  36 .BI "               char *restrict " buf ", size_t " buflen ,
  37 .BI "               struct passwd **restrict " result );
  38 .fi
  39 .PP
  40 .RS -4
  41 Feature Test Macro Requirements for glibc (see
  42 .BR feature_test_macros (7)):
  43 .RE
  44 .PP
  45 .BR getpwnam_r (),
  46 .BR getpwuid_r ():
  47 .nf
  48     _POSIX_C_SOURCE
  49         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  50 .fi
  51 .SH DESCRIPTION
  52 The
  53 .BR getpwnam ()
  54 function returns a pointer to a structure containing
  55 the broken-out fields of the record in the password database
  56 (e.g., the local password file
  57 .IR /etc/passwd ,
  58 NIS, and LDAP)
  59 that matches the username
  60 .IR name .
  61 .PP
  62 The
  63 .BR getpwuid ()
  64 function returns a pointer to a structure containing
  65 the broken-out fields of the record in the password database
  66 that matches the user ID
  67 .IR uid .
  68 .PP
  69 The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
  70 .PP
  71 .in +4n
  72 .EX
  73 struct passwd {
  74     char   *pw_name;       /* username */
  75     char   *pw_passwd;     /* user password */
  76     uid_t   pw_uid;        /* user ID */
  77     gid_t   pw_gid;        /* group ID */
  78     char   *pw_gecos;      /* user information */
  79     char   *pw_dir;        /* home directory */
  80     char   *pw_shell;      /* shell program */
  81 };
  82 .EE
  83 .in
  84 .PP
  85 See
  86 .BR passwd (5)
  87 for more information about these fields.
  88 .PP
  89 The
  90 .BR getpwnam_r ()
  91 and
  92 .BR getpwuid_r ()
  93 functions obtain the same information as
  94 .BR getpwnam ()
  95 and
  96 .BR getpwuid (),
  97 but store the retrieved
  98 .I passwd
  99 structure in the space pointed to by
 100 .IR pwd .
 101 The string fields pointed to by the members of the
 102 .I passwd
 103 structure are stored in the buffer
 104 .I buf
 105 of size
 106 .IR buflen .
 107 A pointer to the result (in case of success) or NULL (in case no entry
 108 was found or an error occurred) is stored in
 109 .IR *result .
 110 .PP
 111 The call
 112 .PP
 113 .in +4n
 114 .EX
 115 sysconf(_SC_GETPW_R_SIZE_MAX)
 116 .EE
 117 .in
 118 .PP
 119 returns either \-1, without changing
 120 .IR errno ,
 121 or an initial suggested size for
 122 .IR buf .
 123 (If this size is too small,
 124 the call fails with
 125 .BR ERANGE ,
 126 in which case the caller can retry with a larger buffer.)
 127 .SH RETURN VALUE
 128 The
 129 .BR getpwnam ()
 130 and
 131 .BR getpwuid ()
 132 functions return a pointer to a
 133 .I passwd
 134 structure, or NULL if the matching entry is not found or
 135 an error occurs.
 136 If an error occurs,
 137 .I errno
 138 is set to indicate the error.
 139 If one wants to check
 140 .I errno
 141 after the call, it should be set to zero before the call.
 142 .PP
 143 The return value may point to a static area, and may be overwritten
 144 by subsequent calls to
 145 .BR getpwent (3),
 146 .BR getpwnam (),
 147 or
 148 .BR getpwuid ().
 149 (Do not pass the returned pointer to
 150 .BR free (3).)
 151 .PP
 152 On success,
 153 .BR getpwnam_r ()
 154 and
 155 .BR getpwuid_r ()
 156 return zero, and set
 157 .I *result
 158 to
 159 .IR pwd .
 160 If no matching password record was found,
 161 these functions return 0 and store NULL in
 162 .IR *result .
 163 In case of error, an error number is returned, and NULL is stored in
 164 .IR *result .
 165 .SH ERRORS
 166 .TP
 167 .BR 0 " or " ENOENT " or " ESRCH " or " EBADF " or " EPERM " or ..."
 168 The given
 169 .I name
 170 or
 171 .I uid
 172 was not found.
 173 .TP
 174 .B EINTR
 175 A signal was caught; see
 176 .BR signal (7).
 177 .TP
 178 .B EIO
 179 I/O error.
 180 .TP
 181 .B EMFILE
 182 The per-process limit on the number of open file descriptors has been reached.
 183 .TP
 184 .B ENFILE
 185 The system-wide limit on the total number of open files has been reached.
 186 .TP
 187 .B ENOMEM
 188 .\" not in POSIX
 189 Insufficient memory to allocate
 190 .I passwd
 191 structure.
 192 .\" This structure is static, allocated 0 or 1 times. No memory leak. (libc45)
 193 .TP
 194 .B ERANGE
 195 Insufficient buffer space supplied.
 196 .SH FILES
 197 .TP
 198 .I /etc/passwd
 199 local password database file
 200 .SH ATTRIBUTES
 201 For an explanation of the terms used in this section, see
 202 .BR attributes (7).
 203 .ad l
 204 .nh
 205 .TS
 206 allbox;
 207 lb lb lbx
 208 l l l.
 209 Interface       Attribute       Value
 210 T{
 211 .BR getpwnam ()
 212 T}      Thread safety   T{
 213 MT-Unsafe race:pwnam locale
 214 T}
 215 T{
 216 .BR getpwuid ()
 217 T}      Thread safety   T{
 218 MT-Unsafe race:pwuid locale
 219 T}
 220 T{
 221 .BR getpwnam_r (),
 222 .BR getpwuid_r ()
 223 T}      Thread safety   T{
 224 MT-Safe locale
 225 T}
 226 .TE
 227 .hy
 228 .ad
 229 .sp 1
 230 .SH STANDARDS
 231 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 232 The
 233 .I pw_gecos
 234 field is not specified in POSIX, but is present on most implementations.
 235 .SH NOTES
 236 The formulation given above under "RETURN VALUE" is from POSIX.1-2001.
 237 It does not call "not found" an error, and hence does not specify what value
 238 .I errno
 239 might have in this situation.
 240 But that makes it impossible to recognize
 241 errors.
 242 One might argue that according to POSIX
 243 .I errno
 244 should be left unchanged if an entry is not found.
 245 Experiments on various
 246 UNIX-like systems show that lots of different values occur in this
 247 situation: 0, ENOENT, EBADF, ESRCH, EWOULDBLOCK, EPERM, and probably others.
 248 .\" more precisely:
 249 .\" AIX 5.1 - gives ESRCH
 250 .\" OSF1 4.0g - gives EWOULDBLOCK
 251 .\" libc, glibc up to version 2.6, Irix 6.5 - give ENOENT
 252 .\" glibc since version 2.7 - give 0
 253 .\" FreeBSD 4.8, OpenBSD 3.2, NetBSD 1.6 - give EPERM
 254 .\" SunOS 5.8 - gives EBADF
 255 .\" Tru64 5.1b, HP-UX-11i, SunOS 5.7 - give 0
 256 .PP
 257 The
 258 .I pw_dir
 259 field contains the name of the initial working directory of the user.
 260 Login programs use the value of this field to initialize the
 261 .B HOME
 262 environment variable for the login shell.
 263 An application that wants to determine its user's home directory
 264 should inspect the value of
 265 .B HOME
 266 (rather than the value
 267 .IR getpwuid(getuid())\->pw_dir )
 268 since this allows the user to modify their notion of
 269 "the home directory" during a login session.
 270 To determine the (initial) home directory of another user,
 271 it is necessary to use
 272 .I getpwnam("username")\->pw_dir
 273 or similar.
 274 .SH EXAMPLES
 275 The program below demonstrates the use of
 276 .BR getpwnam_r ()
 277 to find the full username and user ID for the username
 278 supplied as a command-line argument.
 279 .PP
 280 .EX
 281 #include <pwd.h>
 282 #include <stdint.h>
 283 #include <stdio.h>
 284 #include <stdlib.h>
 285 #include <unistd.h>
 286 #include <errno.h>
 287
 288 int
 289 main(int argc, char *argv[])
 290 {
 291     struct passwd pwd;
 292     struct passwd *result;
 293     char *buf;
 294     long bufsize;
 295     int s;
 296
 297     if (argc != 2) {
 298         fprintf(stderr, "Usage: %s username\en", argv[0]);
 299         exit(EXIT_FAILURE);
 300     }
 301
 302     bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
 303     if (bufsize == \-1)          /* Value was indeterminate */
 304         bufsize = 16384;        /* Should be more than enough */
 305
 306     buf = malloc(bufsize);
 307     if (buf == NULL) {
 308         perror("malloc");
 309         exit(EXIT_FAILURE);
 310     }
 311
 312     s = getpwnam_r(argv[1], &pwd, buf, bufsize, &result);
 313     if (result == NULL) {
 314         if (s == 0)
 315             printf("Not found\en");
 316         else {
 317             errno = s;
 318             perror("getpwnam_r");
 319         }
 320         exit(EXIT_FAILURE);
 321     }
 322
 323     printf("Name: %s; UID: %jd\en", pwd.pw_gecos,
 324             (intmax_t) pwd.pw_uid);
 325     exit(EXIT_SUCCESS);
 326 }
 327 .EE
 328 .SH SEE ALSO
 329 .BR endpwent (3),
 330 .BR fgetpwent (3),
 331 .BR getgrnam (3),
 332 .BR getpw (3),
 333 .BR getpwent (3),
 334 .BR getspnam (3),
 335 .BR putpwent (3),
 336 .BR setpwent (3),
 337 .BR passwd (5)