Man Linux: Main Page and Category List

NAME

       getgrgid, getgrgid_r - get group database entry for a group ID

SYNOPSIS

       #include <grp.h>

       struct group *getgrgid(gid_t gid);

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

DESCRIPTION

       The  getgrgid()  function  shall search the group database for an entry
       with a matching gid.

       The getgrgid() function need not be reentrant. A function that  is  not
       required to be reentrant is not required to be thread-safe.

       The  getgrgid_r()  function shall update the group structure pointed to
       by grp and store a pointer to that structure at the location pointed to
       by result. The structure shall contain an entry from the group database
       with a matching gid. Storage  referenced  by  the  group  structure  is
       allocated  from the memory provided with the buffer parameter, which is
       bufsize bytes in size. The maximum size needed for this buffer  can  be
       determined  with the {_SC_GETGR_R_SIZE_MAX} sysconf() parameter. A NULL
       pointer shall be returned at the location pointed to by result on error
       or if the requested entry is not found.

RETURN VALUE

       Upon  successful  completion,  getgrgid()  shall  return a pointer to a
       struct group with the structure defined  in  <grp.h>  with  a  matching
       entry  if  one  is  found.  The getgrgid() function shall return a null
       pointer if either the requested  entry  was  not  found,  or  an  error
       occurred. On error, errno shall be set to indicate the error.

       The  return  value may point to a static area which is overwritten by a
       subsequent call to getgrent(), getgrgid(), or getgrnam().

       If successful, the getgrgid_r() function shall return zero;  otherwise,
       an error number shall be returned to indicate the error.

ERRORS

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

       EIO    An I/O error has occurred.

       EINTR  A signal was caught during getgrgid().

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

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

       The getgrgid_r() function may fail if:

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

       The following sections are informative.

EXAMPLES

   Finding an Entry in the Group Database
       The  following example uses getgrgid() to search the group database for
       a group ID that was previously stored in a stat structure, then  prints
       out  the  group  name  if  it is found.  If the group is not found, the
       program prints the numeric value of the group for the entry.

              #include <sys/types.h>
              #include <grp.h>
              #include <stdio.h>
              ...
              struct stat statbuf;
              struct group *grp;
              ...
              if ((grp = getgrgid(statbuf.st_gid)) != NULL)
                  printf(" %-8.8s", grp->gr_name);
              else
                  printf(" %-8d", statbuf.st_gid);
              ...

APPLICATION USAGE

       Applications wishing to check for error situations should set errno  to
       0  before  calling  getgrgid().  If  errno  is  set on return, an error
       occurred.

       The getgrgid_r() function is thread-safe and shall return values  in  a
       user-supplied  buffer instead of possibly using a static data area that
       may be overwritten by each call.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       endgrent()  ,   getgrnam()   ,   the   Base   Definitions   volume   of
       IEEE Std 1003.1-2001, <grp.h>, <limits.h>, <sys/types.h>

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .