endgrent, fgetgrent, getgrent, getgrgid, getgrnam, setgrent,
endgrent_r, fgetgrent_r, getgrent_r, getgrgid_r,
getgrnam_r, setgrent_r - Access group information in the
user database
#include <grp.h>
void endgrent(
void ); struct group *fgetgrent(
FILE *f ); struct group *getgrent(
void ); struct group *getgrgid(
gid_t *gid ); struct group *getgrnam(
const char *name ); void setgrent(
void ); void endgrent(
FILE **gr_fp ); void fgetgrent_r(
FILE *f,
stuct group *grp,
char *buffer,
int len ); void getgrent_r(
stuct group *grp,
char *buffer,
int len,
FILE **gr_fp ); int getgrgid_r(
gid_t *gid,
struct group *grp,
char *buffer,
siz_t len,
struct group **result ); int getgrname(
const char *name,
struct group *grp,
char *buffer,
size_t len,
struct group **result ); int setgrent_r(
FILE **gr_fp );
The following obsolete functions do not conform to industry
standards and are supported only for backward compatibility.
You should not use them in new designs. int getgrgid_r(
gid_t gid,
struct group *grp,
char *buffer,
int len ); int getgrnam_r(
const char *name,
struct group *grp,
char *buffer,
int len ); int setgrent(
void );
Standard C Library (libc)
Interfaces documented on this reference page conform to
industry standards as follows:
endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(),
getgrnam_r(), setgrent(): XSH5.0
Refer to the standards(5) reference page for more
information about industry standards and associated tags.
Specifies the name of the group for which the group file
entry is to be retrieved. Specifies the group ID of the
group for which the group file entry is to be retrieved.
Provides storage to hold the retrieved group structure.
Specifies the working buffer that is able to hold the
longest group entry in the database (/etc/group). Specifies
the length of buffer. This length should be sufficient
for buf to hold the longest /etc/group line. Upon
successful return, points to the retrieved group structure.
Upon unsuccessful return, the result is set to NULL.
Specifies a file that contains the next group structure
(initialized by the user). Specifies a file that contains
the next group structure (initialized by the user). This
file should have the same format as /etc/group. The minimum
buffer size is 1024 bytes as defined for SIABUFSIZ in
/usr/include/sia.h. Specifies the length of buffer. The
minimum buffer size is 1024 bytes as defined for SIABUFSIZ
in /usr/include/sia.h.
The getgrent(), getgrgid(), getgrnam(), setgrent(), endgrent(),
and fgetgrent() functions may be used to access
the basic group attributes.
The setgrent() function opens the user database (if not
already open) and rewinds to the first group entry in the
database.
The getgrent(), getgrnam(), and getgrgid() functions
return information about the requested group. The getgrent()
function returns the next group in the sequential
search. The getgrnam() function returns the first group in
the database with the gr_name field that matches the name
parameter. The getgrgid() function returns the first group
in the database with a gr_gid field that matches the gid
parameter. The endgrent() function closes the user
database.
The group structure, which is returned by the getgrent(),
getgrgid(), and getgrnam() functions, is defined in the
grp.h header file, and contains the following members: The
name of the group. The password of the group. (Note that
this field is not used by the system, so its value is
meaningless.) The ID of the group. The members of the
group.
The fgetgrent() function gets a group file entry from the
file specified by the f parameter, rather than assuming
that it comes from the /etc/group file. This file must
have the format of the /etc/group file.
The endgrent_r(), fgetgrent_r(), getgrent_r(), getgrgid_r(),
getgrnam_r(), and setgrent_r(), functions are
the reentrant versions of endgrent(), fgetgrent(), getgrent(),
getgrgid(), getgrnam(), and setgrent(), respectively.
The endgrent_r(), fgetgrent_r(), getgrent_r(), and setgrent_r(),
functions use the f and gr_fp parameters to
keep track of the calls to the getgrent_r function, so
that subsequent calls will return subsequent entries from
the /etc/group file.
Upon successful completion, the fgetgrent_r(), getgrent_r(),
getgrgid_r(), and getgrnam_r() functions store
their results in the buffer pointed to by the grp parameter,
with references to the working buffer. The pointer to
the grp is also stored in result.
The data that is returned by the fgetgrent(), getgrent(),
getgrgid(), and getgrnam() functions is stored in a static
area and will be overwritten on subsequent calls to these
routines.
The fgetgrent(), getgrent(), getgrnam(), and getgrgid()
functions are not supported for multithreaded applications.
Instead, their reentrant equivalents, fgetgrent_r(),
getgrent_r(), getgrnam_r(), and getgrgid_r,()
should be used with multiple threads.
Note that the caller is expected to initialize *gr_fp to
NULL before using it for the first time.
Note also that entries which are excessively long will be
ignored by both the reentrant and non-reentrant functions.
Upon successful completion, the fgetgrent(), getgrent(),
getgrgid(), and getgrnam() functions return a pointer to a
valid group structure containing a matching entry. Upon
failure, these functions return NULL.
The getgrgid_r() and getgrnam_r() functions return a value
of 0 (zero) on success. If the user or group is not found
in the password or group database, these routines return 0
for the status and a NULL in the returned "result"
pointer.
The fgetgrent_r() and getgrent_r() functions, as well as
the obsolete versions of the getgrgid_r and getgrnam_r
functions, return a value of 0 (zero) for success and a
value of -1 for failure.
The backward-compatible version of the setgrent() function
returns a value of 1 for success and a value of 0 (zero)
for failure.
The setgrent_r() function returns a value of 0 (zero) for
success and a value of -1 for failure.
If any of the following conditions occurs, the getgrgid_r()
and getgrnam_r() functions set errno to the corresponding
value: The amount of storage specified by
buffer and len is too small to contain the data to be referenced
by the resulting struct group structure.
Functions: getpwent(3)
Standards: standards(5)
getgrent(3)
[ Back ] |
