Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
getgrnam(3C)		 Standard C Library Functions		  getgrnam(3C)

       getgrnam,  getgrnam_r, getgrent,	getgrent_r, getgrgid, getgrgid_r, set-
       grent, endgrent,	fgetgrent, fgetgrent_r - group	database  entry	 func-

       #include	<grp.h>

       struct group *getgrnam(const char *name);

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

       struct group *getgrent(void);

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

       struct group *getgrgid(gid_t gid);

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

       void setgrent(void);

       void endgrent(void);

       struct group *fgetgrent(FILE *f);

       struct group *fgetgrent_r(FILE *f, struct group *grp, char *buffer, int

       cc [ flag... ] file... -D_POSIX_PTHREAD_SEMANTICS [ library... ]

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

       int  getgrgid_r(gid_t gid, struct group *grp, char *buffer, size_t buf-
       size, struct group **result);

       These functions are used	to obtain entries describing user groups.  En-
       tries  can  come	 from  any  of	the sources for	group specified	in the
       /etc/nsswitch.conf file (see nsswitch.conf(4)).

       The getgrnam() function searches	the group database for an  entry  with
       the group name specified	by the character string	parameter name.

       The  getgrgid()	function searches the group database for an entry with
       the (numeric) group id specified	by gid.

       The setgrent(), getgrent(), and endgrent() functions are	used  to  enu-
       merate group entries from the database.

       The setgrent() function effectively rewinds the group database to allow
       repeated	searches. It sets (or resets) the enumeration to the beginning
       of the set of group entries.  This function should be called before the
       first call to getgrent().

       The getgrent() function returns a pointer to a structure	containing the
       broken-out  fields  of  an  entry  in  the  group database.  When first
       called, getgrent() returns a pointer to a  group	 structure  containing
       the next	group structure	in the group database. Successive calls	may be
       used to search the entire database.

       The endgrent() function may be called to	close the group	 database  and
       deallocate  resources  when  processing is complete. It is permissible,
       though possibly less efficient, for the	process	 to  call  more	 group
       functions after calling endgrent().

       The  fgetgrent()	 function,  unlike the other functions 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 the group	file (see group(4)).

   Reentrant Interfaces
       The   getgrnam(), getgrgid(), getgrent(), and fgetgrent() functions use
       static storage that is reused in	each call, making them unsafe for mul-
       tithreaded applications.

       The  parallel  functions	 getgrnam_r(), getgrgid_r(), getgrent_r(), and
       fgetgrent_r() provide reentrant interfaces for these operations.

       Each reentrant interface	performs the same operation as	its  non-reen-
       trant counterpart, named	by removing the	 _r suffix.  The reentrant in-
       terfaces, however, use buffers supplied by the caller to	store returned
       results,	 and   are  safe  for  use  in both single-threaded and	multi-
       threaded	applications.

       Each reentrant interface	takes the same arguments as its	 non-reentrant
       counterpart,  as	 well as the following additional parameters.  The grp
       argument	must be	a pointer to a struct group structure allocated	by the
       caller.	On successful completion, the function returns the group entry
       in this structure. Storage referenced by	the group structure  is	 allo-
       cated  from the memory provided with the	buffer argument, which is buf-
       size characters in size.	 The maximum size needed for  this buffer  can
       be  determined with the _SC_GETGR_R_SIZE_MAX sysconf(3C)	parameter. The
       POSIX versions place a pointer to the modified grp structure in the re-
       sult parameter, instead of returning a pointer to this structure.

       For  enumeration	in multithreaded applications, the position within the
       enumeration is a	process-wide property  shared  by  all	threads.  set-
       grent()	may be used in a multithreaded application but resets the enu-
       meration	position for all  threads.   If	 multiple  threads  interleave
       calls  to  getgrent_r(),	the threads will enumerate disjoint subsets of
       the group database. Like	their non-reentrant counterparts, getgrnam_r()
       and  getgrgid_r()  leave	 the  enumeration position in an indeterminate

       Group entries are represented by	the struct group structure defined  in

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

       The   getgrnam(),  getgrnam_r(),	getgrgid(), and	getgrgid_r() functions
       each return a pointer to	a struct group if they successfully locate the
       requested entry;	otherwise they return NULL. The	POSIX functions	getgr-
       nam_r() and getgrgid_r()	return 0 upon success or the error  number  in
       case of failure.

       The  getgrent(),	getgrent_r(), fgetgrent(), and fgetgrent_r() functions
       each return a pointer to	a struct group if they successfully  enumerate
       an entry; otherwise they	return NULL, indicating	the end	of the enumer-

       The  getgrnam(),	getgrgid(), getgrent(),	and fgetgrent()	functions  use
       static  storage,	 so  returned  data must be copied before a subsequent
       call to any of these functions if the data is to	be saved.

       When the	pointer	returned by the	reentrant functions getgrnam_r(), get-
       grgid_r(),  getgrent_r(),  and  fgetgrent_r() is	non-null, it is	always
       equal to	the grp	pointer	that was supplied by the caller.

       The getgrnam(), getgrgid(), getgrent(), fgetgrent(), and	 fgetgrent_r()
       functions may fail if:

       EINTR A signal was caught during	the operation.

       EIO   An	I/O error has occurred.

	     There are OPEN_MAX	file descriptors currently open	in the calling

	     The maximum allowable number of files is currently	 open  in  the

	     The group file contains a line that exceeds 512 bytes.

       The getgrnam_r(), getgrgid_r(), and getgrent_r()	functions may fail if:

	     Insufficient  storage  was	supplied by buffer and bufsize to con-
	     tain the data to be referenced by the resulting group structure.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |See "Reentrant  Interfaces"  |
       |			     |in DESCRIPTION.		   |

       Intro(3),  getpwnam(3C),	 group(4),  nsswitch.conf(4),  passwd(4),  at-
       tributes(5), standards(5)

       When compiling multithreaded programs, see Intro(3),  Notes  On	Multi-
       threaded	Applications.

       Programs	 that  use the interfaces described in this manual page	cannot
       be linked statically since the implementations of these	functions  em-
       ploy dynamic loading and	linking	of shared objects at run time.

       Use  of	the enumeration	interfaces getgrent() and getgrent_r() is dis-
       couraged; enumeration is	supported for the group	file, NIS,  and	 NIS+,
       but  in general is not efficient	and may	not be supported for all data-
       base sources.  The semantics of enumeration are	discussed  further  in

       Previous	 releases  allowed  the	 use  of  ``+''	 and  ``-'' entries in
       /etc/group to selectively include and exclude  entries  from  NIS.  The
       primary	usage  of  these  entries  is  superseded  by the name service
       switch, so the ``+/-'' form may not be supported	in future releases.

       If required, the	``+/-''	functionality can still	be obtained for	NIS by
       specifying compat as the	source for group.

       If  the	``+/-''	 functionality	is  required in	conjunction with NIS+,
       specify both compat as the source for group and nisplus as  the	source
       for   the   pseudo-database   group_compat.   See  group(4),  and  nss-
       witch.conf(4) for details.

       Solaris 2.4 and earlier releases	provided  definitions  of  the	getgr-
       nam_r()	and  getgrgid_r()  functions as	specified in POSIX.1c Draft 6.
       The final POSIX.1c standard changed the interface for these  functions.
       Support	for  the  Draft	6 interface is provided	for compatibility only
       and may not be supported	in future releases. New	applications  and  li-
       braries should use the POSIX standard interface.

       For  POSIX.1c-compliant	applications, the _POSIX_PTHREAD_SEMANTICS and
       _REENTRANT  flags  are  automatically  turned  on   by	defining   the
       _POSIX_C_SOURCE flag with a value >= 199506L.

SunOS 5.9			  10 Feb 1999			  getgrnam(3C)


Want to link to this manual page? Use this URL:

home | help