endgrent man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

GETGRNAM(3C)							  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 bufsize, struct group **result);

DESCRIPTION
       These  functions	 are  used  to	obtain entries describing user groups.
       Entries 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
       interfaces, 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 multithreaded 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
       result 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
       entry  was  not	found  or an error occurred. On error, errno is set to
       indicate the error. The standard-conforming functions getgrnam_r()  and
       getgrgid_r()  return 0 upon success or an error number in case of fail‐
       ure.

       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 │ See below.			       │
       ├────────────────────┼──────────────────────────────────────────┤
       │MT-Level	    │ See Reentrant Interfaces in DESCRIPTION. │
       └────────────────────┴──────────────────────────────────────────┘

       The endgrent(), getgrent(), getgrgid(), getgrgid_r(), getgrnam(),  get‐
       grnam_r(), and setgrent() functions are Standard.

SEE ALSO
       Intro(3),    getpwnam(3C),   group(4),	nsswitch.conf(4),   passwd(4),
       attributes(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
       libraries 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.

				  Apr 5, 2004			  GETGRNAM(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net