setfsgid.2: Clarify description of return value

More clearly describe the weirdness in the return value of this
system call, and ote the problems it creates in in BUGS

Reported-by: Oleg Nesterov <oleg@redhat.com>

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 13 insertions, 8 deletions

diff --git a/man2/setfsgid.2 b/man2/setfsgid.2
index caa26e7c..ea7b872a 100644
--- a/man2/setfsgid.2
+++ b/man2/setfsgid.2
@@ -28,7 +28,7 @@
 .\" 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 filesystem checks
 .SH SYNOPSIS
@@ -67,12 +67,8 @@ matches either the real group ID, effective group ID,
 saved set-group-ID, or the current value of
 .IR fsgid .
 .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
@@ -102,7 +98,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