Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 109 insertions, 0 deletions

diff --git a/man/man2/setfsgid.2 b/man/man2/setfsgid.2
new file mode 100644
index 0000000..008f095
--- /dev/null
+++ b/man/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 2024-05-02 "Linux man-pages (unreleased)"
+.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>
+.P
+.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)).
+.P
+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 .
+.P
+.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.
+.P
+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)