Debian Codegraph @

upstream/debian-trixie/man2/setfsgid.2

raw
1 .\" Copyright (C) 1995, Thomas K. Dyas <[email protected]>
2 .\" and Copyright (C) 2019, Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Created 1995-08-06 Thomas K. Dyas <[email protected]>
7 .\" Modified 2000-07-01 aeb
8 .\" Modified 2002-07-23 aeb
9 .\" Modified, 27 May 2004, Michael Kerrisk <[email protected]>
10 .\" Added notes on capability requirements
11 .\"
12 .TH setfsgid 2 2024-05-02 "Linux man-pages 6.9.1"
13 .SH NAME
14 setfsgid \- set group identity used for filesystem checks
15 .SH LIBRARY
16 Standard C library
17 .RI ( libc ", " \-lc )
18 .SH SYNOPSIS
19 .nf
20 .B #include <sys/fsuid.h>
21 .P
22 .BI "[[deprecated]] int setfsgid(gid_t " fsgid );
23 .fi
24 .SH DESCRIPTION
25 On Linux, a process has both a filesystem group ID and an effective group ID.
26 The (Linux-specific) filesystem group ID is used
27 for permissions checking when accessing filesystem objects,
28 while the effective group ID is used for some other kinds
29 of permissions checks (see
30 .BR credentials (7)).
31 .P
32 Normally, the value of the process's filesystem group ID
33 is the same as the value of its effective group ID.
34 This is so, because whenever a process's effective group ID is changed,
35 the kernel also changes the filesystem group ID to be the same as
36 the new value of the effective group ID.
37 A process can cause the value of its filesystem group ID to diverge
38 from its effective group ID by using
39 .BR setfsgid ()
40 to change its filesystem group ID to the value given in
41 .IR fsgid .
42 .P
43 .BR setfsgid ()
44 will succeed only if the caller is the superuser or if
45 .I fsgid
46 matches either the caller's real group ID, effective group ID,
47 saved set-group-ID, or current the filesystem user ID.
48 .SH RETURN VALUE
49 On both success and failure,
50 this call returns the previous filesystem group ID of the caller.
51 .SH STANDARDS
52 Linux.
53 .SH HISTORY
54 Linux 1.2.
55 .\" Linux 1.1.44
56 .\" and in libc since libc 4.7.6.
57 .SS C library/kernel differences
58 In glibc 2.15 and earlier,
59 when the wrapper for this system call determines that the argument can't be
60 passed to the kernel without integer truncation (because the kernel
61 is old and does not support 32-bit group IDs),
62 it will return \-1 and set \fIerrno\fP to
63 .B EINVAL
64 without attempting
65 the system call.
66 .SH NOTES
67 The filesystem group ID concept and the
68 .BR setfsgid ()
69 system call were invented for historical reasons that are
70 no longer applicable on modern Linux kernels.
71 See
72 .BR setfsuid (2)
73 for a discussion of why the use of both
74 .BR setfsuid (2)
75 and
76 .BR setfsgid ()
77 is nowadays unneeded.
78 .P
79 The original Linux
80 .BR setfsgid ()
81 system call supported only 16-bit group IDs.
82 Subsequently, Linux 2.4 added
83 .BR setfsgid32 ()
84 supporting 32-bit IDs.
85 The glibc
86 .BR setfsgid ()
87 wrapper function transparently deals with the variation across kernel versions.
88 .SH BUGS
89 No error indications of any kind are returned to the caller,
90 and the fact that both successful and unsuccessful calls return
91 the same value makes it impossible to directly determine
92 whether the call succeeded or failed.
93 Instead, the caller must resort to looking at the return value
94 from a further call such as
95 .I setfsgid(\-1)
96 (which will always fail), in order to determine if a preceding call to
97 .BR setfsgid ()
98 changed the filesystem group ID.
99 At the very
100 least,
101 .B EPERM
102 should be returned when the call fails (because the caller lacks the
103 .B CAP_SETGID
104 capability).
105 .SH SEE ALSO
106 .BR kill (2),
107 .BR setfsuid (2),
108 .BR capabilities (7),
109 .BR credentials (7)