diff options
Diffstat (limited to 'man2/setfsgid.2')
| -rw-r--r-- | man2/setfsgid.2 | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/man2/setfsgid.2 b/man2/setfsgid.2 new file mode 100644 index 0000000..43b5507 --- /dev/null +++ b/man2/setfsgid.2 @@ -0,0 +1,109 @@ +.\" Copyright (C) 1995, Thomas K. Dyas <tdyas@eden.rutgers.edu> +.\" and Copyright (C) 2019, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Created 1995-08-06 Thomas K. Dyas <tdyas@eden.rutgers.edu> +.\" Modified 2000-07-01 aeb +.\" Modified 2002-07-23 aeb +.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added notes on capability requirements +.\" +.TH setfsgid 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +setfsgid \- set group identity used for filesystem checks +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/fsuid.h> +.PP +.BI "[[deprecated]] int setfsgid(gid_t " fsgid ); +.fi +.SH DESCRIPTION +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 +.BR credentials (7)). +.PP +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 +.BR setfsgid () +to change its filesystem group ID to the value given in +.IR fsgid . +.PP +.BR setfsgid () +will succeed only if the caller is the superuser or if +.I fsgid +matches either the caller's real group ID, effective group ID, +saved set-group-ID, or current the filesystem user ID. +.SH RETURN VALUE +On both success and failure, +this call returns the previous filesystem group ID of the caller. +.SH STANDARDS +Linux. +.SH HISTORY +Linux 1.2. +.\" Linux 1.1.44 +.\" and in libc since libc 4.7.6. +.SS 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 \fIerrno\fP to +.B EINVAL +without attempting +the system call. +.SH NOTES +The filesystem group ID concept and the +.BR setfsgid () +system call were invented for historical reasons that are +no longer applicable on modern Linux kernels. +See +.BR setfsuid (2) +for a discussion of why the use of both +.BR setfsuid (2) +and +.BR setfsgid () +is nowadays unneeded. +.PP +The original Linux +.BR setfsgid () +system call supported only 16-bit group IDs. +Subsequently, Linux 2.4 added +.BR setfsgid32 () +supporting 32-bit IDs. +The glibc +.BR setfsgid () +wrapper function transparently deals with the variation across kernel versions. +.SH BUGS +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 +.I setfsgid(\-1) +(which will always fail), in order to determine if a preceding call to +.BR setfsgid () +changed the filesystem group ID. +At the very +least, +.B EPERM +should be returned when the call fails (because the caller lacks the +.B CAP_SETGID +capability). +.SH SEE ALSO +.BR kill (2), +.BR setfsuid (2), +.BR capabilities (7), +.BR credentials (7) |