From patchwork Fri Oct 11 19:12:36 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 1996275 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=eJEfQ1i1; 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 4XQGVR0QLjz1xt1 for ; Sat, 12 Oct 2024 06:13:02 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id D10E9385734D for ; Fri, 11 Oct 2024 19:13:00 +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.129.124]) by sourceware.org (Postfix) with ESMTP id 828F93858D26 for ; Fri, 11 Oct 2024 19:12:44 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 828F93858D26 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 828F93858D26 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1728673966; cv=none; b=AeCa3VL89QA3L9z8xAltYNbj7xPO+l+Psm/EXDLLGJ3zsy1s7JFV9WTf+LCPzS6ZxzWoKiv2doSta07lJ8cJ4jiOrz9E2nF4PCiHVNpCWkM1VbjmvUluAB0ArnzGi6jgbHtC8GfDFmNjV1tcWGeCO32f7v4vywXxL+5JhWsE/CU= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1728673966; c=relaxed/simple; bh=dlocSuEaP3qlJNX7lckFNkZV2lkhScIFGKSupRRW2bY=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=Ctj/6TdjxkbvyWaOEUTBXk9hg7sEp/lJpooBo8UM6xF6LAv06xWvd0MwDvCtWNQO49XvfLLooa2KgGFHhGAILgYFds42rpjscimjKqqSSZ8DlcQqsSrttv/fSdpZrglBec2pEgMFTmXCO/Zha5ZP2Vhl7O+GNHleiUo/7ruJM0c= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1728673964; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to; bh=4SFkEr1iFvcgRQokZQ02GdDaUi6oKQ2kwoBMuX5bT0o=; b=eJEfQ1i1xYVGcvl41yrCvU8tHqLDVMkb+kxmcS1lleOK20gdhiZmHu/FcXPn/pFOnMNz4w mTPg8UQMpDlyA/qUpF+LUPom7YR1xSnZ/cJnuRakSQ7qLzB9Pbat92hRX3vmzssSClA+Tb ci9mq4700LTrccvH68flPa6Jkrftr38= Received: from mx-prod-mc-01.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-473-QDD4inAiOv2liBqDFVakew-1; Fri, 11 Oct 2024 15:12:41 -0400 X-MC-Unique: QDD4inAiOv2liBqDFVakew-1 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (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-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1608A1955D4F; Fri, 11 Oct 2024 19:12:40 +0000 (UTC) Received: from greed.delorie.com (unknown [10.22.8.53]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id A48C119560AA; Fri, 11 Oct 2024 19:12:39 +0000 (UTC) Received: from greed.delorie.com.redhat.com (localhost [127.0.0.1]) by greed.delorie.com (8.16.1/8.16.1) with ESMTP id 49BJCafe4191032; Fri, 11 Oct 2024 15:12:37 -0400 From: DJ Delorie To: Florian Weimer Cc: libc-alpha@sourceware.org Subject: [patch v2] manual: Document stdio.h functions that may be macros In-Reply-To: <87msjbchig.fsf@mid.deneb.enyo.de> (message from Florian Weimer on Fri, 11 Oct 2024 07:53:27 +0200) Date: Fri, 11 Oct 2024 15:12:36 -0400 Message-ID: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.40 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-10.6 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_H3, 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 Glibc has two gnu-extension functions that are implemented as macros but not documented as such: fread_unlocked and fwrite_unlocked. Document them as such. Additionally, putc_unlocked and getc_unlocked are documented in POSIX as possibly being macros. Update the manual to add a warning about those also, depite glibc not implementing them as macros. Reviewed-by: Carlos O'Donell diff --git a/manual/stdio.texi b/manual/stdio.texi index 75aee8ab08..83f4f92e3f 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -929,6 +929,9 @@ Therefore, @var{stream} should never be an expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{putc_unlocked} function is equivalent to the @code{putc} function except that it does not implicitly lock the stream. +Like @code{putc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) @@ -1132,6 +1135,9 @@ Therefore, @var{stream} should never be an expression with side-effects. @safety{@prelim{}@mtsafe{@mtsrace{:stream}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} The @code{getc_unlocked} function is equivalent to the @code{getc} function except that it does not implicitly lock the stream. +Like @code{getc}, it may be implemented as a macro and may evaluate +the @var{stream} argument more than once. Therefore, @var{stream} +should not be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) @@ -1571,6 +1577,9 @@ The @code{fread_unlocked} function is equivalent to the @code{fread} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @deftypefun size_t fwrite (const void *@var{data}, size_t @var{size}, size_t @var{count}, FILE *@var{stream}) @@ -1589,6 +1598,9 @@ The @code{fwrite_unlocked} function is equivalent to the @code{fwrite} function except that it does not implicitly lock the stream. This function is a GNU extension. +This function may be implemented as a macro and may evaluate +@var{stream} more than once. Therefore, @var{stream} should not be an +expression with side-effects. @end deftypefun @node Formatted Output