Debian Codegraph @

upstream/debian-trixie/man2/setgid.2

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