(split) LDP: Update original to LDP v3.54

[linuxjm/LDP_man-pages.git] / original / man2 / setfsuid.2

diff --git a/original/man2/setfsuid.2 b/original/man2/setfsuid.2
index a8add87..dcf9cad 100644 (file)
--- a/original/man2/setfsuid.2
+++ b/original/man2/setfsuid.2
@@ -28,25 +28,25 @@
 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"     Added notes on capability requirements
 .\"
-.TH SETFSUID 2 2010-11-22 "Linux" "Linux Programmer's Manual"
+.TH SETFSUID 2 2013-08-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
-setfsuid \- set user identity used for file system checks
+setfsuid \- set user identity used for filesystem checks
 .SH SYNOPSIS
-.B #include <unistd.h>
-/* glibc uses <sys/fsuid.h> */
+.B #include <sys/fsuid.h>
 .sp
 .BI "int setfsuid(uid_t " fsuid );
 .SH DESCRIPTION
 The system call
 .BR setfsuid ()
-sets the user ID that the Linux kernel uses to check for all accesses
-to the file system.
+changes the value of the caller's filesystem user ID\(emthe
+user ID that the Linux kernel uses to check for all accesses
+to the filesystem.
 Normally, the value of
-.I fsuid
+the filesystem user ID
 will shadow the value of the effective user ID.
 In fact, whenever the
 effective user ID is changed,
-.I fsuid
+the filesystem user ID
 will also be changed to the new value of the effective user ID.
 
 Explicit calls to
@@ -63,16 +63,11 @@ is a security hole that can expose it to unwanted signals.
 .BR setfsuid ()
 will succeed only if the caller is the superuser or if
 .I fsuid
-matches either the real user ID, effective user ID, saved set-user-ID, or
-the current value of
-.IR 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 success, the previous value of
-.I fsuid
-is returned.
-On error, the current value of
-.I fsuid
-is returned.
+On both success and failure,
+this call returns the previous filesystem user ID of the caller.
 .SH VERSIONS
 This system call is present in Linux since version 1.2.
 .\" This system call is present since Linux 1.1.44
@@ -88,9 +83,24 @@ it will return \-1 and set \fIerrno\fP to
 without attempting
 the system call.
 .LP
-Note that at the time this system call was introduced, a process
-could send a signal to a process with the same effective user ID.
-Today signal permission handling is slightly different.
+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 privilged 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 change 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)).
 
 The original Linux
 .BR setfsuid ()
@@ -102,7 +112,16 @@ The glibc
 .BR setfsuid ()
 wrapper function transparently deals with the variation across kernel versions.
 .SH BUGS
-No error messages of any kind are returned to the caller.
+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
+.IR 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