2004-11-03 13:51:07 +00:00
|
|
|
.\" 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.
|
|
|
|
.\"
|
2007-12-10 09:07:03 +00:00
|
|
|
.TH GETGRENT_R 3 2007-07-26 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
getgrent_r, fgetgrent_r \- get group file entry reentrantly
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <grp.h>
|
|
|
|
.sp
|
|
|
|
.BI "int getgrent_r(struct group *" gbuf ", char *" buf ,
|
|
|
|
.br
|
|
|
|
.BI " size_t " buflen ", struct group **" gbufp );
|
|
|
|
.sp
|
|
|
|
.BI "int fgetgrent_r(FILE *" fp ", struct group *" gbuf ", char *" buf ,
|
|
|
|
.br
|
|
|
|
.BI " size_t " buflen ", struct group **" gbufp );
|
2007-07-08 12:11:40 +00:00
|
|
|
.fi
|
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.sp
|
|
|
|
.BR getgrent_r ():
|
|
|
|
_GNU_SOURCE
|
|
|
|
.\" FIXME . The FTM requirements seem inconsistent here. File a glibc bug?
|
|
|
|
.br
|
|
|
|
.BR fgetgrent_r ():
|
|
|
|
_SVID_SOURCE
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The functions
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR getgrent_r ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 07:07:02 +00:00
|
|
|
.BR fgetgrent_r ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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 the stream
|
2008-07-10 20:27:50 +00:00
|
|
|
.IR fp .
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The \fIgroup\fP structure is defined in
|
|
|
|
.I <grp.h>
|
|
|
|
as follows:
|
|
|
|
.sp
|
2007-12-19 06:16:04 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
|
|
|
struct group {
|
2007-12-19 05:53:30 +00:00
|
|
|
char *gr_name; /* group name */
|
|
|
|
char *gr_passwd; /* group password */
|
|
|
|
gid_t gr_gid; /* group ID */
|
|
|
|
char **gr_mem; /* group members */
|
2004-11-03 13:51:07 +00:00
|
|
|
};
|
|
|
|
.fi
|
2007-12-19 06:16:04 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.sp
|
getgrent_r.3, gethostbyname.3, getmntent.3, getnetent_r.3, getprotoent_r.3, getpwent_r.3, getrpcent_r.3, getservent_r.3, getspnam.3: Global fix: s/non-reentrant/nonrentrant/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:55:51 +00:00
|
|
|
The nonreentrant functions return a pointer to static storage,
|
2004-11-03 13:51:07 +00:00
|
|
|
where this static storage contains further pointers to group
|
|
|
|
name, password and members.
|
|
|
|
The reentrant functions described here return all of that in
|
2007-04-12 22:42:49 +00:00
|
|
|
caller-provided buffers.
|
|
|
|
First of all there is the buffer
|
2004-11-03 13:51:07 +00:00
|
|
|
.I gbuf
|
2007-06-13 22:13:46 +00:00
|
|
|
that can hold a \fIstruct group\fP.
|
2007-04-12 22:42:49 +00:00
|
|
|
And next the buffer
|
2004-11-03 13:51:07 +00:00
|
|
|
.I buf
|
|
|
|
of size
|
|
|
|
.I buflen
|
|
|
|
that can hold additional strings.
|
2007-06-13 22:13:46 +00:00
|
|
|
The result of these functions, the \fIstruct group\fP read from the stream,
|
2004-11-03 13:51:07 +00:00
|
|
|
is stored in the provided buffer
|
2007-12-22 22:10:40 +00:00
|
|
|
.IR *gbuf ,
|
2007-06-13 22:13:46 +00:00
|
|
|
and a pointer to this \fIstruct group\fP is returned in
|
2007-12-22 22:10:40 +00:00
|
|
|
.IR *gbufp .
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success, these functions return 0 and
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *gbufp
|
2007-06-13 22:13:46 +00:00
|
|
|
is a pointer to the \fIstruct group\fP.
|
2004-11-03 13:51:07 +00:00
|
|
|
On error, these functions return an error value and
|
2007-12-22 22:10:40 +00:00
|
|
|
.I *gbufp
|
2004-11-03 13:51:07 +00:00
|
|
|
is NULL.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B ENOENT
|
|
|
|
No more entries.
|
|
|
|
.TP
|
|
|
|
.B ERANGE
|
2007-04-12 22:42:49 +00:00
|
|
|
Insufficient buffer space supplied.
|
|
|
|
Try again with larger buffer.
|
2007-05-19 04:30:20 +00:00
|
|
|
.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
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2007-12-24 15:08:20 +00:00
|
|
|
struct group *getgrent_r(struct group *grp, char *buf,
|
|
|
|
int buflen);
|
2007-05-19 04:30:20 +00:00
|
|
|
.in
|
|
|
|
.fi
|
|
|
|
.sp
|
|
|
|
or, better,
|
|
|
|
.sp
|
|
|
|
.nf
|
2007-12-19 06:57:44 +00:00
|
|
|
.in +4n
|
2007-12-24 15:08:20 +00:00
|
|
|
int getgrent_r(struct group *grp, char *buf, int buflen,
|
|
|
|
FILE **gr_fp);
|
2007-05-19 04:30:20 +00:00
|
|
|
.in
|
|
|
|
.fi
|
|
|
|
.SH NOTES
|
|
|
|
The function
|
|
|
|
.BR getgrent_r ()
|
|
|
|
is not really reentrant since it shares the reading position
|
|
|
|
in the stream with all other threads.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
.nf
|
|
|
|
#define _GNU_SOURCE
|
|
|
|
#include <grp.h>
|
|
|
|
#include <stdio.h>
|
2007-09-10 02:44:09 +00:00
|
|
|
#include <stdlib.h>
|
2004-11-03 13:51:07 +00:00
|
|
|
#define BUFLEN 4096
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
int
|
|
|
|
main(void)
|
2007-04-05 12:36:57 +00:00
|
|
|
{
|
|
|
|
struct group grp, *grpp;
|
|
|
|
char buf[BUFLEN];
|
|
|
|
int i;
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
setgrent();
|
|
|
|
while (1) {
|
|
|
|
i = getgrent_r(&grp, buf, BUFLEN, &grpp);
|
|
|
|
if (i)
|
|
|
|
break;
|
2007-06-20 21:39:45 +00:00
|
|
|
printf("%s (%d):", grpp\->gr_name, grpp\->gr_gid);
|
2007-04-05 12:36:57 +00:00
|
|
|
for (i = 0; ; i++) {
|
2007-06-20 21:39:45 +00:00
|
|
|
if (grpp\->gr_mem[i] == NULL)
|
2007-04-05 12:36:57 +00:00
|
|
|
break;
|
2007-06-20 21:39:45 +00:00
|
|
|
printf(" %s", grpp\->gr_mem[i]);
|
2007-04-05 12:36:57 +00:00
|
|
|
}
|
|
|
|
printf("\en");
|
|
|
|
}
|
|
|
|
endgrent();
|
2007-05-16 02:09:09 +00:00
|
|
|
exit(EXIT_SUCCESS);
|
2004-11-03 13:51:07 +00:00
|
|
|
}
|
|
|
|
.fi
|
|
|
|
.\" 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));
|
2007-05-14 21:11:42 +00:00
|
|
|
.\" exit(EXIT_FAILURE);
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" }
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR fgetgrent (3),
|
|
|
|
.BR getgrent (3),
|
|
|
|
.BR getgrgid (3),
|
|
|
|
.BR getgrnam (3),
|
2005-06-28 07:26:52 +00:00
|
|
|
.BR putgrent (3),
|
2007-07-08 12:11:40 +00:00
|
|
|
.BR group (5)
|