From patchwork Mon Aug 5 11:03:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 1969033 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=ZIqvDC4t; dkim-atps=neutral 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=server2.sourceware.org; envelope-from=libc-alpha-bounces~incoming=patchwork.ozlabs.org@sourceware.org; receiver=patchwork.ozlabs.org) Received: from server2.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 (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4WctqL1Gswz1yZb for ; Mon, 5 Aug 2024 21:04:14 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 0B0E93858430 for ; Mon, 5 Aug 2024 11:04:12 +0000 (GMT) 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.133.124]) by sourceware.org (Postfix) with ESMTP id C7791385840F for ; Mon, 5 Aug 2024 11:03:54 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org C7791385840F Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org C7791385840F Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1722855836; cv=none; b=djeU5aiYd9Zvg+YEWn3GlGsqcc/u6cycRxLcjsSef4XsZBt+rL/syt6Jj7/bOlxLSwsLui76RQUFrXehcQHadGORBMtzWWjaFOKOxo06ouTY5cPPaSJjK6B2YPK7HQG2JJ/Q8A4PAX/xPypswgTFcvwI7x9lZ7AFOwtAKf7QOHg= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1722855836; c=relaxed/simple; bh=7HFjw0TiHaTZjNp/aQ9/jz/N2sP46qoArD7VjbuzWE8=; h=DKIM-Signature:From:To:Subject:Message-ID:Date:MIME-Version; b=aF+elaxwFBva2jY7OlA/4VBZpO7OFDMZEfXEO/KcMg8lbpd5WEYyLd2MImNqYt0vfeazX2bi5GbyhBI0CrTRKziL/J6smSmrzzrhxsC6S7AP/tFlDDFRqiDFlcN8kEKD7Ym5k6gesw6LBNtUSAD16/NAPFZG7+SvAj0fEg9jvlU= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1722855834; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type; bh=/1hALQV/qgv+hHT6sEVcArFgCrVulb+27E26JCMiNhU=; b=ZIqvDC4t/x0V8bDHljxU53RTp4K/Vky2KiP8lGsI1uk2Z5NT4rkMUAgYwez39FxPsD/xwj ilQ/Rz5TC/8+/9SmmdLBYOGRV2XPSN5BIXBw9XouWTZ5IZ9Xi7Ee5gdJROqxjDh1RsbHSQ QeOcUzS7jsbWWyA8tV+WPwJYPWglb8A= Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-596-oDJ-MzALMTWX5B3G4ylqJw-1; Mon, 05 Aug 2024 07:03:53 -0400 X-MC-Unique: oDJ-MzALMTWX5B3G4ylqJw-1 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8C9921956088 for ; Mon, 5 Aug 2024 11:03:52 +0000 (UTC) Received: from oldenburg.str.redhat.com (unknown [10.39.192.224]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1A33419560B2 for ; Mon, 5 Aug 2024 11:03:50 +0000 (UTC) From: Florian Weimer To: libc-alpha@sourceware.org Subject: [PATCH 1/2] manual: Document generic printf error codes Message-ID: X-From-Line: ee9cf3da5de1061185fb267810b9bb8c45880a4a Mon Sep 17 00:00:00 2001 Date: Mon, 05 Aug 2024 13:03:47 +0200 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP 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.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~incoming=patchwork.ozlabs.org@sourceware.org --- manual/stdio.texi | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) base-commit: 7a630f7d3392ca391a399486ce2846f9e4b4ee63 Reviewed-by: Carlos O'Donell diff --git a/manual/stdio.texi b/manual/stdio.texi index f9529a098d..83478460f8 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -2363,6 +2363,29 @@ the easiest way to make sure you have all the right prototypes is to just include @file{stdio.h}. @pindex stdio.h +The @code{printf} family shares the error codes listed below. +Individual functions may report additional @code{errno} values if they +fail. + +@table @code +@item EOVERFLOW +The number of written bytes would have exceeded @code{INT_MAX}, and thus +could not be represented in the return type @code{int}. + +@item ENOMEM +The function could not allocate memory during processing. Long argument +lists and certain floating point conversions may require memory +allocation, as does initialization of an output stream upon first use. + +@item EILSEQ +POSIX specifies this error code should be used if a wide character is +encountered that does not have a matching valid character. @Theglibc{} +always performs transliteration, using a replacement character if +necessary, so this error condition cannot occur on output. However, +@theglibc{} uses @code{EILSEQ} to indicate that an input character +sequence (wide or multi-byte) could not be converted successfully. +@end table + @deftypefun int printf (const char *@var{template}, @dots{}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acsmem{} @aculock{} @acucorrupt{}}} From patchwork Mon Aug 5 11:03:54 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 1969034 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=M0D7HCHr; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=8.43.85.97; helo=server2.sourceware.org; envelope-from=libc-alpha-bounces~incoming=patchwork.ozlabs.org@sourceware.org; receiver=patchwork.ozlabs.org) Received: from server2.sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4WctqS5ccbz1yZb for ; Mon, 5 Aug 2024 21:04:20 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 0074C385B508 for ; Mon, 5 Aug 2024 11:04:19 +0000 (GMT) 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.133.124]) by sourceware.org (Postfix) with ESMTP id A34363858431 for ; Mon, 5 Aug 2024 11:04:01 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org A34363858431 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org A34363858431 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.133.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1722855843; cv=none; b=vl0qNHeAHgizkTiBs+yhNfatBHV93grbAA+OGznaKjEQRnrLYqRmLU0tkanog5t4Z6YgnkKBgZXLrJWcnsnInTndse2PHMKRSN8v75fCNsu7eMPX/C276gPLMpQvS5TAWYPBrMYajPsO0xXbL2lNqZQt3ojUg89Tiud+tfK2zBM= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1722855843; c=relaxed/simple; bh=74+RDEVpwJdqwM5hjRsuscJ+mLkbmV5YQX77O/7iKJg=; h=DKIM-Signature:From:To:Subject:Message-ID:Date:MIME-Version; b=moaFHaaJ7HsRqfPf9ETxpLGKP5v4pniKY9clC0oiuvyHkz0UPZoGrxNGKHpar5NtBl1F/JsQZmgzAWbcDjXU8BuENGdHu2JMlb8dR/GmuWTef9vkVDXt9fZ5QJr3FytJ7KBBk7Nxjo65v6ysylQpZmQRUNRtctSxMAjVK8v7dNo= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1722855841; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=IPncBUG8Ffyypv5Hfb0Ut2drQH1OpT8aL0vf4SMFV/w=; b=M0D7HCHrZTVV3Nqbcx1Xwh15SHwUegUjUlq5BHnk3vBOqiHRorvAYZnZPa8sDaxGn1bx/E IqCMKEfpIN3mFKoPbqBJB+gOwmowUGAMfOH+q4XvFYFp6zbH8DaKTrXIUJ/QRikzPKJPQo CDRxHOkJT3tcNl9gwhiMy9EVsib5QVM= Received: from mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-638-f5FtWWqnP5qIOd56AI32SA-1; Mon, 05 Aug 2024 07:04:00 -0400 X-MC-Unique: f5FtWWqnP5qIOd56AI32SA-1 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 41A251955D4F for ; Mon, 5 Aug 2024 11:03:59 +0000 (UTC) Received: from oldenburg.str.redhat.com (unknown [10.39.192.224]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7AA8819560AE for ; Mon, 5 Aug 2024 11:03:58 +0000 (UTC) From: Florian Weimer To: libc-alpha@sourceware.org Subject: [PATCH 2/2] manual: Document dprintf and vdprintf In-Reply-To: Message-ID: <4f718d8adcb9a37e7708c81b241c445d2dd6a855.1722855793.git.fweimer@redhat.com> References: X-From-Line: 4f718d8adcb9a37e7708c81b241c445d2dd6a855 Mon Sep 17 00:00:00 2001 Date: Mon, 05 Aug 2024 13:03:54 +0200 User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_NONE, TXREP 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.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~incoming=patchwork.ozlabs.org@sourceware.org --- manual/stdio.texi | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) Reviewed-by: Carlos O'Donell diff --git a/manual/stdio.texi b/manual/stdio.texi index 83478460f8..dd9ee58642 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -2532,6 +2532,26 @@ store the result in which case @code{-1} is returned. This was changed in order to comply with the @w{ISO C99} standard. @end deftypefun +@deftypefun dprintf (int @var{fd}, @var{template}, ...) +@standards{POSIX, stdio.h} +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +This function formats its arguments according to @var{template} and +writes the result to the file descriptor @var{fd}, using the +@code{write} function. It returns the number of bytes written, or a +negative value if there was an error. In the error case, @code{errno} +is set appropriately. The possible @code{errno} values depend on the +type of the file descriptor @var{fd}, in addition to the general +@code{printf} error codes. + +The number of calls to @code{write} is unspecified, and some @code{write} +calls may have happened even if @code{dprintf} returns with an error. + +@strong{Portability Note:} POSIX does not require that this function is +async-signal-safe, and @theglibc{} implementation is not. However, some +other systems offer this function as an async-signal-safe alternative to +@code{fprintf}. @xref{POSIX Safety Concepts}. +@end deftypefun + @node Dynamic Output @subsection Dynamically Allocating Formatted Output @@ -2745,6 +2765,13 @@ The @code{obstack_vprintf} function is the equivalent of as for @code{vprintf}. @end deftypefun +@deftypefun int vdprintf (int @var{fd}, const char *@var{template}, va_list @var{ap}) +@standards{POSIX, stdio.h} +@safety{@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}} +The @code{vdprintf} is the equivalent of @code{dprintf}, but processes +an argument list. +@end deftypefun + Here's an example showing how you might use @code{vfprintf}. This is a function that prints error messages to the stream @code{stderr}, along with a prefix indicating the name of the program