man3/getpwent_r.3

   1 .\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .TH GETPWENT_R 3 2003-11-15 "GNU" "Linux Programmer's Manual"
  24 .SH NAME
  25 getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
  26 .SH SYNOPSIS
  27 .nf
  28 .B "#define _GNU_SOURCE"
  29 .br
  30 .B #include <pwd.h>
  31 .sp
  32 .BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf ,
  33 .br
  34 .BI "               size_t " buflen ", struct passwd **" pwbufp );
  35 .sp
  36 .BI "int fgetpwent_r(FILE *" fp ", struct passwd *" pwbuf ", char *" buf ,
  37 .br
  38 .BI "                size_t " buflen ", struct passwd **" pwbufp );
  39 .SH DESCRIPTION
  40 The functions
  41 .BR getpwent_r ()
  42 and
  43 .BR fgetpwent_r ()
  44 are the reentrant versions of
  45 .BR getpwent (3)
  46 and
  47 .BR fgetpwent (3).
  48 The former reads the next passwd entry from the stream initialized by
  49 .BR setpwent (3).
  50 The latter reads the next passwd entry from the stream
  51 .I fp
  52 given as parameter.
  53 .PP
  54 The \fIpasswd\fP structure is defined in
  55 .I <pwd.h>
  56 as follows:
  57 .sp
  58 .RS
  59 .nf
  60 struct passwd {
  61     char    *pw_name;      /* user name */
  62     char    *pw_passwd;    /* user password */
  63     uid_t    pw_uid;       /* user ID */
  64     gid_t    pw_gid;       /* group ID */
  65     char    *pw_gecos;     /* real name */
  66     char    *pw_dir;       /* home directory */
  67     char    *pw_shell;     /* shell program */
  68 };
  69 .fi
  70 .RE
  71 .sp
  72 The non-reentrant functions return a pointer to static storage,
  73 where this static storage contains further pointers to user
  74 name, password, gecos field, home directory and shell.
  75 The reentrant functions described here return all of that in
  76 caller-provided buffers. First of all there is the buffer
  77 .I pwbuf
  78 that can hold a struct passwd. And next the buffer
  79 .I buf
  80 of size
  81 .I buflen
  82 that can hold additional strings.
  83 The result of these functions, the struct passwd read from the stream,
  84 is stored in the provided buffer
  85 .RI * pwbuf ,
  86 and a pointer to this struct passwd is returned in
  87 .RI * pwbufp .
  88 .SH "RETURN VALUE"
  89 On success, these functions return 0 and
  90 .RI * pwbufp
  91 is a pointer to the struct passwd.
  92 On error, these functions return an error value and
  93 .RI * pwbufp
  94 is NULL.
  95 .SH ERRORS
  96 .TP
  97 .B ENOENT
  98 No more entries.
  99 .TP
 100 .B ERANGE
 101 Insufficient buffer space supplied. Try again with larger buffer.
 102 .SH EXAMPLE
 103 .nf
 104 #define _GNU_SOURCE
 105 #include <pwd.h>
 106 #include <stdio.h>
 107 #define BUFLEN 4096
 108
 109 int
 110 main(void)
 111 {
 112     struct passwd pw, *pwp;
 113     char buf[BUFLEN];
 114     int i;
 115
 116     setpwent();
 117     while (1) {
 118         i = getpwent_r(&pw, buf, BUFLEN, &pwp);
 119         if (i)
 120             break;
 121         printf("%s (%d)\etHOME %s\etSHELL %s\en", pwp->pw_name,
 122                pwp->pw_uid, pwp->pw_dir, pwp->pw_shell);
 123     }
 124     endpwent();
 125     return 0;
 126 }
 127 .fi
 128 .\" perhaps add error checking - should use strerror_r
 129 .\" #include <errno.h>
 130 .\" #include <stdlib.h>
 131 .\"         if (i) {
 132 .\"               if (i == ENOENT)
 133 .\"                     break;
 134 .\"               printf("getpwent_r: %s", strerror(i));
 135 .\"               exit(1);
 136 .\"         }
 137 .SH "CONFORMING TO"
 138 These functions are GNU extensions, done in a style resembling
 139 the POSIX version of functions like
 140 .BR getpwnam_r (3).
 141 Other systems use prototype
 142 .sp
 143 .nf
 144 .in +4
 145 struct passwd *
 146 getpwent_r(struct passwd *pwd, char *buf, int buflen);
 147 .in
 148 .fi
 149 .sp
 150 or, better,
 151 .sp
 152 .nf
 153 .in +4
 154 int
 155 getpwent_r(struct passwd *pwd, char *buf, int buflen,
 156            FILE **pw_fp);
 157 .in
 158 .fi
 159 .SH NOTES
 160 The function
 161 .BR getpwent_r ()
 162 is not really reentrant since it shares the reading position
 163 in the stream with all other threads.
 164 .SH "SEE ALSO"
 165 .BR fgetpwent (3),
 166 .BR getpw (3),
 167 .BR getpwent (3),
 168 .BR getpwnam (3),
 169 .BR getpwuid (3),
 170 .BR putpwent (3),
 171 .BR passwd (5),
 172 .BR feature_test_macros (7)