sysconf.3: Rework RETURN VALUE description to add more detail

Make the discussion clearer, and add a few details.
Also, fix the problem report from Pavel Tikhomirov
who noted that the man page falsely said that errno
is not changed on a successful return.

Addresses https://bugzilla.kernel.org/show_bug.cgi?id=195955

Reported-by: Pavel Tikhomirov <ptikhomirov@virtuozzo.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man3/sysconf.3 b/man3/sysconf.3
index 42aed8abb747e2a58ad16130945ec81b2f7e2e0d..fc1c936010f3cc089b26ca3b08ef9006bc0d7fa1 100644 (file)
--- a/man3/sysconf.3
+++ b/man3/sysconf.3
@@ -312,18 +312,45 @@ The number of processors configured.
 .BR "" " - " _SC_NPROCESSORS_ONLN
 The number of processors currently online (available).
 .SH RETURN VALUE
+The return value of
+.BR sysconf ()
+is one of the following:
+.IP * 3
+On error, \-1 is returned and
+.I errno
+is set to indicate the cause of the error
+(for example,
+.BR EINVAL ,
+indicating that
+.I name
+is invalid).
+.IP *
 If
 .I name
-is invalid, \-1 is returned, and
-.I errno
-is set to
-.BR EINVAL .
-Otherwise, the value returned is the value of the system resource and
+corresponds to a maximum or minimum limit, and that limit is indeterminate,
+\-1 is returned and
 .I errno
 is not changed.
-In the case of options, a positive value is returned if a queried option
-is available, and \-1 if it is not.
-In the case of limits, \-1 means that there is no definite limit.
+(To distinguish an indeterminate limit from an error, set
+.I errno
+to zero before the call, and then check whether
+.I errno
+is nonzero when \-1 is returned.)
+.IP *
+If
+.I name
+corresponds to an option,
+a positive value is returned if the option is supported,
+and \-1 is returned if the option is not supported.
+.IP *
+Otherwise,
+the current value of the option or limit is returned.
+This value will not be more restrictive than
+the corresponding value that was described to the application in
+.I <unistd.h>
+or
+.I <limits.h>
+when the application was compiled.
 .SH ERRORS
 .TP
 .B EINVAL