getgrent(S)

getgrent, getgrgid, getgrnam, setgrent, endgrent, fgetgrent -- get group file entry

Syntax

cc . . . -lc

#include  <grp.h>

struct group *getgrent ()

struct group *getgrgid (gid)
gid_t gid;

struct group *getgrnam (name)
char *name;

void setgrent ()

void endgrent ()

struct group *fgetgrent (f)
FILE *f;

Description

The getgrent, getgrgid, and getgrnam routines return pointers to an object with the following 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.

   struct  group {
           char       *gr_name;        /* the name of the group */
           char       *gr_passwd;      /* the encrypted group password */
           int        gr_gid;          /* the numerical group ID */
           char       **gr_mem;        /* vector of pointers to member names */
   };

When the getgrent routine is first called, it returns a pointer to the first group structure in the /etc/group file. Thereafter, it returns a pointer to the next group structure in the /etc/group file. Thus, successive calls to getgrent may be used to search the entire file.

The getgrgid routine searches from the beginning of the /etc/group file until a numerical group ID matching the argument gid is found. getgrgid returns a pointer to the group structure in which the argument gid was found.

Like getgrgid, the getgrnam routine searches from the beginning of the /etc/group file until a group whose name matches the argument name is found. getgrnam returns a pointer to the particular group structure in which the argument name was found.

The setgrent routine resets the file pointer to the beginning of the group file to allow repeated searches. The endgrent routine closes the group file when processing is complete.

The fgetgrent routine returns a pointer to the next group structure which matches the format of /etc/group in the stream argument f.

Return value

Upon successful completion, the routines getgrent, getgrgid, getgrnam, and fgetgrent each returns a pointer to a group structure. If an end-of-file or an error is encountered on reading, these routines return a NULL pointer. If a bad entry is encountered, errno is set to EINVAL. If the functions are unable to allocate sufficient space for the entry, errno is set to ENOMEM. No errors are defined for the setgrent or endgrent routines.

Diagnostics

Use feof( ) to test if a null return value is caused by an end-of-file or from a syntax error in the group file. The feof macro is described in the ferror(S) manual page.

The endgrent, getgrgid and getgrnam functions may fail if:

[EINTR]: A signal was caught during the operation.
[EIO]: An I/O error has occurred.
[EMFILE]: {OPEN_MAX} file descriptors are currently open in the calling process.
[ENFILE]: The maximum allowable number of files is currently open in the system.

Note

All information is contained in a static area, so it must be copied if it is to be saved. Otherwise, it may be overwritten on subsequent calls to these routines.

These routines are also included in libsocket. The libsocket version provides the same functionality described here, in addition to providing the NIS support. Link with libsocket using cc ... -lsocket to get the additional NIS (Network Information Service) functionality.

Files

/etc/group

Standards conformance

fgetgrent, getgrent, endgrent, and setgrent are not part of any currently supported standard; they were developed by UNIX System Laboratories, Inc. and are maintained by The SCO Group.

getgrgid and getgrnam conform with:

AT&T SVID Issue 2 ;
X/Open Portability Guide, Issue 3, 1989 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1

. getgrgid and getgrnam conform with:

X/Open Portability Guide, Issue 3, 1989 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .