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

FreeBSD Manual Pages

  
 
  

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

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

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

   Standard comforming
       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);

DESCRIPTION
       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	can be
       used to search the entire database.

       The endgrent() function can 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
       thread-specific storage that is reused in each call  to	one  of	 these
       functions  by  the  same	thread,	making them safe to use	but not	recom-
       mended for multithreaded	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 instead of using	thread-specific	data that can  be  overwritten
       by  each	call. They 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 that is bufsize
       characters in size.  The	maximum	size needed for	 this  buffer  can  be
       determined  with	 the  _SC_GETGR_R_SIZE_MAX  sysconf(3C)	parameter. The
       standard-conforming versions place a pointer to the modified grp	struc-
       ture  in	 the  result parameter,	instead	of returning a pointer to this
       structure. A null pointer is returned at	the location pointed to	by re-
       sult on error or	if the requested entry is not found.

       For  enumeration	in multithreaded applications, the position within the
       enumeration is a	process-wide property shared by	all threads. The  set-
       grent()	function can be	used in	a multithreaded	application but	resets
       the enumeration position	for all	threads.  If multiple  threads	inter-
       leave  calls  to	getgrent_r(), the threads will enumerate disjoint sub-
       sets of the group database. Like	their non-reentrant counterparts, get-
       grnam_r()  and  getgrgid_r() leave the enumeration position in an inde-
       terminate state.

   group Structure
       Group entries are represented by	the struct group structure defined  in
       <grp.h>:

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

RETURN VALUES
       The  getgrnam(),	 getgrnam_r(),	getgrgid(), and	getgrgid_r() functions
       each return a pointer to	a struct group if they successfully locate the
       requested entry.	They return a null pointer if either the requested en-
       try was not found or an error occurred. On error, errno is set to indi-
       cate the	error. The standard-conforming functions getgrnam_r() and get-
       grgid_r() return	0 upon success or an 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 a null pointer on end-of-file or	error.
       On error, errno is set to indicate the error.

       The  getgrnam(),	 getgrgid(), getgrent(), and fgetgrent() functions use
       thread-specific data storage, so	returned data must be copied before  a
       subsequent call to any of these functions if the	data are 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.

       Applications  wishing to	check for error	situations should set errno to
       0 before	calling	getgrnam(), getgrnam_r(), getgrent(), getgrent_r()get-
       grgid(),	 getgrgid_r(),	fgetgrent(), and fgetgrent_r().	If these func-
       tions return a null pointer and errno is	non-zero, an error occurred.

ERRORS
       The getgrent_r(), fgetgrent(), and fgetgrent_r()	 functions  will  fail
       if:

       EIO	       An I/O error has	occurred.

       ERANGE	       Insufficient storage was	supplied by buffer and bufsize
		       to contain the data to be referenced by	the  resulting
		       group structure.

       The getgrent_r()	function will fail if:

       EMFILE	       There are {OPEN_MAX} file descriptors currently open in
		       the calling process.

       ENFILE	       The maximum allowable number of files is	currently open
		       in the system.

       The  getgrnam(),	getgrnam_r(), getgrgid(), getgrgid_r(),	and getgrent()
       functions may fail if:

       EINTR	       A signal	was caught during the operation.

       EIO	       An I/O error has	occurred.

       EMFILE	       There are {OPEN_MAX} file descriptors currently open in
		       the calling process.

       ENFILE	       The maximum allowable number of files is	currently open
		       in the system.

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

       ERANGE	       Insufficient storage was	supplied by buffer and bufsize
		       to  contain  the	data to	be referenced by the resulting
		       group structure.

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |endgrent(),     getgrent(),  |
       |			     |getgrgid(),   getgrgid_r(),  |
       |			     |getgrnam(),   getgrnam_r(),  |
       |			     |and  setgrent()  are  Stan-  |
       |			     |dard.			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See Reentrant Interfaces in  |
       |			     |DESCRIPTION.		   |
       +-----------------------------+-----------------------------+

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

NOTES
       When compiling multithreaded programs, see Intro(3).

       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 might  not  be  supported  for  all
       database	 sources.   The	semantics of enumeration are discussed further
       in nsswitch.conf(4).

       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 might 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 might not be	supported in future releases. New applications and li-
       braries should use the standard-conforming interface.

       For POSIX.1c-conforming 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.10			  5 Apr	2004			  getgrnam(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=getgrnam&sektion=3c&manpath=SunOS+5.10>

home | help