]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C), 1994, Graeme W. Wilford. (Wilf.) |
716db1ba | 2 | .\" and Copyright (C) 2010, 2015, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da | 25 | .\" |
c13182ef | 26 | .\" Fri Jul 29th 12:56:44 BST 1994 Wilf. <G.Wilford@ee.surrey.ac.uk> |
fea681da MK |
27 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> |
28 | .\" Modified 2002-03-09 by aeb | |
29 | .\" | |
9ba01802 | 30 | .TH SETGID 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da MK |
31 | .SH NAME |
32 | setgid \- set group identity | |
33 | .SH SYNOPSIS | |
34 | .B #include <sys/types.h> | |
35 | .br | |
36 | .B #include <unistd.h> | |
68e4db0a | 37 | .PP |
fea681da MK |
38 | .BI "int setgid(gid_t " gid ); |
39 | .SH DESCRIPTION | |
e511ffb6 | 40 | .BR setgid () |
a1ffe9f5 | 41 | sets the effective group ID of the calling process. |
a1dbd698 | 42 | If the calling process is privileged (more precisely: has the |
52f2c8fb | 43 | .B CAP_SETGID |
6f22721e MK |
44 | capability in its user namespace), |
45 | the real GID and saved set-group-ID are also set. | |
efeece04 | 46 | .PP |
c13182ef | 47 | Under Linux, |
e511ffb6 | 48 | .BR setgid () |
8c4f34f8 MK |
49 | is implemented like the POSIX version with the |
50 | .B _POSIX_SAVED_IDS | |
51 | feature. | |
d9df8ff8 | 52 | This allows a set-group-ID program that is not set-user-ID-root |
880f5b4b | 53 | to drop all of its group |
3b777aff | 54 | privileges, do some un-privileged work, and then reengage the original |
fea681da | 55 | effective group ID in a secure manner. |
47297adb | 56 | .SH RETURN VALUE |
c13182ef MK |
57 | On success, zero is returned. |
58 | On error, \-1 is returned, and | |
fea681da MK |
59 | .I errno |
60 | is set appropriately. | |
61 | .SH ERRORS | |
62 | .TP | |
0076479c MK |
63 | .B EINVAL |
64 | The group ID specified in | |
65 | .I gid | |
66 | is not valid in this user namespace. | |
67 | .TP | |
fea681da | 68 | .B EPERM |
d3c8b3e9 | 69 | The calling process is not privileged (does not have the |
51c11a70 | 70 | \fBCAP_SETGID\fP capability in its user namespace), and |
fea681da | 71 | .I gid |
7a8fe6a9 | 72 | does not match the real group ID or saved set-group-ID of |
fea681da | 73 | the calling process. |
47297adb | 74 | .SH CONFORMING TO |
ea85e550 | 75 | POSIX.1-2001, POSIX.1-2008, SVr4. |
6dc1520b MK |
76 | .SH NOTES |
77 | The original Linux | |
78 | .BR setgid () | |
79 | system call supported only 16-bit group IDs. | |
c5662d5d | 80 | Subsequently, Linux 2.4 added |
6dc1520b MK |
81 | .BR setgid32 () |
82 | supporting 32-bit IDs. | |
83 | The glibc | |
84 | .BR setgid () | |
85 | wrapper function transparently deals with the variation across kernel versions. | |
716db1ba | 86 | .\" |
0722a578 | 87 | .SS C library/kernel differences |
716db1ba MK |
88 | At the kernel level, user IDs and group IDs are a per-thread attribute. |
89 | However, POSIX requires that all threads in a process | |
90 | share the same credentials. | |
91 | The NPTL threading implementation handles the POSIX requirements by | |
92 | providing wrapper functions for | |
93 | the various system calls that change process UIDs and GIDs. | |
94 | These wrapper functions (including the one for | |
95 | .BR setgid ()) | |
96 | employ a signal-based technique to ensure | |
97 | that when one thread changes credentials, | |
98 | all of the other threads in the process also change their credentials. | |
99 | For details, see | |
100 | .BR nptl (7). | |
47297adb | 101 | .SH SEE ALSO |
fea681da MK |
102 | .BR getgid (2), |
103 | .BR setegid (2), | |
104 | .BR setregid (2), | |
53a1443c | 105 | .BR capabilities (7), |
0076479c | 106 | .BR credentials (7), |
f58fb24f | 107 | .BR user_namespaces (7) |