getgrent(3C)


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

Synopsis

   #include <grp.h> 
   

struct group *getgrent(void);

struct group *getgrgid(gid_t gid);

struct group *getgrnam(const char *name);

void setgrent(void);

void endgrent(void);

struct group *fgetgrent(FILE *f);

Description

getgrgid- get group file entry

getgrnam- get group file entry

setgrent- get group file entry

endgrent- get group file entry

fgetgrent- get group file entry

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 */ 

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; so, successive calls may be used to search the entire file. 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.

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. If an end-of-file or an error is encountered on reading, these functions return a null pointer.

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.

When used by a multithreaded program, each distinct thread will have its own group structure and, except for fgetgrent, its own underlaying file descriptor.

Files

   /etc/group 
   /var/yp/domainame/group.byname 
   /var/yp/domainame/group.bygid 

Errors

getgrent, getgrgid, getgrnam, and fgetgrent return a null pointer on EOF or error. If the functions are unable to allocate sufficient space for the entry, errno is set to ENOMEM.

References

getlogin(3C), getpwent(3C), group(4)

Notices

All information is contained in a static area, so it must be copied if it is to be saved.

Group structures will be obtained from NIS, when the dynamic versions of these routines (other than fgetgrent) are used and NIS is installed and running. See group(4) for the formats of NIS entries.


30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.