aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAurelien Jarno <aurelien@aurel32.net>2017-12-29 14:44:57 +0100
committerAurelien Jarno <aurelien@aurel32.net>2017-12-29 14:44:57 +0100
commit54e4efc2876b329ba80a6965a2583a906d99e694 (patch)
tree3a08ae64156c80cf1cca5d397245a25bb93226ac
parentf8aa69be445f65bb36cb3ae9291423600da7d6d2 (diff)
downloadglibc-54e4efc2876b329ba80a6965a2583a906d99e694.zip
glibc-54e4efc2876b329ba80a6965a2583a906d99e694.tar.gz
glibc-54e4efc2876b329ba80a6965a2583a906d99e694.tar.bz2
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.
-rw-r--r--ChangeLog6
-rw-r--r--manual/errno.texi28
2 files changed, 20 insertions, 14 deletions
diff --git a/ChangeLog b/ChangeLog
index 02f491b..f87bc14 100644
--- 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 3e0b862..73272fd 100644
--- 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