]> git.saurik.com Git - apple/xnu.git/blob - bsd/man/man2/getgroups.2
xnu-6153.11.26.tar.gz
[apple/xnu.git] / bsd / man / man2 / getgroups.2
1 .\"
2 .\" Copyright (c) 2008-2011 Apple Inc. All rights reserved.
3 .\"
4 .\" @APPLE_LICENSE_HEADER_START@
5 .\"
6 .\" This file contains Original Code and/or Modifications of Original Code
7 .\" as defined in and that are subject to the Apple Public Source License
8 .\" Version 2.0 (the 'License'). You may not use this file except in
9 .\" compliance with the License. Please obtain a copy of the License at
10 .\" http://www.opensource.apple.com/apsl/ and read it before using this
11 .\" file.
12 .\"
13 .\" The Original Code and all software distributed under the License are
14 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 .\" Please see the License for the specific language governing rights and
19 .\" limitations under the License.
20 .\"
21 .\" @APPLE_LICENSE_HEADER_END@
22 .\"
23 .\"
24 .\" $NetBSD: getgroups.2,v 1.8 1995/02/27 12:32:57 cgd Exp $
25 .\"
26 .\" Copyright (c) 1983, 1991, 1993
27 .\" The Regents of the University of California. All rights reserved.
28 .\"
29 .\" Redistribution and use in source and binary forms, with or without
30 .\" modification, are permitted provided that the following conditions
31 .\" are met:
32 .\" 1. Redistributions of source code must retain the above copyright
33 .\" notice, this list of conditions and the following disclaimer.
34 .\" 2. Redistributions in binary form must reproduce the above copyright
35 .\" notice, this list of conditions and the following disclaimer in the
36 .\" documentation and/or other materials provided with the distribution.
37 .\" 3. All advertising materials mentioning features or use of this software
38 .\" must display the following acknowledgement:
39 .\" This product includes software developed by the University of
40 .\" California, Berkeley and its contributors.
41 .\" 4. Neither the name of the University nor the names of its contributors
42 .\" may be used to endorse or promote products derived from this software
43 .\" without specific prior written permission.
44 .\"
45 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
48 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
55 .\" SUCH DAMAGE.
56 .\"
57 .\" @(#)getgroups.2 8.2 (Berkeley) 4/16/94
58 .\"
59 .Dd October 28, 2011
60 .Dt GETGROUPS 2
61 .Os BSD 4.2
62 .Sh NAME
63 .Nm getgroups
64 .Nd get group access list
65 .Sh SYNOPSIS
66 .Fd #include <unistd.h>
67 .Ft int
68 .Fo getgroups
69 .Fa "int gidsetsize"
70 .Fa "gid_t grouplist[]"
71 .Fc
72 .Sh DESCRIPTION
73 .Fn getgroups
74 gets the current group access list of the current user process
75 and stores it in the array
76 .Fa grouplist[] .
77 The parameter
78 .Fa gidsetsize
79 indicates the number of entries that may be placed in
80 .Fa grouplist[] .
81 .Fn getgroups
82 returns the actual number of groups returned in
83 .Fa grouplist[] .
84 However, no more than
85 .Dv {NGROUPS_MAX}
86 will be returned. If
87 .Fa gidsetsize
88 is 0,
89 .Fn getgroups
90 returns the number of groups without modifying the
91 .Fa grouplist[]
92 array.
93 .Pp
94 Calling
95 .Xr initgroups 3
96 to opt-in for supplementary groups will cause
97 .Fn getgroups
98 to return a single entry, the GID that was passed to
99 .Xr initgroups 3 .
100 .Pp
101 To provide compatibility with applications that use
102 .Fn getgroups
103 in environments where users may be in more than
104 .Dv {NGROUPS_MAX}
105 groups, a variant of
106 .Fn getgroups ,
107 obtained when compiling with either the macros
108 .Dv _DARWIN_UNLIMITED_GETGROUPS
109 or
110 .Dv _DARWIN_C_SOURCE
111 defined, can be used that is not limited to
112 .Dv {NGROUPS_MAX}
113 groups.
114 However, this variant only returns the user's default group access list and
115 not the group list modified by a call to
116 .Xr setgroups 2
117 (either in the current process or an ancestor process).
118 Use of
119 .Xr setgroups 2
120 is highly discouraged, and there is no foolproof way to determine if it has
121 been previously called.
122 .Sh RETURN VALUES
123 A successful call returns the number of groups in the group set.
124 Otherwise, a value of -1 is returned and the global integer variable
125 .Va errno
126 is set to indicate the error.
127 .Sh ERRORS
128 The possible errors for
129 .Fn getgroups
130 are:
131 .Bl -tag -width Er
132 .\" ==========
133 .It Bq Er EFAULT
134 The argument
135 .Fa grouplist
136 specifies an invalid address.
137 .\" ==========
138 .It Bq Er EINVAL
139 The argument
140 .Fa gidsetsize ,
141 although non-zero,
142 is smaller than the number of groups in the group set.
143 .El
144 .Sh LEGACY SYNOPSIS
145 .Fd #include <sys/param.h>
146 .Fd #include <sys/types.h>
147 .Fd #include <unistd.h>
148 .Pp
149 The include files
150 .In sys/param.h
151 and
152 .In sys/types.h
153 are necessary.
154 .Sh SEE ALSO
155 .Xr setgroups 2 ,
156 .Xr initgroups 3 ,
157 .Xr compat 5
158 .Sh HISTORY
159 The
160 .Fn getgroups
161 function call appeared in
162 .Bx 4.2 .