diff options
Diffstat (limited to 'man/man3/getgrent.3')
| -rw-r--r-- | man/man3/getgrent.3 | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/man/man3/getgrent.3 b/man/man3/getgrent.3 new file mode 100644 index 000000000..16b41ff8b --- /dev/null +++ b/man/man3/getgrent.3 @@ -0,0 +1,206 @@ +'\" t +.\" 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:29:54 1993 by Rik Faith (faith@cs.unc.edu) +.TH getgrent 3 (date) "Linux man-pages (unreleased)" +.SH NAME +getgrent, setgrent, endgrent \- get group file entry +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/types.h> +.B #include <grp.h> +.P +.B struct group *getgrent(void); +.P +.B void setgrent(void); +.B void endgrent(void); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setgrent (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* glibc >= 2.19: */ _DEFAULT_SOURCE + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.P +.BR getgrent (), +.BR endgrent (): +.nf + Since glibc 2.22: + _XOPEN_SOURCE >= 500 || _DEFAULT_SOURCE +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + glibc 2.21 and earlier + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE +.fi +.SH DESCRIPTION +The +.BR getgrent () +function returns a pointer to a structure containing +the broken-out fields of a record in the group database +(e.g., the local group file +.IR /etc/group , +NIS, and LDAP). +The first time +.BR getgrent () +is called, +it returns the first entry; thereafter, it returns successive entries. +.P +The +.BR setgrent () +function rewinds to the beginning +of the group database, to allow repeated scans. +.P +The +.BR endgrent () +function is used to close the group database +after all processing has been performed. +.P +The \fIgroup\fP structure is defined in \fI<grp.h>\fP as follows: +.P +.in +4n +.EX +struct group { + char *gr_name; /* group name */ + char *gr_passwd; /* group password */ + gid_t gr_gid; /* group ID */ + char **gr_mem; /* NULL\-terminated array of pointers + to names of group members */ +}; +.EE +.in +.P +For more information about the fields of this structure, see +.BR group (5). +.SH RETURN VALUE +The +.BR getgrent () +function returns a pointer to a +.I group +structure, +or NULL if there are no more entries or an error occurs. +.P +Upon error, +.I errno +may be set. +If one wants to check +.I errno +after the call, it should be set to zero before the call. +.P +The return value may point to a static area, and may be overwritten +by subsequent calls to +.BR getgrent (), +.BR getgrgid (3), +or +.BR getgrnam (3). +(Do not pass the returned pointer to +.BR free (3).) +.SH ERRORS +.TP +.B EAGAIN +The service was temporarily unavailable; try again later. +For NSS backends in glibc +this indicates a temporary error talking to the backend. +The error may correct itself, retrying later is suggested. +.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 +.\" not in POSIX +.B ENOENT +A necessary input file cannot be found. +For NSS backends in glibc +this indicates the backend is not correctly configured. +.TP +.B ENOMEM +.\" not in POSIX +Insufficient memory to allocate +.I group +structure. +.TP +.B ERANGE +Insufficient buffer space supplied. +.SH FILES +.TP +.I /etc/group +local group database file +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent +race:grentbuf locale +T} +T{ +.na +.nh +.BR setgrent (), +.BR endgrent () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent locale +T} +.TE +.P +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (), +.BR getgrent (), +or +.BR endgrent () +are used in parallel in different threads of a program, +then data races could occur. +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001, SVr4, 4.3BSD. +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent_r (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR getgrouplist (3), +.BR putgrent (3), +.BR group (5) |