From patchwork Fri Dec 22 19:31:00 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Aurelien Jarno X-Patchwork-Id: 25079 Received: (qmail 127937 invoked by alias); 22 Dec 2017 19:31:09 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 127491 invoked by uid 89); 22 Dec 2017 19:31:09 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-25.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, KAM_LAZY_DOMAIN_SECURITY, T_RP_MATCHES_RCVD autolearn=ham version=3.3.2 spammy= X-HELO: hall.aurel32.net From: Aurelien Jarno To: libc-alpha@sourceware.org Cc: Aurelien Jarno Subject: [PATCH v2 2/3] manual: clarify errno value on success [BZ #22615] Date: Fri, 22 Dec 2017 20:31:00 +0100 Message-Id: <20171222193101.3396-3-aurelien@aurel32.net> In-Reply-To: <20171222193101.3396-1-aurelien@aurel32.net> References: <20171222193101.3396-1-aurelien@aurel32.net> 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. --- ChangeLog | 6 ++++++ manual/errno.texi | 28 ++++++++++++++-------------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/ChangeLog b/ChangeLog index c8157a4e43..8368b3006d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2017-12-22 Zack Weinberg + + [BZ #22615] + * manual/errno.texi (Checking for Errors): Explicitly say that errno + might be set on success. + 2017-12-22 Aurelien Jarno [BZ #22611] diff --git a/manual/errno.texi b/manual/errno.texi index 3e0b862c4e..73272fd884 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