NAME
getgrent,
getgrent_r,
getgrgid,
getgrgid_r,
getgrnam,
getgrnam_r,
setgroupent,
setgrent,
endgrent —
group database
operations
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <grp.h>
struct group *
getgrent(
void);
int
getgrent_r(
struct group *grp,
char *buffer,
size_t buflen,
struct group **result);
struct group *
getgrgid(
gid_t
gid);
int
getgrgid_r(
gid_t gid,
struct group *grp,
char *buffer,
size_t buflen,
struct group
**result);
struct group *
getgrnam(
const
char *name);
int
getgrnam_r(
const char *name,
struct group *grp,
char *buffer,
size_t buflen,
struct group
**result);
int
setgroupent(
int
stayopen);
void
setgrent(
void);
void
endgrent(
void);
DESCRIPTION
These functions operate on the group database which is described in
group(5). Each line of the
database is defined by the structure
group found in the
include file
<grp.h>:
struct group {
char *gr_name; /* group name */
char *gr_passwd; /* group password */
gid_t gr_gid; /* group id */
char **gr_mem; /* group members */
};
The functions
getgrnam() and
getgrgid()
search the group database for the given group name pointed to by
name or the group id pointed to by
gid, respectively, returning the first one encountered.
Identical group names or group ids may result in undefined behavior.
The
getgrent() function sequentially reads the group database
and is intended for programs that wish to step through the complete list of
groups.
All three functions will open the group file for reading, if necessary.
The functions
getgrnam_r(),
getgrgid_r(),
and
getgrent_r() act like their non re-entrant counterparts
respectively, updating the contents of
grp and storing a
pointer to that in
result, and returning
0
. Storage used by
grp is
allocated from
buffer, which is
buflen bytes in size. If the requested entry cannot be
found,
result will point to
NULL
and
0
will be returned. If an error occurs, a non-zero
error number will be returned and
result will point to
NULL
. Calling
getgrent_r() from
multiple threads will result in each thread reading a disjoint portion of the
group database.
The
setgroupent() function opens the file, or rewinds it if it
is already open. If
stayopen is non-zero, file
descriptors are left open, significantly speeding functions subsequent calls.
This functionality is unnecessary for
getgrent() as it
doesn't close its file descriptors by default. It should also be noted that it
is dangerous for long-running programs to use this functionality as the group
file may be updated.
The
setgrent() function is equivalent to
setgroupent() with an argument of zero.
The
endgrent() function closes any open files.
RETURN VALUES
The functions
getgrgid(),
getgrnam(), and
getgrent() return a valid pointer to a group structure on
success and a
NULL
pointer if the entry was not found
or an error occured. If an error occured, the global variable
errno
is set to indicate the nature of the failure.
The functions
getgrgid_r(),
getgrnam_r(),
and
getgrent_r() return
0
on success
or entry not found, and non-zero on failure, setting the global variable
errno
to indicate the nature of the failure.
The
setgroupent() function returns the value 1 if successful,
otherwise the value 0 is returned, setting the global variable
errno
to indicate the nature of the failure.
The
endgrent() and
setgrent() functions have
no return value.
FILES
- /etc/group
- group database file
COMPATIBILITY
The historic function
setgrfile(), which allowed the
specification of alternative group databases, has been deprecated and is no
longer available.
ERRORS
The following error codes may be set in
errno for
getgrent,
getgrent_r,
getgrnam,
getgrnam_r,
getgrgid,
getgrgid_r, and
setgroupent:
-
-
- [
EINTR
]
- A signal was caught during the database search.
-
-
- [
EIO
]
- An I/O error has occurred.
-
-
- [
EMFILE
]
- The limit on open files for this process has been
reached.
-
-
- [
ENFILE
]
- The system limit on open files has been reached.
The following error code may be set in
errno for
getgrent_r,
getgrnam_r, and
getgrgid_r:
-
-
- [
ERANGE
]
- The resulting struct group does not
fit in the space defined by
buffer
and
buflen
Other
errno
values may be set depending on the specific
database backends.
SEE ALSO
getpwent(3),
group(5),
nsswitch.conf(5)
STANDARDS
The
getgrgid() and
getgrnam() functions
conform to
IEEE Std 1003.1-1990
(“POSIX.1”). The
getgrgid_r() and
getgrnam_r() functions conform to
IEEE Std
1003.1c-1995 (“POSIX.1c”). The
endgrent(),
getgrent(), and
setgrent() functions conform to
X/Open
Portability Guide Issue 4, Version 2 (“XPG4.2”)
and
IEEE Std 1003.1-2004 (“POSIX.1”) (XSI
extension).
HISTORY
The functions
endgrent(),
getgrent(),
getgrgid(),
getgrnam(), and
setgrent() appeared in
Version 7
AT&T UNIX. The functions
setgrfile() and
setgroupent() appeared in
4.3BSD-Reno. The functions
getgrgid_r() and
getgrnam_r() appeared in
NetBSD 3.0.
BUGS
The functions
getgrent(),
getgrgid(),
getgrnam(),
setgroupent() and
setgrent() leave their results in an internal static object
and return a pointer to that object. Subsequent calls to the same function
will modify the same object.
The functions
getgrent(),
endgrent(),
setgroupent(), and
setgrent() are fairly
useless in a networked environment and should be avoided, if possible.
getgrent() makes no attempt to suppress duplicate
information if multiple sources are specified in
nsswitch.conf(5)