]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) | |
4 | .\" | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" | |
25 | .\" Modified Thu Oct 31 12:04:29 1996 by Eric S. Raymond <esr@thyrsus.com> | |
305a0578 | 26 | .\" Modified, 27 May 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
27 | .\" Added notes on capability requirements |
28 | .\" | |
cc4615cc | 29 | .TH GETGROUPS 2 2007-07-26 "Linux" "Linux Programmer's Manual" |
fea681da MK |
30 | .SH NAME |
31 | getgroups, setgroups \- get/set list of supplementary group IDs | |
32 | .SH SYNOPSIS | |
33 | .B #include <sys/types.h> | |
34 | .br | |
35 | .B #include <unistd.h> | |
36 | .sp | |
37 | .BI "int getgroups(int " size ", gid_t " list []); | |
38 | .sp | |
39 | .B #include <grp.h> | |
40 | .sp | |
41 | .BI "int setgroups(size_t " size ", const gid_t *" list ); | |
cc4615cc MK |
42 | .sp |
43 | .in -4n | |
44 | Feature Test Macro Requirements for glibc (see | |
45 | .BR feature_test_macros (7)): | |
46 | .in | |
47 | .sp | |
48 | .BR setgroups (): | |
49 | _BSD_SOURCE | |
fea681da MK |
50 | .SH DESCRIPTION |
51 | .TP | |
e511ffb6 | 52 | .BR getgroups () |
fea681da MK |
53 | Up to |
54 | .I size | |
55 | supplementary group IDs (of the calling process) are returned in | |
56 | .IR list . | |
57 | It is unspecified whether the effective group ID of the calling process | |
c13182ef MK |
58 | is included in the returned list. |
59 | (Thus, an application should also call | |
fea681da MK |
60 | .BR getegid (2) |
61 | and add or remove the resulting value.) | |
62 | If | |
63 | .I size | |
64 | is zero, | |
65 | .I list | |
66 | is not modified, but the total number of supplementary group IDs for the | |
67 | process is returned. | |
68 | .TP | |
e511ffb6 | 69 | .BR setgroups () |
fea681da MK |
70 | Sets the supplementary group IDs for the process. |
71 | Appropriate privileges (Linux: the | |
72 | .B CAP_SETGID | |
73 | capability) are required. | |
74 | .SH "RETURN VALUE" | |
75 | .TP | |
e511ffb6 | 76 | .BR getgroups () |
fea681da MK |
77 | On success, the number of supplementary group IDs is returned. |
78 | On error, \-1 is returned, and | |
79 | .I errno | |
80 | is set appropriately. | |
81 | .TP | |
e511ffb6 | 82 | .BR setgroups () |
c13182ef MK |
83 | On success, zero is returned. |
84 | On error, \-1 is returned, and | |
fea681da MK |
85 | .I errno |
86 | is set appropriately. | |
87 | .SH ERRORS | |
88 | .TP | |
89 | .B EFAULT | |
90 | .I list | |
91 | has an invalid address. | |
92 | .TP | |
93 | .B EINVAL | |
94 | For | |
e511ffb6 | 95 | .BR setgroups (), |
fea681da MK |
96 | .I size |
97 | is greater than | |
98 | .B NGROUPS | |
99 | (32 for Linux 2.0.32). | |
100 | For | |
e511ffb6 | 101 | .BR getgroups (), |
fea681da MK |
102 | .I size |
103 | is less than the number of supplementary group IDs, but is not zero. | |
104 | .TP | |
105 | .B EPERM | |
c13182ef | 106 | The calling process has insufficient privilege to call |
e511ffb6 | 107 | .BR setgroups (). |
a1d5f77c MK |
108 | .SH "CONFORMING TO" |
109 | SVr4, 4.3BSD. | |
110 | The | |
111 | .BR getgroups () | |
112 | function is in POSIX.1-2001. | |
113 | Since | |
114 | .BR setgroups () | |
115 | requires privilege, it is not covered by POSIX.1-2001. | |
fea681da | 116 | .SH NOTES |
682edefb MK |
117 | A process can have up to at least |
118 | .B NGROUPS_MAX | |
119 | supplementary group IDs | |
1c44bd5b MK |
120 | in addition to the effective group ID. |
121 | The set of supplementary group IDs | |
fea681da | 122 | is inherited from the parent process and may be changed using |
e511ffb6 | 123 | .BR setgroups (). |
fea681da MK |
124 | The maximum number of supplementary group IDs can be found using |
125 | .BR sysconf (3): | |
126 | .nf | |
6d12800e | 127 | |
fea681da MK |
128 | long ngroups_max; |
129 | ngroups_max = sysconf(_SC_NGROUPS_MAX); | |
6d12800e | 130 | |
fea681da MK |
131 | .fi |
132 | The maximal return value of | |
e511ffb6 | 133 | .BR getgroups () |
fea681da | 134 | cannot be larger than one more than the value obtained this way. |
fea681da MK |
135 | .SH "SEE ALSO" |
136 | .BR getgid (2), | |
137 | .BR setgid (2), | |
138 | .BR initgroups (3), | |
139 | .BR capabilities (7) |