This section describes how to search and scan the database of registered groups. The database itself is kept in the file /etc/group on most systems, but on some systems a special network service provides access to it.
The functions and data structures for accessing the system group database are declared in the header file grp.h. function>struct group/function> The group structure is used to hold information about an entry in the system group database. It has at least the following members:
The name of the group.
The group ID of the group.
A vector of pointers to the names of users in the group. Each user name is a null-terminated string, and the vector itself is terminated by a null pointer.
You can search the group database for information about a specific group using getgrgid or getgrnam. These functions are declared in grp.h.
struct group * function>getgrgid/function> (gid_t gid) This function returns a pointer to a statically-allocated structure containing information about the group whose group ID is gid. This structure may be overwritten by subsequent calls to getgrgid.
A null pointer indicates there is no group with ID gid.
int function>getgrgid_r/function> (gid_t gid, struct group *result_buf, char *buffer, size_t buflen, struct group **result) This function is similar to getgrgid in that it returns information about the group whose group ID is gid. However, it fills the user supplied structure pointed to by result_buf with the information instead of using a static buffer. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.
If a group with ID gid is found, the pointer returned in result points to the record which contains the wanted data (i.e., result contains the value result_buf). If no group is found or if an error occurred, the pointer returned in result is a null pointer. The function returns zero or an error code. If the buffer buffer is too small to contain all the needed information, the error code ERANGE is returned and errno is set to ERANGE.
struct group * function>getgrnam/function> (const char *name) This function returns a pointer to a statically-allocated structure containing information about the group whose group name is name. This structure may be overwritten by subsequent calls to getgrnam.
A null pointer indicates there is no group named name.
int function>getgrnam_r/function> (const char *name, struct group *result_buf, char *buffer, size_t buflen, struct group **result) This function is similar to getgrnam in that is returns information about the group whose group name is name. Like getgrgid_r, it uses the user supplied buffers in result_buf and buffer, not a static buffer.
The return values are the same as for getgrgid_rERANGE.
This section explains how a program can read the list of all groups in the system, one group at a time. The functions described here are declared in grp.h.
You can use the fgetgrent function to read group entries from a particular file.
struct group * function>fgetgrent/function> (FILE *stream) The fgetgrent function reads the next entry from stream. It returns a pointer to the entry. The structure is statically allocated and is overwritten on subsequent calls to fgetgrent. You must copy the contents of the structure if you wish to save the information.
The stream must correspond to a file in the same format as the standard group database file.
int function>fgetgrent_r/function> (FILE *stream, struct group *result_buf, char *buffer, size_t buflen, struct group **result) This function is similar to fgetgrent in that it reads the next user entry from stream. But the result is returned in the structure pointed to by result_buf. The first buflen bytes of the additional buffer pointed to by buffer are used to contain additional information, normally strings which are pointed to by the elements of the result structure.
This stream must correspond to a file in the same format as the standard group database file.
If the function returns zero result points to the structure with the wanted data (normally this is in result_buf). If errors occurred the return value is non-zero and result contains a null pointer.
The way to scan all the entries in the group database is with setgrent, getgrent, and endgrent.
void function>setgrent/function> (void) This function initializes a stream for reading from the group data base. You use this stream by calling getgrent or getgrent_r.
struct group * function>getgrent/function> (void) The getgrent function reads the next entry from the stream initialized by setgrent. It returns a pointer to the entry. The structure is statically allocated and is overwritten on subsequent calls to getgrent. You must copy the contents of the structure if you wish to save the information.
int function>getgrent_r/function> (struct group *result_buf, char *buffer, size_t buflen, struct group **result) This function is similar to getgrent in that it returns the next entry from the stream initialized by setgrent. Like fgetgrent_r, it places the result in user-supplied buffers pointed to result_buf and buffer.
If the function returns zero result contains a pointer to the data (normally equal to result_buf). If errors occurred the return value is non-zero and result contains a null pointer.
void function>endgrent/function> (void) This function closes the internal stream used by getgrent or getgrent_r.