Section: Linux Programmer's Manual (2)
setfsgid - set group identity used for filesystem checks
int setfsgid(uid_t fsgid);
On Linux, a process has both a filesystem group ID and an effective group ID.
The (Linux-specific) filesystem group ID is used
for permissions checking when accessing filesystem objects,
while the effective group ID is used for some other kinds
of permissions checks (see
Normally, the value of the process's filesystem group ID
is the same as the value of its effective group ID.
This is so, because whenever a process's effective group ID is changed,
the kernel also changes the filesystem group ID to be the same as
the new value of the effective group ID.
A process can cause the value of its filesystem group ID to diverge
from its effective group ID by using
to change its filesystem group ID to the value given in
will succeed only if the caller is the superuser or if
matches either the caller's real group ID, effective group ID,
saved set-group-ID, or current the filesystem user ID.
On both success and failure,
this call returns the previous filesystem group ID of the caller.
This system call is present in Linux since version 1.2.
is Linux-specific and should not be used in programs intended
to be portable.
The filesystem group ID concept and the
system call were invented for historical reasons that are
no longer applicable on modern Linux kernels.
for a discussion of why the use of both
is nowadays unneeded.
The original Linux
system call supported only 16-bit group IDs.
Subsequently, Linux 2.4 added
supporting 32-bit IDs.
wrapper function transparently deals with the variation across kernel versions.
C library/kernel differences
In glibc 2.15 and earlier,
when the wrapper for this system call determines that the argument can't be
passed to the kernel without integer truncation (because the kernel
is old and does not support 32-bit group IDs),
it will return -1 and set errno
the system call.
No error indications of any kind are returned to the caller,
and the fact that both successful and unsuccessful calls return
the same value makes it impossible to directly determine
whether the call succeeded or failed.
Instead, the caller must resort to looking at the return value
from a further call such as
(which will always fail), in order to determine if a preceding call to
changed the filesystem group ID.
At the very
should be returned when the call fails (because the caller lacks the
This page is part of release 5.04 of the Linux
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at