From patchwork Thu Jun 15 16:32:53 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 1795532 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=2620:52:3:1:0:246e:9693:128c; helo=sourceware.org; envelope-from=libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.a=rsa-sha256 header.s=default header.b=lCodulbE; dkim-atps=neutral Received: from sourceware.org (server2.sourceware.org [IPv6:2620:52:3:1:0:246e:9693:128c]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4QhnsS5kSdz20Wy for ; Fri, 16 Jun 2023 02:33:16 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C1AD03856604 for ; Thu, 15 Jun 2023 16:33:14 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C1AD03856604 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1686846794; bh=x0nt7KHda+/1KTAbMPF79oqcEj+g3vq9WMgasVMwMNg=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:From; b=lCodulbEr3z/KVWUDwffUr+ZUwShDbgLQfCbwzICYtDTj4rFX9vCfVZFSWUkLFJtr KBZ5u24EkD4Gmf3YSrDiP1t9aPw7AwSZjqCA7p/azTuBE80GbApxT7S2RatVYAegag wApMXkOg1npEFyxEosRputmlLGcJFqn55kK0EBPc= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTPS id EAE853857BA4 for ; Thu, 15 Jun 2023 16:32:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org EAE853857BA4 Received: from mimecast-mx02.redhat.com (mx3-rdu2.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-489--m91q08yOxSQEZ-lLikzLw-1; Thu, 15 Jun 2023 12:32:56 -0400 X-MC-Unique: -m91q08yOxSQEZ-lLikzLw-1 Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3D55B3C108D2 for ; Thu, 15 Jun 2023 16:32:56 +0000 (UTC) Received: from oldenburg.str.redhat.com (unknown [10.2.16.15]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 959AE2026D49 for ; Thu, 15 Jun 2023 16:32:55 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH] manual: Update documentation of strerror and related functions Date: Thu, 15 Jun 2023 18:32:53 +0200 Message-ID: <87ilbo7kju.fsf@oldenburg.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.4 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-10.8 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_NONE, TXREP, T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Errors-To: libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org Sender: "Libc-alpha" The current implementation of strerror is thread-safe, but this has implications for the lifetime of the return string. Describe the strerror_l function. Describe both variants of the strerror_r function. Mention the lifetime of the returned string for strerrorname_np and strerrordesc_np. Clarify that perror output depends on the current locale. --- manual/errno.texi | 123 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 97 insertions(+), 26 deletions(-) base-commit: 57cd52ecec8567dd1bd91779198710f61889cf25 diff --git a/manual/errno.texi b/manual/errno.texi index 28dd871caa..f266bddb06 100644 --- a/manual/errno.texi +++ b/manual/errno.texi @@ -1147,42 +1147,110 @@ name of the program that encountered the error. @deftypefun {char *} strerror (int @var{errnum}) @standards{ISO, string.h} -@safety{@prelim{}@mtunsafe{@mtasurace{:strerror}}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} -@c Calls strerror_r with a static buffer allocated with malloc on the -@c first use. +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} The @code{strerror} function maps the error code (@pxref{Checking for Errors}) specified by the @var{errnum} argument to a descriptive error -message string. The return value is a pointer to this string. +message string. The string is translated according to the current +locale. The return value is a pointer to this string. The value @var{errnum} normally comes from the variable @code{errno}. You should not modify the string returned by @code{strerror}. Also, if -you make subsequent calls to @code{strerror}, the string might be -overwritten. (But it's guaranteed that no library function ever calls -@code{strerror} behind your back.) +you make subsequent calls to @code{strerror} or @code{strerror_l}, or +the thread that obtained the string exits, the returned pointer will be +invalidated. + +As there is no way to restore the previous state after calling +@code{strerror}, library code should not call this function because it +may intefere with application use of @code{strerror}, invalidating the +string pointer before the application is done using it. Instead, +@code{strerror_r}, @code{snprintf} with the @samp{%m} or @samp{%#m} +specifiers, @code{strerrorname_np}, or @code{strerrordesc_np} can be +used instead. + +The @code{strerror} function preserves the value of @code{errno} and +cannot fail. The function @code{strerror} is declared in @file{string.h}. @end deftypefun +@deftypefun {char *} strerror_l (int @var{errnum}, locale_t @var{locale}) +@standards{POSIX, string.h} +@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{} @ascuintl{}}@acunsafe{@acsmem{}}} +This function is like @code{strerror}, except that the returned string +is translated according to @var{locale} (instead of the current locale +used by @code{strerror}). Note that calling @code{strerror_l} +invalidates the pointer returned by @code{strerror} and vice versa. + +The function @code{strerror_l} is defined by POSIX and is declared in +@file{string.h}. +@end deftypefun + @deftypefun {char *} strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n}) @standards{GNU, string.h} @safety{@prelim{}@mtsafe{}@asunsafe{@ascuintl{}}@acunsafe{}} +The following description is for the GNU variant of the function, +used if @code{_GNU_SOURCE} is defined. @xref{Feature Test Macros}. + The @code{strerror_r} function works like @code{strerror} but instead of -returning the error message in a statically allocated buffer shared by -all threads in the process, it returns a private copy for the -thread. This might be either some permanent global data or a message -string in the user supplied buffer starting at @var{buf} with the -length of @var{n} bytes. +returning a pointer to a string that is managed by @theglibc{}, it can +use the user supplied buffer starting at @var{buf} for storing the +string. -At most @var{n} characters are written (including the NUL byte) so it is -up to the user to select a buffer large enough. +At most @var{n} characters are written (including the NUL byte) to +@var{buf}, so it is up to the user to select a buffer large enough. +Whether returned pointer points to the @var{buf} array or not depends on +the @var{errnum} argument. If the result string is not stored in +@var{buf}, the string will does not change for the remaining execution +of the program. -This function should always be used in multi-threaded programs since -there is no way to guarantee the string returned by @code{strerror} -really belongs to the last call of the current thread. +The function @code{strerror_r} as described above is a GNU extension and +it is declared in @file{string.h}. There is a POSIX variant of this +function, described next. +@end deftypefun -The function @code{strerror_r} is a GNU extension and it is declared in -@file{string.h}. +@deftypefun int strerror_r (int @var{errnum}, char *@var{buf}, size_t @var{n}) +@standards{GNU, string.h} + +This variant of the @code{strerror_r} function is used if a standard is +selected that includes @code{strerror_r}, but @code{_GNU_SOURCE} is not +defined. This POSIX variant of thefunction always writes the error +message to the specified buffer @var{buf} of size @var{n} bytes. + +Upon success, @code{strerror_r} returns 0. Two more return values are +used to indicate failure. + +@vtable @code +@item EINVAL +The @var{errnum} argument does not correspond to a known error constant. + +@item ERANGE +The buffer size @var{n} is not large enough to store the entire error message. +@end vtable + +Even if an error is reported occurs, @code{strerror_r} still writes as +much of the error message to the output buffer as possible. After a +call to @code{strerror_r}, the value of @code{errno} is unspecified. + +If you want to use the always-copying POSIX semantics of +@code{strerror_r} in a program that is potentially compiled with +@code{_GNU_SOURCE} defined, you can use @code{snprintf} with the +@samp{%m} conversion specifier, like this: + +@smallexample +int saved_errno = errno; +errno = errnum; +int ret = snprintf (buf, n, "%m"); +errno = saved_errno; +if (strerrorname_np (errnum) == NULL) + return EINVAL; +if (ret >= n) + return ERANGE: +return 0; +@end smallexample + +This function is declared in @file{string.h} if it is declared at all. +It is a POSIX extension. @end deftypefun @deftypefun void perror (const char *@var{message}) @@ -1212,7 +1280,8 @@ The function @code{perror} is declared in @file{stdio.h}. @safety{@mtsafe{}@assafe{}@acsafe{}} This function returns the name describing the error @var{errnum} or @code{NULL} if there is no known constant with this value (e.g "EINVAL" -for @code{EINVAL}). +for @code{EINVAL}). The returned string does not change for the +remaining execution of the program. @pindex string.h This function is a GNU extension, declared in the header file @file{string.h}. @@ -1223,18 +1292,20 @@ This function is a GNU extension, declared in the header file @file{string.h}. @safety{@mtsafe{}@assafe{}@acsafe{}} This function returns the message describing the error @var{errnum} or @code{NULL} if there is no known constant with this value (e.g "Invalid -argument" for @code{EINVAL}). Different than @code{strerror} the returned -description is not translated. +argument" for @code{EINVAL}). Different than @code{strerror} the +returned description is not translated, and the returned string does not +change for the remaining execution of the program. @pindex string.h This function is a GNU extension, declared in the header file @file{string.h}. @end deftypefun @code{strerror} and @code{perror} produce the exact same message for any -given error code; the precise text varies from system to system. With -@theglibc{}, the messages are fairly short; there are no multi-line -messages or embedded newlines. Each error message begins with a capital -letter and does not include any terminating punctuation. +given error code under the same locale; the precise text varies from +system to system. With @theglibc{}, the messages are fairly short; +there are no multi-line messages or embedded newlines. Each error +message begins with a capital letter and does not include any +terminating punctuation. @cindex program name @cindex name of running program