1GETGRGID(3P)               POSIX Programmer's Manual              GETGRGID(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       getgrgid, getgrgid_r — get group database entry for a group ID
13

SYNOPSIS

15       #include <grp.h>
16
17       struct group *getgrgid(gid_t gid);
18       int getgrgid_r(gid_t gid, struct group *grp, char *buffer,
19           size_t bufsize, struct group **result);
20

DESCRIPTION

22       The getgrgid() function shall search the group database  for  an  entry
23       with a matching gid.
24
25       The getgrgid() function need not be thread-safe.
26
27       Applications  wishing to check for error situations should set errno to
28       0 before calling getgrgid().  If getgrgid() returns a null pointer  and
29       errno is set to non-zero, an error occurred.
30
31       The  getgrgid_r()  function shall update the group structure pointed to
32       by grp and store a pointer to that structure at the location pointed to
33       by  result.   The structure shall contain an entry from the group data‐
34       base with a matching gid.  Storage referenced by the group structure is
35       allocated  from the memory provided with the buffer parameter, which is
36       bufsize bytes in size. A call to sysconf(_SC_GETGR_R_SIZE_MAX)  returns
37       either  -1 without changing errno or an initial value suggested for the
38       size of this buffer.  A null pointer shall be returned at the  location
39       pointed to by result on error or if the requested entry is not found.
40

RETURN VALUE

42       Upon  successful  completion,  getgrgid()  shall  return a pointer to a
43       struct group with the structure defined  in  <grp.h>  with  a  matching
44       entry  if  one  is  found.  The getgrgid() function shall return a null
45       pointer if either the requested  entry  was  not  found,  or  an  error
46       occurred.  If  the  requested  entry  was not found, errno shall not be
47       changed. On error, errno shall be set to indicate the error.
48
49       The application shall not modify the  structure  to  which  the  return
50       value  points,  nor any storage areas pointed to by pointers within the
51       structure. The returned pointer, and  pointers  within  the  structure,
52       might  be  invalidated  or  the structure or the storage areas might be
53       overwritten by a subsequent call to getgrent(), getgrgid(),  or  getgr‐
54       nam().   The returned pointer, and pointers within the structure, might
55       also be invalidated if the calling thread is terminated.
56
57       If successful, the getgrgid_r() function shall return zero;  otherwise,
58       an error number shall be returned to indicate the error.
59

ERRORS

61       The getgrgid() and getgrgid_r() functions may fail if:
62
63       EIO    An I/O error has occurred.
64
65       EINTR  A signal was caught during getgrgid().
66
67       EMFILE All  file  descriptors  available  to  the process are currently
68              open.
69
70       ENFILE The maximum allowable number of files is currently open  in  the
71              system.
72
73       The getgrgid_r() function may fail if:
74
75       ERANGE Insufficient storage was supplied via buffer and bufsize to con‐
76              tain the data to be referenced by the resulting group structure.
77
78       The following sections are informative.
79

EXAMPLES

81       Note that sysconf(_SC_GETGR_R_SIZE_MAX) may return -1 if  there  is  no
82       hard  limit  on  the  size of the buffer needed to store all the groups
83       returned. This example shows how an application can allocate  a  buffer
84       of sufficient size to work with getgrid_r().
85
86
87           long int initlen = sysconf(_SC_GETGR_R_SIZE_MAX);
88           size_t len;
89           if (initlen == -1)
90               /* Default initial length. */
91               len = 1024;
92           else
93               len = (size_t) initlen;
94           struct group result;
95           struct group *resultp;
96           char *buffer = malloc(len);
97           if (buffer == NULL)
98               ...handle error...
99           int e;
100           while ((e = getgrgid_r(42, &result, buffer, len, &resultp)) == ERANGE)
101               {
102               size_t newlen = 2 * len;
103               if (newlen < len)
104                   ...handle error...
105               len = newlen;
106               char *newbuffer = realloc(buffer, len);
107               if (newbuffer == NULL)
108                   ...handle error...
109               buffer = newbuffer;
110               }
111           if (e != 0)
112               ...handle error...
113           free (buffer);
114
115   Finding an Entry in the Group Database
116       The  following example uses getgrgid() to search the group database for
117       a group ID that was previously stored in a stat structure, then  prints
118       out  the group name if it is found. If the group is not found, the pro‐
119       gram prints the numeric value of the group for the entry.
120
121
122           #include <sys/types.h>
123           #include <grp.h>
124           #include <stdio.h>
125           ...
126           struct stat statbuf;
127           struct group *grp;
128           ...
129           if ((grp = getgrgid(statbuf.st_gid)) != NULL)
130               printf(" %-8.8s", grp->gr_name);
131           else
132               printf(" %-8d", statbuf.st_gid);
133           ...
134

APPLICATION USAGE

136       The getgrgid_r() function is thread-safe and shall return values  in  a
137       user-supplied  buffer instead of possibly using a static data area that
138       may be overwritten by each call.
139
140       Portable applications should take into account that it is usual for  an
141       implementation  to return -1 from sysconf() indicating that there is no
142       maximum for _SC_GETGR_R_SIZE_MAX.
143

RATIONALE

145       None.
146

FUTURE DIRECTIONS

148       None.
149

SEE ALSO

151       endgrent(), getgrnam(), sysconf()
152
153       The Base Definitions volume of POSIX.1‐2017, <grp.h>, <sys_types.h>
154
156       Portions of this text are reprinted and reproduced in  electronic  form
157       from  IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
158       table Operating System Interface (POSIX), The Open Group Base  Specifi‐
159       cations  Issue  7, 2018 Edition, Copyright (C) 2018 by the Institute of
160       Electrical and Electronics Engineers, Inc and The Open Group.   In  the
161       event of any discrepancy between this version and the original IEEE and
162       The Open Group Standard, the original IEEE and The Open Group  Standard
163       is  the  referee document. The original Standard can be obtained online
164       at http://www.opengroup.org/unix/online.html .
165
166       Any typographical or formatting errors that appear  in  this  page  are
167       most likely to have been introduced during the conversion of the source
168       files to man page format. To report such errors,  see  https://www.ker
169       nel.org/doc/man-pages/reporting_bugs.html .
170
171
172
173IEEE/The Open Group                  2017                         GETGRGID(3P)
Impressum