mirror of https://github.com/mkerrisk/man-pages
185 lines
4.6 KiB
Groff
185 lines
4.6 KiB
Groff
.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl)
|
|
.\"
|
|
.\" 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, write to the Free
|
|
.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
|
|
.\" USA.
|
|
.\"
|
|
.TH GETPWENT_R 3 2007-07-26 "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 *" fp ", 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 the stream
|
|
.I fp
|
|
given as parameter.
|
|
.PP
|
|
The \fIpasswd\fP structure is defined in
|
|
.I <pwd.h>
|
|
as follows:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
struct passwd {
|
|
char *pw_name; /* user name */
|
|
char *pw_passwd; /* user password */
|
|
uid_t pw_uid; /* user ID */
|
|
gid_t pw_gid; /* group ID */
|
|
char *pw_gecos; /* real name */
|
|
char *pw_dir; /* home directory */
|
|
char *pw_shell; /* shell program */
|
|
};
|
|
.fi
|
|
.in
|
|
.sp
|
|
The non-reentrant 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 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)
|