diff options
| author | Alejandro Colomar <alx.manpages@gmail.com> | 2022-09-05 23:03:38 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx.manpages@gmail.com> | 2022-09-05 23:03:47 +0200 |
| commit | 70ac1c4785fc1e158ab2349a962dba2526bf4fbc (patch) | |
| tree | bff270e2496dd284bccfc1271b43946f5d225224 /man/man3/getpwent.3 | |
| parent | 5423a6f86b2b920a5f3e8cf8d759b513050f2d33 (diff) | |
| download | man-pages-70ac1c4785fc1e158ab2349a962dba2526bf4fbc.tar.gz | |
src.mk, All pages: Move man* to man/
The root of the repository is becoming a bit overpopulated and
unorganized, due to the recent addition of more mandirs, and more
informative and configuration files too. Let's create a specific
mandir <man/> that contains the mandirs <man[1-8]*>.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Diffstat (limited to 'man/man3/getpwent.3')
| -rw-r--r-- | man/man3/getpwent.3 | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/man/man3/getpwent.3 b/man/man3/getpwent.3 new file mode 100644 index 0000000000..b46827b0c2 --- /dev/null +++ b/man/man3/getpwent.3 @@ -0,0 +1,183 @@ +.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" References consulted: +.\" Linux libc source code +.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) +.\" 386BSD man pages +.\" +.\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon May 27 21:37:47 1996 by Martin Schulze (joey@linux.de) +.\" +.TH GETPWENT 3 2021-03-22 "Linux man-pages (unreleased)" +.SH NAME +getpwent, setpwent, endpwent \- get password file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <pwd.h> +.PP +.B struct passwd *getpwent(void); +.B void setpwent(void); +.B void endpwent(void); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR getpwent (), +.BR setpwent (), +.BR endpwent (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Glibc since 2.19: */ _DEFAULT_SOURCE + || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getpwent () +function returns a pointer to a structure containing +the broken-out fields of a record from the password database +(e.g., the local password file +.IR /etc/passwd , +NIS, and LDAP). +The first time +.BR getpwent () +is called, it returns the first entry; thereafter, it returns successive +entries. +.PP +The +.BR setpwent () +function rewinds to the beginning +of the password database. +.PP +The +.BR endpwent () +function is used to close the password database +after all processing has been performed. +.PP +The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows: +.PP +.in +4n +.EX +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 */ +}; +.EE +.in +.PP +For more information about the fields of this structure, see +.BR passwd (5). +.SH RETURN VALUE +The +.BR getpwent () +function returns a pointer to a +.I passwd +structure, or NULL if +there are no more entries or an error occurred. +If an error occurs, +.I errno +is set to indicate the error. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.PP +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getpwent (), +.BR getpwnam (3), +or +.BR getpwuid (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EINTR +A signal was caught; see +.BR signal (7). +.TP +.B EIO +I/O error. +.TP +.B EMFILE +The per-process limit on the number of open file descriptors has been reached. +.TP +.B ENFILE +The system-wide limit on the total number of open files has been reached. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I passwd +structure. +.\" to allocate the passwd structure, or to allocate buffers +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/passwd +local password database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.ad l +.nh +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.BR getpwent () +T} Thread safety T{ +MT-Unsafe race:pwent +race:pwentbuf locale +T} +T{ +.BR setpwent (), +.BR endpwent () +T} Thread safety T{ +MT-Unsafe race:pwent locale +T} +.TE +.hy +.ad +.sp 1 +In the above table, +.I pwent +in +.I race:pwent +signifies that if any of the functions +.BR setpwent (), +.BR getpwent (), +or +.BR endpwent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2001, POSIX.1-2008, SVr4, 4.3BSD. +The +.I pw_gecos +field is not specified in POSIX, but is present on most implementations. +.SH SEE ALSO +.BR fgetpwent (3), +.BR getpw (3), +.BR getpwent_r (3), +.BR getpwnam (3), +.BR getpwuid (3), +.BR putpwent (3), +.BR passwd (5) |