man3/getpwent_r.3

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