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

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

diff --git a/original/man2/setfsgid.2 b/original/man2/setfsgid.2
index dbaae16..d1d021d 100644 (file)
--- a/original/man2/setfsgid.2
+++ b/original/man2/setfsgid.2
@@ -28,25 +28,25 @@
 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"     Added notes on capability requirements
 .\"
-.TH SETFSGID 2 2010-11-22 "Linux" "Linux Programmer's Manual"
+.TH SETFSGID 2 2013-08-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
-setfsgid \- set group identity used for file system checks
+setfsgid \- set group identity used for filesystem checks
 .SH SYNOPSIS
-.B #include <unistd.h>
-/* glibc uses <sys/fsuid.h> */
+.B #include <sys/fsuid.h>
 .sp
 .BI "int setfsgid(uid_t " fsgid );
 .SH DESCRIPTION
 The system call
 .BR setfsgid ()
-sets the group ID that the Linux kernel uses to check for all accesses
-to the file system.
+changes the value of the caller's filesystem group ID\(emthe
+group ID that the Linux kernel uses to check for all accesses
+to the filesystem.
 Normally, the value of
-.I fsgid
+the filesystem group ID
 will shadow the value of the effective group ID.
 In fact, whenever the
 effective group ID is changed,
-.I fsgid
+the filesystem group ID
 will also be changed to the new value of the effective group ID.
 
 Explicit calls to
@@ -63,16 +63,11 @@ is a security hole that can expose it to unwanted signals.
 .BR setfsgid ()
 will succeed only if the caller is the superuser or if
 .I fsgid
-matches either the real group ID, effective group ID,
-saved set-group-ID, or the current value of
-.IR 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 success, the previous value of
-.I fsgid
-is returned.
-On error, the current value of
-.I fsgid
-is returned.
+On both success and failure,
+this call returns the previous filesystem group 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
@@ -91,6 +86,13 @@ the system call.
 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.
+See
+.BR setfsuid (2)
+for a discussion of why the use of both
+.BR setfsuid (2)
+and
+.BR setfsgid ()
+is nowadays unneeded.
 
 The original Linux
 .BR setfsgid ()
@@ -102,7 +104,16 @@ The glibc
 .BR setfsgid ()
 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 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