Debian Codegraph @

upstream/debian-unstable/man2/setfsgid.2

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