GETGRENT(3C)							  GETGRENT(3C)

NAME    [Toc]    [Back]

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

SYNOPSIS    [Toc]    [Back]

     #include <grp.h>

     struct group *getgrent(void);

     struct group *getgrent_r(struct group *grent, char	*buffer, int bufsize);

     struct group *getgrgid(gid_t gid);

     int getgrgid_r(gid_t gid, struct group *grent, char *buffer, int bufsize, struct group **grp);

     struct group *getgrnam(const char *name);

     int getgrnam_r(const char *name, struct group *grent, char	*buffer, int bufsize, struct group **grp);

     void setgrent(void);

     void endgrent(void);

     struct group *fgetgrent(FILE *f);

     struct group *fgetgrent_r(FILE *f,	struct group *grent, char *buffer, int bufsize);

     int getgrmember(const char	*name, gid_t gid_array[], int maxgids, int vgids);

DESCRIPTION    [Toc]    [Back]

     getgrent, getgrgid	and getgrnam and their reentrant counterparts each
     return pointers to	an object with the following structure containing the
     broken-out	fields of a line in the	/etc/group file	or some	other back-end
     group database.  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 */
		 gid_t	 gr_gid;     /*	the numerical group ID */
		 char	 **gr_mem;   /*	vector of pointers to member names */
	  };

     getgrent when first called	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



									Page 1






GETGRENT(3C)							  GETGRENT(3C)



     pointer.

     The getgrnam_r and	getgrgid_r calls are reentrant versions	of the
     getgrnam and getgrgid calls.   The	extra arguments	grent and buffer are
     used for internal storage,	bufsize	is size	of buffer, and grp is the
     struct group used to return the requested information.  A good size of
     buffer is BUFSIZ bytes.

     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.

NOTES    [Toc]    [Back]

     In	IRIX 4.0, there	were two versions of the getpwent primitives:  the
     standard version in libc and the NIS version in libsun.  This release
     contains only routines to parse files, an external	file supply mechanism
     nsd(1) supplies data from NIS and other protocols as files.  To force
     these routines to not use nsd supplied data set the external
     _getpwent_no_yp variable to 1. This is useful for programs	that must not
     generate any network traffic, and for programs that update	the /etc/group
     file.


     getgrmember is used to get	the ids	of the groups of which the given user
     is	a member.  name	is the name of the user.  The group ids	are returned
     in	the array gid_array which contains maxgids elements.  The first	vgid
     elements of gid_array are not used	by getgrmember and can be used by the
     caller to initialize default group	ids.  getgrmember is usually called by
     initgroups. getgrmember returns the number	of valid gids in the gid array
     or	-1 if an error is encountered.

     The Mips ABI specifies nothing but	local files so applications which wish
     to	use anything else must compile with libc prior to libnsl in the
     library list.

     When nsd is running changes in the	group file may not be seen by
     getgrent()	until the nsd enumeration cache	file has timed out.

DIAGNOSTICS    [Toc]    [Back]

     All routines that return a	struct group * will return a NULL pointer in
     the case of EOF or	failure. The reentrant functions return	the errno(3C)
     for the call, and thus 0 implies success.	The getgrmember	call returns
     the number	of gids	found, and -1 on failure.

FILES    [Toc]    [Back]

     /etc/group	/var/ns/cache/group.byname.m /var/ns/cache/group.bygid.m
     /var/ns/cache/group.bymember.m





									Page 2






GETGRENT(3C)							  GETGRENT(3C)

SEE ALSO    [Toc]    [Back]

     nsd(1M), getgroups(2), errno(3C), getlogin(3C), getpwent(3C), group(4).

WARNING    [Toc]    [Back]

     The above routines	use the	stdio library, which causes them to increase
     the size of programs, not otherwise using standard	I/O, more than might
     be	expected.  They	also map an external cache file	which can cause	the
     application to be larger than expected.


									PPPPaaaaggggeeee 3333