Merging upstream version 6.8.

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

1 files changed, 127 insertions, 0 deletions

diff --git a/man/man2/setfsuid.2 b/man/man2/setfsuid.2
new file mode 100644
index 0000000..84d6891
--- /dev/null
+++ b/man/man2/setfsuid.2
@@ -0,0 +1,127 @@
+.\" Copyright (C) 1995, Thomas K. Dyas <tdyas@eden.rutgers.edu>
+.\" and Copyright (C) 2013, 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 setfsuid 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+setfsuid \- set user 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 setfsuid(uid_t " fsuid );
+.fi
+.SH DESCRIPTION
+On Linux, a process has both a filesystem user ID and an effective user ID.
+The (Linux-specific) filesystem user ID is used
+for permissions checking when accessing filesystem objects,
+while the effective user ID is used for various other kinds
+of permissions checks (see
+.BR credentials (7)).
+.P
+Normally, the value of the process's filesystem user ID
+is the same as the value of its effective user ID.
+This is so, because whenever a process's effective user ID is changed,
+the kernel also changes the filesystem user ID to be the same as
+the new value of the effective user ID.
+A process can cause the value of its filesystem user ID to diverge
+from its effective user ID by using
+.BR setfsuid ()
+to change its filesystem user ID to the value given in
+.IR fsuid .
+.P
+Explicit calls to
+.BR setfsuid ()
+and
+.BR setfsgid (2)
+are (were) usually used only by programs such as the Linux NFS server that
+need to change what user and group ID is used for file access without a
+corresponding change in the real and effective user and group IDs.
+A change in the normal user IDs for a program such as the NFS server
+is (was) a security hole that can expose it to unwanted signals.
+(However, this issue is historical; see below.)
+.P
+.BR setfsuid ()
+will succeed only if the caller is the superuser or if
+.I fsuid
+matches either the caller's real user ID, effective user ID,
+saved set-user-ID, or current filesystem user ID.
+.SH RETURN VALUE
+On both success and failure,
+this call returns the previous filesystem user ID of the caller.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 1.2.
+.\" Linux 1.1.44
+.\" and in libc since libc 4.7.6.
+.P
+At the time when this system call was introduced, one process
+could send a signal to another process with the same effective user ID.
+This meant that if a privileged process changed its effective user ID
+for the purpose of file permission checking,
+then it could become vulnerable to receiving signals
+sent by another (unprivileged) process with the same user ID.
+The filesystem user ID attribute was thus added to allow a process to
+change its user ID for the purposes of file permission checking without
+at the same time becoming vulnerable to receiving unwanted signals.
+Since Linux 2.0, signal permission handling is different (see
+.BR kill (2)),
+with the result that a process can change its effective user ID
+without being vulnerable to receiving signals from unwanted processes.
+Thus,
+.BR setfsuid ()
+is nowadays unneeded and should be avoided in new applications
+(likewise for
+.BR setfsgid (2)).
+.P
+The original Linux
+.BR setfsuid ()
+system call supported only 16-bit user IDs.
+Subsequently, Linux 2.4 added
+.BR setfsuid32 ()
+supporting 32-bit IDs.
+The glibc
+.BR setfsuid ()
+wrapper function transparently deals with the variation across kernel versions.
+.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 user IDs),
+it will return \-1 and set \fIerrno\fP to
+.B EINVAL
+without attempting
+the system call.
+.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 setfsuid(\-1)
+(which will always fail), in order to determine if a preceding call to
+.BR setfsuid ()
+changed the filesystem user ID.
+At the very
+least,
+.B EPERM
+should be returned when the call fails (because the caller lacks the
+.B CAP_SETUID
+capability).
+.SH SEE ALSO
+.BR kill (2),
+.BR setfsgid (2),
+.BR capabilities (7),
+.BR credentials (7)