+++ /dev/null
-.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
-.\"
-.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
-.\" This is free documentation; you can redistribute it and/or
-.\" modify it under the terms of the GNU General Public License as
-.\" published by the Free Software Foundation; either version 2 of
-.\" the License, or (at your option) any later version.
-.\"
-.\" The GNU General Public License's references to "object code"
-.\" and "executables" are to be interpreted as the output of any
-.\" document formatting or typesetting system, including
-.\" intermediate and printed output.
-.\"
-.\" This manual is distributed in the hope that it will be useful,
-.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
-.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-.\" GNU General Public License for more details.
-.\"
-.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, see
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
-.\"
-.TH GETPWENT_R 3 2015-01-22 "GNU" "Linux Programmer's Manual"
-.SH NAME
-getpwent_r, fgetpwent_r \- get passwd file entry reentrantly
-.SH SYNOPSIS
-.nf
-.B #include <pwd.h>
-.sp
-.BI "int getpwent_r(struct passwd *" pwbuf ", char *" buf ,
-.br
-.BI " size_t " buflen ", struct passwd **" pwbufp );
-.sp
-.BI "int fgetpwent_r(FILE *" stream ", struct passwd *" pwbuf ", char *" buf ,
-.br
-.BI " size_t " buflen ", struct passwd **" pwbufp );
-.fi
-.sp
-.in -4n
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.sp
-.BR getpwent_r (),
-_BSD_SOURCE || _SVID_SOURCE
-.br
-.BR fgetpwent_r ():
-_SVID_SOURCE
-.SH DESCRIPTION
-The functions
-.BR getpwent_r ()
-and
-.BR fgetpwent_r ()
-are the reentrant versions of
-.BR getpwent (3)
-and
-.BR fgetpwent (3).
-The former reads the next passwd entry from the stream initialized by
-.BR setpwent (3).
-The latter reads the next passwd entry from
-.IR stream .
-.PP
-The \fIpasswd\fP structure is defined in
-.I <pwd.h>
-as follows:
-.sp
-.in +4n
-.nf
-struct passwd {
- char *pw_name; /* username */
- char *pw_passwd; /* user password */
- uid_t pw_uid; /* user ID */
- gid_t pw_gid; /* group ID */
- char *pw_gecos; /* user information */
- char *pw_dir; /* home directory */
- char *pw_shell; /* shell program */
-};
-.fi
-.in
-.PP
-For more information about the fields of this structure, see
-.BR passwd (5).
-
-The nonreentrant functions return a pointer to static storage,
-where this static storage contains further pointers to user
-name, password, gecos field, home directory and shell.
-The reentrant functions described here return all of that in
-caller-provided buffers.
-First of all there is the buffer
-.I pwbuf
-that can hold a \fIstruct passwd\fP.
-And next the buffer
-.I buf
-of size
-.I buflen
-that can hold additional strings.
-The result of these functions, the \fIstruct passwd\fP read from the stream,
-is stored in the provided buffer
-.IR *pwbuf ,
-and a pointer to this \fIstruct passwd\fP is returned in
-.IR *pwbufp .
-.SH RETURN VALUE
-On success, these functions return 0 and
-.I *pwbufp
-is a pointer to the \fIstruct passwd\fP.
-On error, these functions return an error value and
-.I *pwbufp
-is NULL.
-.SH ERRORS
-.TP
-.B ENOENT
-No more entries.
-.TP
-.B ERANGE
-Insufficient buffer space supplied.
-Try again with larger buffer.
-.SH CONFORMING TO
-These functions are GNU extensions, done in a style resembling
-the POSIX version of functions like
-.BR getpwnam_r (3).
-Other systems use the prototype
-.sp
-.nf
-.in +4n
-struct passwd *
-getpwent_r(struct passwd *pwd, char *buf, int buflen);
-.in
-.fi
-.sp
-or, better,
-.sp
-.nf
-.in +4n
-int
-getpwent_r(struct passwd *pwd, char *buf, int buflen,
- FILE **pw_fp);
-.in
-.fi
-.SH NOTES
-The function
-.BR getpwent_r ()
-is not really reentrant since it shares the reading position
-in the stream with all other threads.
-.SH EXAMPLE
-.nf
-#define _GNU_SOURCE
-#include <pwd.h>
-#include <stdio.h>
-#define BUFLEN 4096
-
-int
-main(void)
-{
- struct passwd pw, *pwp;
- char buf[BUFLEN];
- int i;
-
- setpwent();
- while (1) {
- i = getpwent_r(&pw, buf, BUFLEN, &pwp);
- if (i)
- break;
- printf("%s (%d)\etHOME %s\etSHELL %s\en", pwp\->pw_name,
- pwp\->pw_uid, pwp\->pw_dir, pwp\->pw_shell);
- }
- endpwent();
- exit(EXIT_SUCCESS);
-}
-.fi
-.\" perhaps add error checking - should use strerror_r
-.\" #include <errno.h>
-.\" #include <stdlib.h>
-.\" if (i) {
-.\" if (i == ENOENT)
-.\" break;
-.\" printf("getpwent_r: %s", strerror(i));
-.\" exit(EXIT_SUCCESS);
-.\" }
-.SH SEE ALSO
-.BR fgetpwent (3),
-.BR getpw (3),
-.BR getpwent (3),
-.BR getpwnam (3),
-.BR getpwuid (3),
-.BR putpwent (3),
-.BR passwd (5)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
