#include <sys/types.h> #include <grp.h>
struct group getgrent (void);
int getgrent_r (struct group grp, char buf, size_t len, struct group ptr);
struct group getgrgid (gid_t gid);
int getgrgid_r (gid_t gid, struct group *grp, char *buf, size_t len, struct group **ptr);
struct group getgrnam (const char *name);
int getgrnam_r (const char *name, struct group *grp, char *buf, size_t len, struct group **ptr);
void setgrent (void);
void endgrent (void);
struct group fgetgrent (FILE f);
int fgetgrent_r (FILE f, struct group grp, char buf, size_t len, struct group ptr);
getgrent_r- fill in group structure from next entry
getgrgid- return pointer to group entry matching gid
getgrgid_r- fill in group entry matching gid
getgrnam- return pointer to group entry matching name
getgrnam_r- fill in group entry matching name
setgrent- rewind the group file
endgrent- close the group file
fgetgrent- return pointer to next group structure in stream
fgetgrent_r- fill in group structure from next in stream
getgrent, getgrgid, and getgrnam each returns a pointer to a structure containing the broken-out fields of a line in the /etc/group file. Each line contains a ``group'' structure, defined in the grp.h header file with the following members:
char gr_name; / the name of the group / char gr_passwd; / the encrypted group password / gid_t gr_gid; / the numerical group ID / char gr_mem; / vector of pointers to member names /
The corresponding reentrant routines getgrent_r, getgrgid_r, and getgrnam_r each return zero, set the pointer pointed-to by ptr to be the address of the structure pointed-to by grp, and fill in the structure whose address was passed as grp if there is either a next entry (for getgrent_r) or a matching entry (for getgrnam_r and getgrgid_r). Otherwise, they set the pointer pointed-to by ptr to be null and return zero if no entry was found, or a nonzero errno-code if some error occurred. The buf argument points to the start of an array of at least len bytes into which these routines may read the input line and thus store the strings pointed-to by the filled-in structure. If insufficient space is provided, they fail, returning ERANGE.
When first called, getgrent returns a pointer to the first group structure in the file; thereafter, it returns a pointer to the next group structure in the file. Thus successive calls can be used to search the entire file. The same is true for the getgrent_r routine except that the objects filled-in are provided by the caller. Note that getgrent_r shares the ``current location'' in the file with getgrent.
getgrgid searches from the beginning of the file until a numerical group ID matching gid is found and returns a pointer to the particular structure in which it was found. The same is true for the getgrgid_r routine except that the objects filled-in are provided by the caller.
getgrnam searches from the beginning of the file until a group name matching name is found, and returns a pointer to the particular structure in which it was found. The same is true for the getgrnam_r routine except that the objects filled-in are provided by the caller.
A call to setgrent has the effect of rewinding the group file to allow repeated searches. endgrent may be called to close the group file when processing is complete.
fgetgrent returns a pointer to the next group structure in the stream f, which matches the format of /etc/group. The same is true for the fgetgrent_r routine except that the objects filled-in are provided by the caller.
/etc/group /var/yp/domainame/group.byname /var/yp/domainame/group.bygid
getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r return zero on EOF or a nonzero errno-code on error.
Except for fgetgrent and fgetgrent_r, these routines use NSS (Name Service Switch) to decide how to process the requested operations. See nsdispatch(3C).
For fgetgrent, getgrent, getgrgid, getgrnam, setgrent, and endgrent, all information is contained in a thread-specific buffers so that calls from separate threads will not interfere. Subsequent calls from the same thread will reuse these buffers, so information must be copied if it is to be saved. Moreover, getgrent and getgrent_r share the thread-specific current location in the password file.
Depending on whether NIS is installed and enabled, when the dynamic versions of these routines are used, and the NSS routing is so configured, the group structures may be obtained from NIS. See group(4) for the formats of NIS entries.