getgrent(3C)

getgrent, getgrent_r, getgrgid, getgrgid_r, getgrnam, getgrnam_r, setgrent, endgrent, fgetgrent, fgetgrent_r -- manipulate group file entry

Synopsis

   #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);

Description

getgrent- return pointer to group entry

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.

Files

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

Return Values

getgrent, getgrgid, getgrnam, and fgetgrent return a null pointer on EOF or error.

getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r return zero on EOF or a nonzero errno-code on error.

Diagnostics

getgrent, getgrgid, getgrnam, fgetgrent, setgrent, and endgrent return the following values if the corresponding conditions are detected:

ENOMEM: sufficient space for the entry cannot be allocated.

getgrent_r, getgrgid_r, getgrnam_r, and fgetgrent_r return the following value if the corresponding condition is detected:

ERANGE: Insufficient storage was supplied in the len bytes of buf to contain the data to be referenced by the resulting passwd structure.

Standards Compliance

The Single UNIX Specification, Version 2; The Open Group.

References

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

Notices

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.