Debian Codegraph @

upstream/debian-unstable/man2/setgid.2

raw
1 .\" Copyright 1994, Graeme W. Wilford <[email protected]>
2 .\" Copyright 2010-2015, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH setgid 2 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 setgid \- set group identity
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <unistd.h>
16 .P
17 .BI "int setgid(gid_t " gid );
18 .fi
19 .SH DESCRIPTION
20 .BR setgid ()
21 sets the effective group ID of the calling process.
22 If the calling process is privileged (more precisely: has the
23 .B CAP_SETGID
24 capability in its user namespace),
25 the real GID and saved set-group-ID are also set.
26 .P
27 Under Linux,
28 .BR setgid ()
29 is implemented like the POSIX version with the
30 .B _POSIX_SAVED_IDS
31 feature.
32 This allows a set-group-ID program that is not set-user-ID-root
33 to drop all of its group
34 privileges, do some un-privileged work, and then reengage the original
35 effective group ID in a secure manner.
36 .SH RETURN VALUE
37 On success, zero is returned.
38 On error, \-1 is returned, and
39 .I errno
40 is set to indicate the error.
41 .SH ERRORS
42 .TP
43 .B EINVAL
44 The group ID specified in
45 .I gid
46 is not valid in this user namespace.
47 .TP
48 .B EPERM
49 The calling process is not privileged (does not have the
50 .B CAP_SETGID
51 capability in its user namespace), and
52 .I gid
53 does not match the real group ID or saved set-group-ID of
54 the calling process.
55 .SH VERSIONS
56 .SS C library/kernel differences
57 At the kernel level, user IDs and group IDs are a per-thread attribute.
58 However, POSIX requires that all threads in a process
59 share the same credentials.
60 The NPTL threading implementation handles the POSIX requirements by
61 providing wrapper functions for
62 the various system calls that change process UIDs and GIDs.
63 These wrapper functions (including the one for
64 .BR setgid ())
65 employ a signal-based technique to ensure
66 that when one thread changes credentials,
67 all of the other threads in the process also change their credentials.
68 For details, see
69 .BR nptl (7).
70 .SH STANDARDS
71 POSIX.1-2024.
72 .SH HISTORY
73 POSIX.1-2001, SVr4.
74 .P
75 The original Linux
76 .BR setgid ()
77 system call supported only 16-bit group IDs.
78 Subsequently, Linux 2.4 added
79 .BR setgid32 ()
80 supporting 32-bit IDs.
81 The glibc
82 .BR setgid ()
83 wrapper function transparently deals with the variation across kernel versions.
84 .SH SEE ALSO
85 .BR getgid (2),
86 .BR setegid (2),
87 .BR setregid (2),
88 .BR capabilities (7),
89 .BR credentials (7),
90 .BR user_namespaces (7)