NAME

getgrnam, getgrent, getgrgid, setgrent, endgrent, fgetgrent − get group entry

SYNOPSIS

#include <grp.h>

struct group ∗getgrnam(const char ∗name);

struct group ∗getgrent(void);

struct group ∗getgrgid(gid_t gid);

void setgrent(void);

void endgrent(void);

struct group ∗fgetgrent(FILE ∗f);

DESCRIPTION

getgrent(), getgrgid(), and getgrnam() each return a group entry.  The entry may come from one of the following sources:  the group file (see group(4)), the NIS maps “group.byname” and “group.bygid”, and the NIS+ table “group”. The sources and their lookup order are specified in the /etc/nsswitch.conf file (see nsswitch.conf(4)). 

getgrnam() searches for a group entry with a given group name. 

getgrgid() searches for a group entry with a given (numeric) group id. 

getgrent() enumerates group entries:  successive calls to getgrent() will return either successive group entries or NULL.  Enumeration may not be supported by some sources. 

setgrent() “rewinds” to the beginning of the enumeration of group entries.  Calls to getgrnam() and getgrgid() may leave the enumeration in an indeterminate state, so setgrent() should be called before the first getgrent(). 

endgrent() may be called to indicate that group processing is complete; the system may then close any open group file, deallocate storage, and so forth.  It is legitimate, but possibly less efficient, to call more group routines after endgrent(). 

fgetgrent(), unlike the routines above, does not use nsswitch.conf; it reads and parses the next line from the stream f, which is assumed to have the format of group(4). 

The internal representation of a group entry is a group structure defined in <grp.h> with the following members:

char∗gr_name;/∗ the name of the group ∗/
char∗gr_passwd;/∗ the encrypted group password ∗/
gid_tgr_gid;/∗ the numerical group ID ∗/
char∗∗gr_mem;/∗ vector of pointers to member names ∗/

RETURN VALUES

getgrnam() and getgrgid() return a pointer to a struct group if they successfully locate the requested entry; otherwise they return NULL. 

getgrent() and fgetgrent() return a pointer to a struct group if they successfully enumerate an entry; otherwise they return NULL, indicating the end of the enumeration. 

FILES

/etc/group

/etc/nsswitch.conf

SEE ALSO

getpwnam(3C), group(4), nsswitch.conf(4)

NOTES

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

Previous releases used “+” and “-” entries in /etc/group to selectively include and exclude entries from NIS.  If still required, this is supported by a “compat” source.  If compatibility with the +/- syntax is desired in conjunction with NIS+, this is supported by using the source “nisplus” for the pseudo-database group_compat.  The "compat” source may not be supported in future releases.  The preferred sources are “files” and “nisplus”; they do not require the use of “+” and “-” entries in /etc/group.  See group(4) and nsswitch.conf(4) for details. 

Use of getgrent() is deprecated; enumeration is well-defined for the group file and is supported (albeit inefficiently) for NIS and NIS+, but in general may not be well-defined.  The semantics of enumeration are discussed in nsswitch.conf(4). 

BUGS

Programs that call getgrnam() or getgrgid() routines cannot be linked statically since the implementation of these routines requires dynamic linker functionality to access shared objects at run time. 

SunOS 5.1/SPARC  —  Last change: 24 Feb 1992