NAME
getgrent, getgrnam, getgrgid, setgrent, endgrent, setgrfile
- group file routines
SYNOPSIS
#include <grp.h>
struct group *getgrent(void)
struct group *getgrnam(const char *name)
struct group *getgrgid(gid_t gid)
int setgrent(void)
void endgrent(void)
void setgrfile(const char *file)
DESCRIPTION
These functions are used to obtain information from the
group file. They return this information in a struct group
as defined by <grp.h>:
struct group {
char *gr_name; /* login name */
char *gr_passwd; /* encrypted password */
gid_t gr_gid; /* numeric group id */
char **gr_mem; /* null-terminated list of group members */
};
Getgrent() reads the group file entry by entry. Getgrnam()
scans the entire group file for the group with the given
name. Getgrgid() looks for the first group with the given
gid. The setgrent() and endgrent() functions are used to
open and later close the group file. With setgrfile() one
can specify the file to read other than the normal group
file. This only sets the name, the next setgrent() call
will open the file. Do not touch the file name while it is
active. Use setgrfile(NULL) to revert back to the normal
group file.
The usual way to scan the group file is (error checking
omitted):
setgrent();
while ((gr = getgrent()) != NULL)
if (appropriate_test(gr)) break;
endgrent();
The gr variable contains the entry that is wanted if non-
NULL. The getgrnam() and getgrgid() functions are imple-
mented as in this example, with error checking of course.
Getgrent() calls setgrent() if this has not yet been done.
Setgrent() first calls endgrent() if the group file is still
open. (Other implementations may simply rewind the file.)
FILES
/etc/group The group file database.
SEE ALSO
getgroups(2), initgroups(3), getpwent(3), passwd(5).
DIAGNOSTICS
Setgrent() has the same return value and error codes as the
open(2) call it uses to open the group file. The getxxx()
functions return NULL on end of file, entry not found, or
error. You can set errno to zero before the call and check
it after.
NOTES
All getxxx() routines return a pointer to static storage
that is overwritten in each call.
Only getgrnam() and getgrgid() are defined by POSIX. The
_MINIX_SOURCE macro must be defined before including <grp.h>
to make the other functions visible. The gr_passwd field is
also not defined by POSIX, but is always visible. Portable
code cannot reliably detect errors by setting errno to zero.
Under MINIX 3 it is better to make a getgrent() scan if you
need to look up several group-id's or names, but portable
code had better use several getgrgid() or getgrnam() calls.
The getgrent() is usually available on other systems, but
may be very expensive. See initgroups(3) if you are after
supplementary group id's.
AUTHOR
Kees J. Bot (kjb@cs.vu.nl)