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
)
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.
),
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.
EIO
]
EINTR
]
EMFILE
]
ENFILE
]The following error code may be set in errno for getgrent_r, getgrnam_r, and getgrgid_r:
ERANGE
]
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.
/etc/group
)
and
getgrnam(
)
functions conform to
ISO/IEC 9945-1:1990 (``POSIX.1'') .
The
getgrgid_r(
)
and
getgrnam_r(
)
functions conform to
IEEE Std 1003.1c-1995 (``POSIX.1'') .
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).
),
getgrent(
),
getgrgid(
),
getgrnam(
),
and
setgrent(
)
appeared in
Version 7 AT&T UNIX
.
The functions
setgrfile(
)
and
setgroupent(
)
appeared in
4.3BSDReno.
The functions
getgrgid_r(
)
and
getgrnam_r(
)
appeared in
NetBSD3.0.
),
which allowed the specification of alternative group databases, has
been deprecated and is no longer available.
),
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)