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