man3/getpwent.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\"
  10 .\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de)
  12 .\"
  13 .TH GETPWENT 3  2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  14 .SH NAME
  15 getpwent, setpwent, endpwent \- get password file entry
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/types.h>
  22 .B #include <pwd.h>
  23 .PP
  24 .B struct passwd *getpwent(void);
  25 .B void setpwent(void);
  26 .B void endpwent(void);
  27 .fi
  28 .PP
  29 .RS -4
  30 Feature Test Macro Requirements for glibc (see
  31 .BR feature_test_macros (7)):
  32 .RE
  33 .PP
  34 .BR getpwent (),
  35 .BR setpwent (),
  36 .BR endpwent ():
  37 .nf
  38     _XOPEN_SOURCE >= 500
  39 .\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
  40         || /* Glibc since 2.19: */ _DEFAULT_SOURCE
  41         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  42 .fi
  43 .SH DESCRIPTION
  44 The
  45 .BR getpwent ()
  46 function returns a pointer to a structure containing
  47 the broken-out fields of a record from the password database
  48 (e.g., the local password file
  49 .IR /etc/passwd ,
  50 NIS, and LDAP).
  51 The first time
  52 .BR getpwent ()
  53 is called, it returns the first entry; thereafter, it returns successive
  54 entries.
  55 .PP
  56 The
  57 .BR setpwent ()
  58 function rewinds to the beginning
  59 of the password database.
  60 .PP
  61 The
  62 .BR endpwent ()
  63 function is used to close the password database
  64 after all processing has been performed.
  65 .PP
  66 The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
  67 .PP
  68 .in +4n
  69 .EX
  70 struct passwd {
  71     char   *pw_name;       /* username */
  72     char   *pw_passwd;     /* user password */
  73     uid_t   pw_uid;        /* user ID */
  74     gid_t   pw_gid;        /* group ID */
  75     char   *pw_gecos;      /* user information */
  76     char   *pw_dir;        /* home directory */
  77     char   *pw_shell;      /* shell program */
  78 };
  79 .EE
  80 .in
  81 .PP
  82 For more information about the fields of this structure, see
  83 .BR passwd (5).
  84 .SH RETURN VALUE
  85 The
  86 .BR getpwent ()
  87 function returns a pointer to a
  88 .I passwd
  89 structure, or NULL if
  90 there are no more entries or an error occurred.
  91 If an error occurs,
  92 .I errno
  93 is set to indicate the error.
  94 If one wants to check
  95 .I errno
  96 after the call, it should be set to zero before the call.
  97 .PP
  98 The return value may point to a static area, and may be overwritten
  99 by subsequent calls to
 100 .BR getpwent (),
 101 .BR getpwnam (3),
 102 or
 103 .BR getpwuid (3).
 104 (Do not pass the returned pointer to
 105 .BR free (3).)
 106 .SH ERRORS
 107 .TP
 108 .B EINTR
 109 A signal was caught; see
 110 .BR signal (7).
 111 .TP
 112 .B EIO
 113 I/O error.
 114 .TP
 115 .B EMFILE
 116 The per-process limit on the number of open file descriptors has been reached.
 117 .TP
 118 .B ENFILE
 119 The system-wide limit on the total number of open files has been reached.
 120 .TP
 121 .B ENOMEM
 122 .\" not in POSIX
 123 Insufficient memory to allocate
 124 .I passwd
 125 structure.
 126 .\" to allocate the passwd structure, or to allocate buffers
 127 .TP
 128 .B ERANGE
 129 Insufficient buffer space supplied.
 130 .SH FILES
 131 .TP
 132 .I /etc/passwd
 133 local password database file
 134 .SH ATTRIBUTES
 135 For an explanation of the terms used in this section, see
 136 .BR attributes (7).
 137 .ad l
 138 .nh
 139 .TS
 140 allbox;
 141 lb lb lbx
 142 l l l.
 143 Interface       Attribute       Value
 144 T{
 145 .BR getpwent ()
 146 T}      Thread safety   T{
 147 MT-Unsafe race:pwent
 148 race:pwentbuf locale
 149 T}
 150 T{
 151 .BR setpwent (),
 152 .BR endpwent ()
 153 T}      Thread safety   T{
 154 MT-Unsafe race:pwent locale
 155 T}
 156 .TE
 157 .hy
 158 .ad
 159 .sp 1
 160 In the above table,
 161 .I pwent
 162 in
 163 .I race:pwent
 164 signifies that if any of the functions
 165 .BR setpwent (),
 166 .BR getpwent (),
 167 or
 168 .BR endpwent ()
 169 are used in parallel in different threads of a program,
 170 then data races could occur.
 171 .SH STANDARDS
 172 POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD.
 173 The
 174 .I pw_gecos
 175 field is not specified in POSIX, but is present on most implementations.
 176 .SH SEE ALSO
 177 .BR fgetpwent (3),
 178 .BR getpw (3),
 179 .BR getpwent_r (3),
 180 .BR getpwnam (3),
 181 .BR getpwuid (3),
 182 .BR putpwent (3),
 183 .BR passwd (5)