man3/getpwent_r.3

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