man3/getpwent_r.3

   1 '\" t
   2 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH getpwent_r 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <pwd.h>
  15 .P
  16 .BI "int getpwent_r(struct passwd *restrict " pwbuf ,
  17 .BI "               char " buf "[restrict ." buflen "], size_t " buflen ,
  18 .BI "               struct passwd **restrict " pwbufp );
  19 .BI "int fgetpwent_r(FILE *restrict " stream \
  20 ", struct passwd *restrict " pwbuf ,
  21 .BI "               char " buf "[restrict ." buflen "], size_t " buflen ,
  22 .BI "               struct passwd **restrict " pwbufp );
  23 .fi
  24 .P
  25 .RS -4
  26 Feature Test Macro Requirements for glibc (see
  27 .BR feature_test_macros (7)):
  28 .RE
  29 .P
  30 .BR getpwent_r (),
  31 .nf
  32     Since glibc 2.19:
  33         _DEFAULT_SOURCE
  34     glibc 2.19 and earlier:
  35         _BSD_SOURCE || _SVID_SOURCE
  36 .fi
  37 .P
  38 .BR fgetpwent_r ():
  39 .nf
  40     Since glibc 2.19:
  41         _DEFAULT_SOURCE
  42     glibc 2.19 and earlier:
  43         _SVID_SOURCE
  44 .fi
  45 .SH DESCRIPTION
  46 The functions
  47 .BR getpwent_r ()
  48 and
  49 .BR fgetpwent_r ()
  50 are the reentrant versions of
  51 .BR getpwent (3)
  52 and
  53 .BR fgetpwent (3).
  54 The former reads the next passwd entry from the stream initialized by
  55 .BR setpwent (3).
  56 The latter reads the next passwd entry from
  57 .IR stream .
  58 .P
  59 The \fIpasswd\fP structure is defined in
  60 .I <pwd.h>
  61 as follows:
  62 .P
  63 .in +4n
  64 .EX
  65 struct passwd {
  66     char    *pw_name;      /* username */
  67     char    *pw_passwd;    /* user password */
  68     uid_t    pw_uid;       /* user ID */
  69     gid_t    pw_gid;       /* group ID */
  70     char    *pw_gecos;     /* user information */
  71     char    *pw_dir;       /* home directory */
  72     char    *pw_shell;     /* shell program */
  73 };
  74 .EE
  75 .in
  76 .P
  77 For more information about the fields of this structure, see
  78 .BR passwd (5).
  79 .P
  80 The nonreentrant functions return a pointer to static storage,
  81 where this static storage contains further pointers to user
  82 name, password, gecos field, home directory and shell.
  83 The reentrant functions described here return all of that in
  84 caller-provided buffers.
  85 First of all there is the buffer
  86 .I pwbuf
  87 that can hold a \fIstruct passwd\fP.
  88 And next the buffer
  89 .I buf
  90 of size
  91 .I buflen
  92 that can hold additional strings.
  93 The result of these functions, the \fIstruct passwd\fP read from the stream,
  94 is stored in the provided buffer
  95 .IR *pwbuf ,
  96 and a pointer to this \fIstruct passwd\fP is returned in
  97 .IR *pwbufp .
  98 .SH RETURN VALUE
  99 On success, these functions return 0 and
 100 .I *pwbufp
 101 is a pointer to the \fIstruct passwd\fP.
 102 On error, these functions return an error value and
 103 .I *pwbufp
 104 is NULL.
 105 .SH ERRORS
 106 .TP
 107 .B ENOENT
 108 No more entries.
 109 .TP
 110 .B ERANGE
 111 Insufficient buffer space supplied.
 112 Try again with larger buffer.
 113 .SH ATTRIBUTES
 114 For an explanation of the terms used in this section, see
 115 .BR attributes (7).
 116 .TS
 117 allbox;
 118 lb lb lbx
 119 l l l.
 120 Interface       Attribute       Value
 121 T{
 122 .na
 123 .nh
 124 .BR getpwent_r ()
 125 T}      Thread safety   T{
 126 .na
 127 .nh
 128 MT-Unsafe race:pwent locale
 129 T}
 130 T{
 131 .na
 132 .nh
 133 .BR fgetpwent_r ()
 134 T}      Thread safety   MT-Safe
 135 .TE
 136 .P
 137 In the above table,
 138 .I pwent
 139 in
 140 .I race:pwent
 141 signifies that if any of the functions
 142 .BR setpwent (),
 143 .BR getpwent (),
 144 .BR endpwent (),
 145 or
 146 .BR getpwent_r ()
 147 are used in parallel in different threads of a program,
 148 then data races could occur.
 149 .SH VERSIONS
 150 Other systems use the prototype
 151 .P
 152 .in +4n
 153 .EX
 154 struct passwd *
 155 getpwent_r(struct passwd *pwd, char *buf, int buflen);
 156 .EE
 157 .in
 158 .P
 159 or, better,
 160 .P
 161 .in +4n
 162 .EX
 163 int
 164 getpwent_r(struct passwd *pwd, char *buf, int buflen,
 165            FILE **pw_fp);
 166 .EE
 167 .in
 168 .SH STANDARDS
 169 None.
 170 .SH HISTORY
 171 These functions are done in a style resembling
 172 the POSIX version of functions like
 173 .BR getpwnam_r (3).
 174 .SH NOTES
 175 The function
 176 .BR getpwent_r ()
 177 is not really reentrant since it shares the reading position
 178 in the stream with all other threads.
 179 .SH EXAMPLES
 180 .\" SRC BEGIN (getpwent_r.c)
 181 .EX
 182 #define _GNU_SOURCE
 183 #include <pwd.h>
 184 #include <stdint.h>
 185 #include <stdio.h>
 186 #include <stdlib.h>
 187 \&
 188 #define BUFLEN 4096
 189 \&
 190 int
 191 main(void)
 192 {
 193     struct passwd pw;
 194     struct passwd *pwp;
 195     char buf[BUFLEN];
 196     int i;
 197 \&
 198     setpwent();
 199     while (1) {
 200         i = getpwent_r(&pw, buf, sizeof(buf), &pwp);
 201         if (i)
 202             break;
 203         printf("%s (%jd)\etHOME %s\etSHELL %s\en", pwp\->pw_name,
 204                (intmax_t) pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell);
 205     }
 206     endpwent();
 207     exit(EXIT_SUCCESS);
 208 }
 209 .EE
 210 .\" perhaps add error checking - should use strerror_r
 211 .\" #include <errno.h>
 212 .\" #include <stdlib.h>
 213 .\"         if (i) {
 214 .\"               if (i == ENOENT)
 215 .\"                     break;
 216 .\"               printf("getpwent_r: %s", strerror(i));
 217 .\"               exit(EXIT_SUCCESS);
 218 .\"         }
 219 .\" SRC END
 220 .SH SEE ALSO
 221 .BR fgetpwent (3),
 222 .BR getpw (3),
 223 .BR getpwent (3),
 224 .BR getpwnam (3),
 225 .BR getpwuid (3),
 226 .BR putpwent (3),
 227 .BR passwd (5)