getgrnam

GETGRNAM(3)		  Linux Programmer’s Manual		  GETGRNAM(3)



NAME
       getgrnam, getgrnam_r, getgrgid, getgrgid_r - get group file entry

SYNOPSIS
       #include <sys/types.h>
       #include <grp.h>

       struct group *getgrnam(const char *name);

       struct group *getgrgid(gid_t gid);

       int getgrnam_r(const char *name, struct group *gbuf,
		 char *buf, size_t buflen, struct group **gbufp);

       int getgrgid_r(gid_t gid, struct group *gbuf,
		 char *buf, size_t buflen, struct group **gbufp);

DESCRIPTION
       The  getgrnam()	function  returns a pointer to a structure containing
       the group information from /etc/group for the entry that	 matches  the
       group name name.

       The  getgrgid()	function  returns a pointer to a structure containing
       the group information from /etc/group for the entry that	 matches  the
       group gid gid.

       The getgrnam_r() and getgrgid_r() functions find the same information,
       but store the retrieved group structure in the  space  pointed  to  by
       gbuf.   This  group  structure contains pointers to strings, and these
       strings are stored in the buffer buf of size buflen.  A pointer to the
       result  (in case of success) or NULL (in case no entry was found or an
       error occurred) is stored in *gbufp.

       The group structure is defined in <grp.h> as follows:

	      struct group {
		    char    *gr_name;	   /* group name */
		    char    *gr_passwd;	   /* group password */
		    gid_t   gr_gid;	   /* group id */
		    char    **gr_mem;	   /* group members */
	      };

       The maximum needed size for buf can be found using sysconf(3) with the
       _SC_GETGR_R_SIZE_MAX	parameter.     A     call     to     sysconf(
       _SC_GETGR_R_SIZE_MAX ) returns either -1 without changing errno or  an
       initial value suggested for the size of this buffer.

RETURN VALUE
       The  getgrnam() and getgrgid() functions return a pointer to the group
       information structure, or NULL if the matching entry is not  found  or
       an  error  occurs.  If an error occurs, errno is set appropriately. If
       one wants to check errno after the call, it  should  be	set  to	 zero
       before the call.

       The  return  value may point to static area, and may be overwritten by
       subsequent calls to getgrent(), getgrgid(), or getgrnam().

       The  getgrnam_r() and getgrgid_r() functions return zero	 on  success.
       In case of error, an error value is returned.

ERRORS
       0 or ENOENT or ESRCH or EBADF or EPERM or ...
	      The given name or gid was not found.

       ENOMEM Insufficient memory.

       EIO    I/O error.

       EINTR  A signal was caught.

       EMFILE The  maximum number (OPEN_MAX) of files was open already in the
	      calling process.

       ENFILE The maximum number of files was open already in the system.

       ERANGE Insufficient buffer space supplied.

FILES
       /etc/group
	      group database file

CONFORMING TO
       SVID 3, BSD 4.3, POSIX 1003.1-2003

NOTES
       The formulation	given  above  under  "RETURN  VALUE"  is  from	POSIX
       1003.1-2001.   It  does	not call "not found" an error, hence does not
       specify what value errno might have in this situation. But that	makes
       it  impossible  to recognize errors. One might argue that according to
       POSIX errno should be left unchanged if an entry is not found. Experi-
       ments on various Unix-like systems shows that lots of different values
       occur in this situation: 0, ENOENT, EBADF, ESRCH,  EWOULDBLOCK,	EPERM
       and probably others.

SEE ALSO
       fgetgrent(3),   getgrent(3),  setgrent(3),  endgrent(3),	 getpwnam(3),
       group(5)



				  2003-11-15			  GETGRNAM(3)