1GETGROUPS(3P)              POSIX Programmer's Manual             GETGROUPS(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
11

NAME

13       getgroups — get supplementary group IDs
14

SYNOPSIS

16       #include <unistd.h>
17
18       int getgroups(int gidsetsize, gid_t grouplist[]);
19

DESCRIPTION

21       The getgroups() function shall fill in the  array  grouplist  with  the
22       current supplementary group IDs of the calling process. It is implemen‐
23       tation-defined whether getgroups() also returns the effective group  ID
24       in the grouplist array.
25
26       The  gidsetsize  argument specifies the number of elements in the array
27       grouplist.  The actual number of group IDs stored in the array shall be
28       returned.   The  values  of  array entries with indices greater than or
29       equal to the value returned are undefined.
30
31       If gidsetsize is 0, getgroups() shall return the number  of  group  IDs
32       that  it  would otherwise return without modifying the array pointed to
33       by grouplist.
34
35       If the effective group ID of the process is returned with  the  supple‐
36       mentary  group  IDs, the value returned shall always be greater than or
37       equal to one and less than or equal to the value of {NGROUPS_MAX}+1.
38

RETURN VALUE

40       Upon successful completion, the number of supplementary group IDs shall
41       be  returned. A return value of −1 indicates failure and errno shall be
42       set to indicate the error.
43

ERRORS

45       The getgroups() function shall fail if:
46
47       EINVAL The gidsetsize argument is non-zero and less than the number  of
48              group IDs that would have been returned.
49
50       The following sections are informative.
51

EXAMPLES

53   Getting the Supplementary Group IDs of the Calling Process
54       The following example places the current supplementary group IDs of the
55       calling process into the group array.
56
57           #include <sys/types.h>
58           #include <unistd.h>
59           ...
60           gid_t *group;
61           int nogroups;
62           long ngroups_max;
63
64           ngroups_max = sysconf(_SC_NGROUPS_MAX) + 1;
65           group = (gid_t *)malloc(ngroups_max *sizeof(gid_t));
66
67           ngroups = getgroups(ngroups_max, group);
68

APPLICATION USAGE

70       None.
71

RATIONALE

73       The related function setgroups() is a privileged operation  and  there‐
74       fore is not covered by this volume of POSIX.1‐2008.
75
76       As  implied  by  the  definition of supplementary groups, the effective
77       group ID may appear in the array returned by getgroups() or it  may  be
78       returned only by getegid().  Duplication may exist, but the application
79       needs to call getegid() to be sure of getting all of  the  information.
80       Various  implementation  variations  and administrative sequences cause
81       the set of groups appearing in the result of  getgroups()  to  vary  in
82       order  and  as to whether the effective group ID is included, even when
83       the set of groups is the same (in the mathematical sense  of  ``set'').
84       (The  history  of a process and its parents could affect the details of
85       the result.)
86
87       Application developers should note that {NGROUPS_MAX} is not  necessar‐
88       ily a constant on all implementations.
89

FUTURE DIRECTIONS

91       None.
92

SEE ALSO

94       getegid(), setgid()
95
96       The Base Definitions volume of POSIX.1‐2008, <sys_types.h>, <unistd.h>
97
99       Portions  of  this text are reprinted and reproduced in electronic form
100       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
101       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
102       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
103       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
104       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
105       event of any discrepancy between this version and the original IEEE and
106       The Open Group Standard, the original IEEE and The Open Group  Standard
107       is  the  referee document. The original Standard can be obtained online
108       at http://www.unix.org/online.html .
109
110       Any typographical or formatting errors that appear  in  this  page  are
111       most likely to have been introduced during the conversion of the source
112       files to man page format. To report such errors,  see  https://www.ker
113       nel.org/doc/man-pages/reporting_bugs.html .
114
115
116
117IEEE/The Open Group                  2013                        GETGROUPS(3P)
Impressum