manual: clarify errno value on success [BZ #22615]

The current glibc manual is ambiguous about the errno value on success
and suggests that it is left unchanged. Some functions might and
sometimes do change the errno value, however they never set it to 0.

This patch from Zack Weinberg clarifies this section of the manual.

Changelog:
	[BZ #22615]
	* manual/errno.texi (Checking for Errors): Explicitly say that errno
	might be set on success.

diff --git a/ChangeLog b/ChangeLog
index 02f491b6b0c8d279da9288eb63022d9f451443f7..f87bc14690a7d048bd9b2516c12622fb993ab7ea 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2017-12-29  Zack Weinberg  <zackw@panix.com>
+
+       [BZ #22615]
+       * manual/errno.texi (Checking for Errors): Explicitly say that errno
+       might be set on success.
+
 2017-12-29  Aurelien Jarno  <aurelien@aurel32.net>
 
        [BZ #22611]

diff --git a/manual/errno.texi b/manual/errno.texi
index 3e0b862c4e0e841368bcb0ceb43d3739fd0512f6..73272fd8849b48458c91386f2098d96974fe3613 100644 (file)
--- a/manual/errno.texi
+++ b/manual/errno.texi
@@ -47,20 +47,20 @@ However, a properly written signal handler saves and restores the value
 of @code{errno}, so you generally do not need to worry about this
 possibility except when writing signal handlers.
 
-The initial value of @code{errno} at program startup is zero.  Many
-library functions are guaranteed to set it to certain nonzero values
-when they encounter certain kinds of errors.  These error conditions are
-listed for each function.  These functions do not change @code{errno}
-when they succeed; thus, the value of @code{errno} after a successful
-call is not necessarily zero, and you should not use @code{errno} to
-determine @emph{whether} a call failed.  The proper way to do that is
-documented for each function.  @emph{If} the call failed, you can
-examine @code{errno}.
-
-Many library functions can set @code{errno} to a nonzero value as a
-result of calling other library functions which might fail.  You should
-assume that any library function might alter @code{errno} when the
-function returns an error.
+The initial value of @code{errno} at program startup is zero.  In many
+cases, when a library function encounters an error, it will set
+@code{errno} to a non-zero value to indicate what specific error
+condition occurred.  The documentation for each function lists the
+error conditions that are possible for that function.  Not all library
+functions use this mechanism; some return an error code directly,
+instead.
+
+@strong{Warning:} Many library functions may set @code{errno} to some
+meaningless non-zero value even if they did not encounter any errors,
+and even if they return error codes directly.  Therefore, it is
+usually incorrect to check @emph{whether} an error occurred by
+inspecting the value of @code{errno}.  The proper way to check for
+error is documented for each function.
 
 @strong{Portability Note:} @w{ISO C} specifies @code{errno} as a
 ``modifiable lvalue'' rather than as a variable, permitting it to be