From patchwork Fri Jan 4 16:09:24 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 1020760 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=sourceware.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=libc-alpha-return-99051-incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.b="EL+MPSgd"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 43WV9J6DPmz9s7h for ; Sat, 5 Jan 2019 03:09:40 +1100 (AEDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:subject:date:message-id:mime-version :content-type; q=dns; s=default; b=QLGC10wjLPrsDP+SniA42c6I6hfd6 oZSx14YWyMqDaC2lwbiY1rsN1G1Uiduo3n0ve9Zh8Gp+k+FYGjSCzckgjQA76/0+ Kxp5OsMWUXPaQmb9qe2KjdkEy4QIvTEjAstyuvYwCGLOrPW5qvDjNTg2auilFmXH KNGYLmabhS1wfE= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:subject:date:message-id:mime-version :content-type; s=default; bh=bxkiVCbkWlEzneUsJSqwIXvwjMA=; b=EL+ MPSgduk3ukKuWLukXnGTWslIY+5Wximb/aXRNfrMNRfzpoti/6OE+cgtoSbZQCSc tNhorqnKSmUrYstHZsNmZpDt5gTWqdiHRWXFPP/Bo6BndGeTluwIx+ZXl95p05l9 YjTUF77iR4CthuxOREB8RjMb541+dXiN7k/s5WtM= Received: (qmail 18184 invoked by alias); 4 Jan 2019 16:09:34 -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 17099 invoked by uid 89); 4 Jan 2019 16:09:34 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=catalog, trees, occurs, Terminal X-HELO: mx1.redhat.com From: Florian Weimer To: libc-alpha@sourceware.org Subject: [PATCH] manual: Use @code{errno} instead of @var{errno} [BZ #24063] Date: Fri, 04 Jan 2019 17:09:24 +0100 Message-ID: <87tvioo157.fsf@oldenburg2.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) MIME-Version: 1.0 @var is intended for placeholders (such as function parameters). Actual variables need to use @code because @var causes upper-case output, resulting in a different C identifier. 2019-01-04 Florian Weimer [BZ #24063] * manual/arith.texi (Math Error Reporting): Use @code{errno} instead of @var{errno}. (Parsing of Integers): Likewise. (Parsing of Floats): Likewise. * manual/filesys.texi (Working with Directory Trees): Likewise. (Temporary Files): Likewise. * manual/job.texi (Terminal Access Functions): Likewise. * manual/llio.texi (Synchronizing I/O): Likewise. * manual/math.texi (SVID Random): Likewise. * manual/message.texi (The catgets Functions): Likewise. (Translation with gettext): Likewise. (Locating gettext catalog): Likewise. (Charset conversion in gettext): Likewise. * manual/nss.texi (NSS Module Function Internals): Likewise. * manual/search.texi (Hash Search Function): Likewise. * manual/setjmp.texi (System V contexts): Likewise. * manual/time.texi (Sleeping): Likewise. * manual/users.texi (Lookup User): Likewise. (Lookup Group): Likewise. diff --git a/manual/arith.texi b/manual/arith.texi index 5080abf063..6ca7902b3d 100644 --- a/manual/arith.texi +++ b/manual/arith.texi @@ -875,20 +875,20 @@ complete response as @dfn{signalling} a domain error, overflow, or underflow. When a math function suffers a domain error, it raises the invalid -exception and returns NaN. It also sets @var{errno} to @code{EDOM}; +exception and returns NaN. It also sets @code{errno} to @code{EDOM}; this is for compatibility with old systems that do not support @w{IEEE 754} exception handling. Likewise, when overflow occurs, math functions raise the overflow exception and, in the default rounding mode, return @math{@infinity{}} or @math{-@infinity{}} as appropriate (in other rounding modes, the largest finite value of the appropriate sign is returned when appropriate for that rounding mode). They also -set @var{errno} to @code{ERANGE} if returning @math{@infinity{}} or -@math{-@infinity{}}; @var{errno} may or may not be set to +set @code{errno} to @code{ERANGE} if returning @math{@infinity{}} or +@math{-@infinity{}}; @code{errno} may or may not be set to @code{ERANGE} when a finite value is returned on overflow. When underflow occurs, the underflow exception is raised, and zero (appropriately signed) or a subnormal value, as appropriate for the mathematical result of the function and the rounding mode, is -returned. @var{errno} may be set to @code{ERANGE}, but this is not +returned. @code{errno} may be set to @code{ERANGE}, but this is not guaranteed; it is intended that @theglibc{} should set it when the underflow is to an appropriately signed zero, but not necessarily for other underflows. @@ -2545,7 +2545,7 @@ You should not check for errors by examining the return value of @code{0l}, @code{LONG_MAX}, or @code{LONG_MIN}. Instead, check whether @var{tailptr} points to what you expect after the number (e.g. @code{'\0'} if the string should end after the number). You also -need to clear @var{errno} before the call and check it afterward, in +need to clear @code{errno} before the call and check it afterward, in case there was overflow. There is an example at the end of this section. @@ -2574,7 +2574,7 @@ for example that @code{strtoul} on @code{"-1"} returns @code{ULONG_MAX} and an input more negative than @code{LONG_MIN} returns (@code{ULONG_MAX} + 1) / 2. -@code{strtoul} sets @var{errno} to @code{EINVAL} if @var{base} is out of +@code{strtoul} sets @code{errno} to @code{EINVAL} if @var{base} is out of range, or @code{ERANGE} on overflow. @end deftypefun @@ -2892,7 +2892,7 @@ representation of NaN (there can be several). Since zero is a valid result as well as the value returned on error, you should check for errors in the same way as for @code{strtol}, by -examining @var{errno} and @var{tailptr}. +examining @code{errno} and @var{tailptr}. @end deftypefun @deftypefun float strtof (const char *@var{string}, char **@var{tailptr}) diff --git a/manual/filesys.texi b/manual/filesys.texi index ccda36cf84..28480e7608 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -1098,7 +1098,7 @@ this option is set. This option is a GNU extension. The return value is computed in the same way as for @code{ftw}. @code{nftw} returns @math{0} if no failures occurred and all callback functions returned @math{0}. In case of internal errors, such as memory -problems, the return value is @math{-1} and @var{errno} is set +problems, the return value is @math{-1} and @code{errno} is set accordingly. If the return value of a callback invocation was non-zero then that value is returned. @@ -3524,9 +3524,9 @@ directory, and returns @var{template}. As with @code{mktemp} and @samp{XXXXXX}. If @code{mkdtemp} cannot create an uniquely named directory, it returns -@code{NULL} and sets @var{errno} appropriately. If @var{template} does +@code{NULL} and sets @code{errno} appropriately. If @var{template} does not end with @samp{XXXXXX}, @code{mkdtemp} returns @code{NULL} and does -not modify @var{template}. @var{errno} will be set to @code{EINVAL} in +not modify @var{template}. @code{errno} will be set to @code{EINVAL} in this case. The directory is created using mode @code{0700}. diff --git a/manual/job.texi b/manual/job.texi index e304313ca7..05a42ea820 100644 --- a/manual/job.texi +++ b/manual/job.texi @@ -1275,7 +1275,7 @@ process. This function is used to obtain the process group ID of the session for which the terminal specified by @var{fildes} is the controlling terminal. If the call is successful the group ID is returned. Otherwise the -return value is @code{(pid_t) -1} and the global variable @var{errno} +return value is @code{(pid_t) -1} and the global variable @code{errno} is set to the following value: @table @code @item EBADF diff --git a/manual/llio.texi b/manual/llio.texi index 2733b9cb73..46b891d194 100644 --- a/manual/llio.texi +++ b/manual/llio.texi @@ -2197,7 +2197,7 @@ protected using cancellation handlers. @c ref pthread_cleanup_push / pthread_cleanup_pop The return value of the function is zero if no error occurred. Otherwise -it is @math{-1} and the global variable @var{errno} is set to the +it is @math{-1} and the global variable @code{errno} is set to the following values: @table @code @item EBADF @@ -2230,7 +2230,7 @@ required by @code{fdatasync}. The prototype for @code{fdatasync} is in @file{unistd.h}. The return value of the function is zero if no error occurred. Otherwise -it is @math{-1} and the global variable @var{errno} is set to the +it is @math{-1} and the global variable @code{errno} is set to the following values: @table @code @item EBADF diff --git a/manual/math.texi b/manual/math.texi index d19a14b47d..4aaa106653 100644 --- a/manual/math.texi +++ b/manual/math.texi @@ -1835,7 +1835,7 @@ pointer @var{buffer}. The random number is returned in the variable pointed to by @var{result}. The return value of the function indicates whether the call succeeded. -If the value is less than @code{0} an error occurred and @var{errno} is +If the value is less than @code{0} an error occurred and @code{errno} is set to indicate the problem. This function is a GNU extension and should not be used in portable diff --git a/manual/message.texi b/manual/message.texi index 4cdff66eba..ef68693fd1 100644 --- a/manual/message.texi +++ b/manual/message.texi @@ -116,7 +116,7 @@ opaque type and can be used in calls to the other functions to refer to this loaded catalog. The return value is @code{(nl_catd) -1} in case the function failed and -no catalog was loaded. The global variable @var{errno} contains a code +no catalog was loaded. The global variable @code{errno} contains a code for the error causing the failure. But even if the function call succeeded this does not mean that all messages can be translated. @@ -242,7 +242,7 @@ translation actually happened must look like this: @end smallexample @noindent -When an error occurs the global variable @var{errno} is set to +When an error occurs the global variable @code{errno} is set to @table @var @item EBADF @@ -315,8 +315,8 @@ The @code{catclose} function can be used to free the resources associated with a message catalog which previously was opened by a call to @code{catopen}. If the resources can be successfully freed the function returns @code{0}. Otherwise it returns @code{@minus{}1} and the -global variable @var{errno} is set. Errors can occur if the catalog -descriptor @var{catalog_desc} is not valid in which case @var{errno} is +global variable @code{errno} is set. Errors can occur if the catalog +descriptor @var{catalog_desc} is not valid in which case @code{errno} is set to @code{EBADF}. @end deftypefun @@ -849,14 +849,14 @@ say more about this when we talk about the ways message catalogs are selected (@pxref{Locating gettext catalog}). The @code{gettext} function does not modify the value of the global -@var{errno} variable. This is necessary to make it possible to write +@code{errno} variable. This is necessary to make it possible to write something like @smallexample printf (gettext ("Operation failed: %m\n")); @end smallexample -Here the @var{errno} value is used in the @code{printf} function while +Here the @code{errno} value is used in the @code{printf} function while processing the @code{%m} format element and if the @code{gettext} function would change this value (it is called before @code{printf} is called) we would get a wrong message. @@ -1133,7 +1133,7 @@ only lead to problems. The function returns the value which is from now on taken as the default domain. If the system went out of memory the returned value is -@code{NULL} and the global variable @var{errno} is set to @code{ENOMEM}. +@code{NULL} and the global variable @code{errno} is set to @code{ENOMEM}. Despite the return value type being @code{char *} the return string must not be changed. It is allocated internally by the @code{textdomain} function. @@ -1190,7 +1190,7 @@ containing the name of the selected directory name. The string is allocated internally in the function and must not be changed by the user. If the system went out of core during the execution of @code{bindtextdomain} the return value is @code{NULL} and the global -variable @var{errno} is set accordingly. +variable @code{errno} is set accordingly. @end deftypefun @@ -1585,7 +1585,7 @@ string containing the name of the selected codeset. The string is allocated internally in the function and must not be changed by the user. If the system went out of core during the execution of @code{bind_textdomain_codeset}, the return value is @code{NULL} and the -global variable @var{errno} is set accordingly. +global variable @code{errno} is set accordingly. @end deftypefun diff --git a/manual/nss.texi b/manual/nss.texi index 18361b6f42..164ae33246 100644 --- a/manual/nss.texi +++ b/manual/nss.texi @@ -691,7 +691,7 @@ function. Therefore one must not misuse this buffer to save some state information from one call to another. Before the function returns with a failure code, the implementation -should store the value of the local @var{errno} variable in the variable +should store the value of the local @code{errno} variable in the variable pointed to be @var{errnop}. This is important to guarantee the module working in statically linked programs. The stored value must not be zero. @@ -725,7 +725,7 @@ The implementation of this function should honor the @var{stayopen} flag set by the @code{set@var{DB}ent} function whenever this makes sense. Before the function returns, the implementation should store the value of -the local @var{errno} variable in the variable pointed to by +the local @code{errno} variable in the variable pointed to by @var{errnop}. This is important to guarantee the module works in statically linked programs. diff --git a/manual/search.texi b/manual/search.texi index 57dad7a56d..1574c96562 100644 --- a/manual/search.texi +++ b/manual/search.texi @@ -449,7 +449,7 @@ entry in the table is not the return value of the function. It is returned by storing it in a pointer variable pointed to by the @var{retval} parameter. The return value of the function is an integer value indicating success if it is non-zero and failure if it is zero. -In the latter case the global variable @var{errno} signals the reason for +In the latter case the global variable @code{errno} signals the reason for the failure. @table @code diff --git a/manual/setjmp.texi b/manual/setjmp.texi index 3ce202d024..17bdcaec99 100644 --- a/manual/setjmp.texi +++ b/manual/setjmp.texi @@ -300,7 +300,7 @@ information about the current context's stack may be in the architecture-specific subfields of the @code{uc_mcontext} field. The function returns @code{0} if successful. Otherwise it returns -@code{-1} and sets @var{errno} accordingly. +@code{-1} and sets @code{errno} accordingly. @end deftypefun The @code{getcontext} function is similar to @code{setjmp} but it does @@ -425,7 +425,7 @@ installed and execution continues as described in this context. If @code{swapcontext} succeeds the function does not return unless the context @var{oucp} is used without prior modification by @code{makecontext}. The return value in this case is @code{0}. If the -function fails it returns @code{-1} and sets @var{errno} accordingly. +function fails it returns @code{-1} and sets @code{errno} accordingly. @end deftypefun @heading Example for SVID Context Handling diff --git a/manual/time.texi b/manual/time.texi index 4d154452eb..9e98131487 100644 --- a/manual/time.texi +++ b/manual/time.texi @@ -2864,7 +2864,7 @@ without getting interrupted by a signal, this is zero. @code{struct timespec} is described in @xref{Elapsed Time}. If the function returns because the interval is over the return value is -zero. If the function returns @math{-1} the global variable @var{errno} +zero. If the function returns @math{-1} the global variable @code{errno} is set to the following values: @table @code diff --git a/manual/users.texi b/manual/users.texi index 4ed79ba26f..96ed2065b7 100644 --- a/manual/users.texi +++ b/manual/users.texi @@ -2034,7 +2034,7 @@ If a user with ID @var{uid} is found, the pointer returned in or if an error occurred, the pointer returned in @var{result} is a null pointer. The function returns zero or an error code. If the buffer @var{buffer} is too small to contain all the needed information, the -error code @code{ERANGE} is returned and @var{errno} is set to +error code @code{ERANGE} is returned and @code{errno} is set to @code{ERANGE}. @end deftypefun @@ -2353,7 +2353,7 @@ If a group with ID @var{gid} is found, the pointer returned in or if an error occurred, the pointer returned in @var{result} is a null pointer. The function returns zero or an error code. If the buffer @var{buffer} is too small to contain all the needed information, the -error code @code{ERANGE} is returned and @var{errno} is set to +error code @code{ERANGE} is returned and @code{errno} is set to @code{ERANGE}. @end deftypefun