setfsgid(2)

1setfsgid(2)                   System Calls Manual                  setfsgid(2)
2
3
4

NAME

6       setfsgid - set group identity used for filesystem checks
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/fsuid.h>
13
14       [[deprecated]] int setfsgid(gid_t fsgid);
15

DESCRIPTION

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

RETURN VALUE

36       On  both success and failure, this call returns the previous filesystem
37       group ID of the caller.
38

STANDARDS

40       Linux.
41

HISTORY

43       Linux 1.2.
44
45   C library/kernel differences
46       In glibc 2.15 and earlier, when the wrapper for this system call deter‐
47       mines  that  the argument can't be passed to the kernel without integer
48       truncation (because the kernel is old and does not support 32-bit group
49       IDs),  it will return -1 and set errno to EINVAL without attempting the
50       system call.
51

NOTES

53       The filesystem group ID concept and the setfsgid() system call were in‐
54       vented  for  historical reasons that are no longer applicable on modern
55       Linux kernels.  See setfsuid(2) for a discussion of why the use of both
56       setfsuid(2) and setfsgid() is nowadays unneeded.
57
58       The  original  Linux setfsgid() system call supported only 16-bit group
59       IDs.  Subsequently, Linux 2.4 added setfsgid32() supporting 32-bit IDs.
60       The  glibc  setfsgid()  wrapper  function  transparently deals with the
61       variation across kernel versions.
62

BUGS

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