diff options
Diffstat (limited to 'man/man3/getgrent_r.3')
| -rw-r--r-- | man/man3/getgrent_r.3 | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/man/man3/getgrent_r.3 b/man/man3/getgrent_r.3 new file mode 100644 index 000000000..6c3018787 --- /dev/null +++ b/man/man3/getgrent_r.3 @@ -0,0 +1,228 @@ +'\" t +.\" Copyright (c) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH getgrent_r 3 (date) "Linux man-pages (unreleased)" +.SH NAME +getgrent_r, fgetgrent_r \- get group file entry reentrantly +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <grp.h> +.P +.BI "int getgrent_r(struct group *restrict " gbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " gbufp ); +.BI "int fgetgrent_r(FILE *restrict " stream ", struct group *restrict " gbuf , +.BI " char " buf "[restrict ." buflen "], size_t " buflen , +.BI " struct group **restrict " gbufp ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getgrent_r (): +.nf + _GNU_SOURCE +.fi +.\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug? +.P +.BR fgetgrent_r (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _SVID_SOURCE +.fi +.SH DESCRIPTION +The functions +.BR getgrent_r () +and +.BR fgetgrent_r () +are the reentrant versions of +.BR getgrent (3) +and +.BR fgetgrent (3). +The former reads the next group entry from the stream initialized by +.BR setgrent (3). +The latter reads the next group entry from +.IR stream . +.P +The \fIgroup\fP structure is defined in +.I <grp.h> +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). +.P +The nonreentrant functions return a pointer to static storage, +where this static storage contains further pointers to group +name, password, and members. +The reentrant functions described here return all of that in +caller-provided buffers. +First of all there is the buffer +.I gbuf +that can hold a \fIstruct group\fP. +And next the buffer +.I buf +of size +.I buflen +that can hold additional strings. +The result of these functions, the \fIstruct group\fP read from the stream, +is stored in the provided buffer +.IR *gbuf , +and a pointer to this \fIstruct group\fP is returned in +.IR *gbufp . +.SH RETURN VALUE +On success, these functions return 0 and +.I *gbufp +is a pointer to the \fIstruct group\fP. +On error, these functions return an error value and +.I *gbufp +is NULL. +.SH ERRORS +.TP +.B ENOENT +No more entries. +.TP +.B ERANGE +Insufficient buffer space supplied. +Try again with larger buffer. +.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_r () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:grent locale +T} +T{ +.na +.nh +.BR fgetgrent_r () +T} Thread safety T{ +.na +.nh +MT-Safe +T} +.TE +.P +In the above table, +.I grent +in +.I race:grent +signifies that if any of the functions +.BR setgrent (3), +.BR getgrent (3), +.BR endgrent (3), +or +.BR getgrent_r () +are used in parallel in different threads of a program, +then data races could occur. +.SH VERSIONS +Other systems use the prototype +.P +.in +4n +.EX +struct group *getgrent_r(struct group *grp, char *buf, + int buflen); +.EE +.in +.P +or, better, +.P +.in +4n +.EX +int getgrent_r(struct group *grp, char *buf, int buflen, + FILE **gr_fp); +.EE +.in +.SH STANDARDS +GNU. +.SH HISTORY +These functions are done in a style resembling +the POSIX version of functions like +.BR getpwnam_r (3). +.SH NOTES +The function +.BR getgrent_r () +is not really reentrant since it shares the reading position +in the stream with all other threads. +.SH EXAMPLES +.\" SRC BEGIN (getgrent_r.c) +.EX +#define _GNU_SOURCE +#include <grp.h> +#include <stdint.h> +#include <stdio.h> +#include <stdlib.h> +#define BUFLEN 4096 +\& +int +main(void) +{ + struct group grp; + struct group *grpp; + char buf[BUFLEN]; + int i; +\& + setgrent(); + while (1) { + i = getgrent_r(&grp, buf, sizeof(buf), &grpp); + if (i) + break; + printf("%s (%jd):", grpp\->gr_name, (intmax_t) grpp\->gr_gid); + for (size_t j = 0; ; j++) { + if (grpp\->gr_mem[j] == NULL) + break; + printf(" %s", grpp\->gr_mem[j]); + } + printf("\en"); + } + endgrent(); + exit(EXIT_SUCCESS); +} +.EE +.\" perhaps add error checking - should use strerror_r +.\" #include <errno.h> +.\" #include <stdlib.h> +.\" if (i) { +.\" if (i == ENOENT) +.\" break; +.\" printf("getgrent_r: %s", strerror(i)); +.\" exit(EXIT_FAILURE); +.\" } +.\" SRC END +.SH SEE ALSO +.BR fgetgrent (3), +.BR getgrent (3), +.BR getgrgid (3), +.BR getgrnam (3), +.BR putgrent (3), +.BR group (5) |