1SETFSGID(2)                Linux Programmer's Manual               SETFSGID(2)
2
3
4

NAME

6       setfsgid - set group identity used for filesystem checks
7

SYNOPSIS

9       #include <sys/fsuid.h>
10
11       int setfsgid(gid_t fsgid);
12

DESCRIPTION

14       On  Linux,  a  process  has both a filesystem group ID and an effective
15       group ID.  The (Linux-specific) filesystem group ID is used for permis‐
16       sions  checking  when accessing filesystem objects, while the effective
17       group ID is used for some other kinds of permissions checks  (see  cre‐
18       dentials(7)).
19
20       Normally, the value of the process's filesystem group ID is the same as
21       the value of its effective group ID.  This is so,  because  whenever  a
22       process's  effective  group  ID is changed, the kernel also changes the
23       filesystem group ID to be the same as the new value  of  the  effective
24       group  ID.  A process can cause the value of its filesystem group ID to
25       diverge from its effective group ID by using setfsgid() to  change  its
26       filesystem group ID to the value given in fsgid.
27
28       setfsgid() will succeed only if the caller is the superuser or if fsgid
29       matches either the caller's real group ID, effective  group  ID,  saved
30       set-group-ID, or current the filesystem user ID.
31

RETURN VALUE

33       On  both success and failure, this call returns the previous filesystem
34       group ID of the caller.
35

VERSIONS

37       This system call is present in Linux since version 1.2.
38

CONFORMING TO

40       setfsgid() is Linux-specific and should not be  used  in  programs  in‐
41       tended to be portable.
42

NOTES

44       The filesystem group ID concept and the setfsgid() system call were in‐
45       vented for historical reasons that are no longer applicable  on  modern
46       Linux kernels.  See setfsuid(2) for a discussion of why the use of both
47       setfsuid(2) and setfsgid() is nowadays unneeded.
48
49       The original Linux setfsgid() system call supported only  16-bit  group
50       IDs.  Subsequently, Linux 2.4 added setfsgid32() supporting 32-bit IDs.
51       The glibc setfsgid() wrapper  function  transparently  deals  with  the
52       variation across kernel versions.
53
54   C library/kernel differences
55       In glibc 2.15 and earlier, when the wrapper for this system call deter‐
56       mines that the argument can't be passed to the kernel  without  integer
57       truncation (because the kernel is old and does not support 32-bit group
58       IDs), it will return -1 and set errno to EINVAL without attempting  the
59       system call.
60

BUGS

62       No  error  indications  of any kind are returned to the caller, and the
63       fact that both successful and unsuccessful calls return the same  value
64       makes it impossible to directly determine whether the call succeeded or
65       failed.  Instead, the caller must resort to looking at the return value
66       from  a  further call such as setfsgid(-1) (which will always fail), in
67       order to determine if  a  preceding  call  to  setfsgid()  changed  the
68       filesystem  group ID.  At the very least, EPERM should be returned when
69       the call fails (because the caller lacks the CAP_SETGID capability).
70

SEE ALSO

72       kill(2), setfsuid(2), capabilities(7), credentials(7)
73

COLOPHON

75       This page is part of release 5.13 of the Linux  man-pages  project.   A
76       description  of  the project, information about reporting bugs, and the
77       latest    version    of    this    page,    can     be     found     at
78       https://www.kernel.org/doc/man-pages/.
79
80
81
82Linux                             2021-03-22                       SETFSGID(2)
Impressum