30.14.3 Scanning the List of All Groups

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.

Function: struct group * fgetgrent (FILE *stream)

Preliminary: | MT-Unsafe race:fgrent | AS-Unsafe corrupt lock | AC-Unsafe corrupt lock | See POSIX Safety Concepts.

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.

Function: int fgetgrent_r (FILE *stream, struct group *result_buf, char *buffer, size_t buflen, struct group **result)

Preliminary: | MT-Safe | AS-Unsafe corrupt | AC-Unsafe corrupt lock | See POSIX Safety Concepts.

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.

Function: void setgrent (void)

Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.

This function initializes a stream for reading from the group data base. You use this stream by calling getgrent or getgrent_r.

Function: struct group * getgrent (void)

Preliminary: | MT-Unsafe race:grent race:grentbuf locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.

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.

Function: int getgrent_r (struct group *result_buf, char *buffer, size_t buflen, struct group **result)

Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.

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 by 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.

Function: void endgrent (void)

Preliminary: | MT-Unsafe race:grent locale | AS-Unsafe dlopen plugin heap lock | AC-Unsafe corrupt lock fd mem | See POSIX Safety Concepts.

This function closes the internal stream used by getgrent or getgrent_r.