From patchwork Thu Oct 10 21:23:14 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: DJ Delorie X-Patchwork-Id: 1995776 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=PIIVgH84; 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 4XPjRY5B23z1xtv for ; Fri, 11 Oct 2024 08:23:37 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id EFEC2385AC1E for ; Thu, 10 Oct 2024 21:23:35 +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 3EAC9385840A for ; Thu, 10 Oct 2024 21:23:19 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 3EAC9385840A 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 3EAC9385840A 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=1728595401; cv=none; b=S3Z7IQ2gtaOVix92bJ7Hf+rTWeMGOzUGRdQgHnKILDApd29BD/Ht6uu1MCglAzYyewJvV1dUbmTR3yZvr01P80TY563k8Q9nzgBoFCfSobQPrran4h35Yed7pBZFzt7ODa74uCkZ1o96mTJuqArmWTrh3lijm1mKKE5btgiSsFw= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1728595401; c=relaxed/simple; bh=NRT7gjVSsZK9YrfmgurvQkaAGgbedMG9qO6tVkiPbJY=; h=DKIM-Signature:Date:Message-Id:From:To:Subject; b=UMFYufXScIyPW3UdYCvD9hp0lFvWWRlb9xI0uoWeFp4XYBShYFA1ZVWeGWTjIICYU7nCSieaGrhJ9LFTHUGM2un0cbHzHpId4Tm+nPbVWumRXNxTMgaXn73In4KCIhGu/hmheVhSFh+qaVYcRcOZEv+f+PL74KL1SyH8YTy12WU= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1728595398; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:content-type:content-type; bh=8nroIzANt1ajQzW80nxLUMpY4f03TVAuOii9bXonP00=; b=PIIVgH84yTQb5dYZt/VMNZFiVAuZEMb+OrSBy3WD1m9QmyDhnLOZlT+9IUtlzCTdkIwezZ pO8yJOo8assqqZxKBJc0VNchPhYlbLkYu5bokV2NnxnnEbH1Kl+kU0Qsbi87GZBpJ6lNgF oVkUv+W6rdi0wqybA/HSjyI4yUQTphA= Received: from mx-prod-mc-03.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-451-tUBJxR14Pnuz6OI92xWB5w-1; Thu, 10 Oct 2024 17:23:17 -0400 X-MC-Unique: tUBJxR14Pnuz6OI92xWB5w-1 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 9CDCE19560AA for ; Thu, 10 Oct 2024 21:23:16 +0000 (UTC) Received: from greed.delorie.com (unknown [10.22.8.53]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 4BDE6300019E for ; Thu, 10 Oct 2024 21:23:16 +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 49ALNE8d4135569 for ; Thu, 10 Oct 2024 17:23:14 -0400 Date: Thu, 10 Oct 2024 17:23:14 -0400 Message-Id: From: DJ Delorie To: libc-alpha@sourceware.org Subject: [patch v1] manual: Document stdio.h functions that may be macros X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 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. The entry for putc looked like it was copied from getc and only mentioned one of the two arguments; update it. diff --git a/manual/stdio.texi b/manual/stdio.texi index c7a2b4a9a1..fb27dfc6e9 100644 --- a/manual/stdio.texi +++ b/manual/stdio.texi @@ -911,9 +911,10 @@ This function is a GNU extension. @deftypefun int putc (int @var{c}, FILE *@var{stream}) @standards{ISO, stdio.h} @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{} @aculock{}}} -This is just like @code{fputc}, except that it may be implemented as -a macro and may evaluate the @var{stream} argument more than once. -Therefore, @var{stream} should never be an expression with side-effects. +This is just like @code{fputc}, except that it may be implemented as a +macro and may evaluate its arguments more than once. Therefore, +@var{c} and @var{stream} should never be expressions with +side-effects. @end deftypefun @deftypefun wint_t putwc (wchar_t @var{wc}, FILE *@var{stream}) @@ -929,6 +930,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 +its arguments more than once. Therefore, @var{c} and @var{stream} +should never be expressions with side-effects. @end deftypefun @deftypefun wint_t putwc_unlocked (wchar_t @var{wc}, FILE *@var{stream}) @@ -1132,6 +1136,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 never be an expression with side-effects. @end deftypefun @deftypefun wint_t getwc_unlocked (FILE *@var{stream}) @@ -1571,6 +1578,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 its +arguments more than once. Therefore, these arguments should never be +expressions 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 +1599,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 its +arguments more than once. Therefore, these arguments should never be +expressions with side-effects. @end deftypefun @node Formatted Output