From patchwork Wed Oct 20 20:22:40 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 1544038 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.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=HftcJ03V; dkim-atps=neutral Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=sourceware.org (client-ip=8.43.85.97; helo=sourceware.org; envelope-from=libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Received: from 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 RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HZMVx28G3z9sPf for ; Thu, 21 Oct 2021 07:23:05 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id F35E93857C73 for ; Wed, 20 Oct 2021 20:23:02 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org F35E93857C73 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1634761383; bh=Blp6IegFw8//t+HXQM+pQnCu/RTVPRKQg8ZRtk3zP6k=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=HftcJ03VKUFYPOoCWw9k/3YxXSLahxRKMx8qCPyaSk6RmfAlrB3Nvt1tpb0jmQcYe lzv9prgb8H13qdIPGf9V2GNYztQdZE5Z+/w0CMwAy70JZDc73sDDcgGZS2T6rEWmJH k+nUM2cyOm/AwXrRwDXVcB218/TJ08jV+Ylvuqdg= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x433.google.com (mail-wr1-x433.google.com [IPv6:2a00:1450:4864:20::433]) by sourceware.org (Postfix) with ESMTPS id 05AB53858D39 for ; Wed, 20 Oct 2021 20:22:48 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 05AB53858D39 Received: by mail-wr1-x433.google.com with SMTP id u18so732389wrg.5 for ; Wed, 20 Oct 2021 13:22:47 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=Blp6IegFw8//t+HXQM+pQnCu/RTVPRKQg8ZRtk3zP6k=; b=gpkiZH+yziB8nKGooOI2sU/5g7pNqn34aVyIpD8tmTdkN+gQTuYbAN5Xkq5gSgp70e ZSXcHvF3OziVkKoAiIOFZEP9s6MDfXvxUDpYcaQAE9WncKYCEzgQQV8IXcAvjOY9u+mQ IBk6llL/rtS2lFDYzO62QZuFB6bvBJS+lh4uWm2+pJjEZ0EPHmbd9UOI4hvsZIamo2SS 77qXCAOrMINyptIFofmNe8EwSCwmi3CtC39KCyF1m01sM3a3omsB45loE9Kd28kF5cPO tIFSkVQxzxBQ+Iyx+1O2sGDyEfPJboir//W13fCLQQrOzJ7CxOBNAMzO+Ed+ditt77oa 8bQA== X-Gm-Message-State: AOAM532Azemt11ra9iTkZ4rAM3EoOPlmvsJvjSnrYowWtNd04v9fPH6W s9e4wgJQkLG0OyJB1H1xD70= X-Google-Smtp-Source: ABdhPJxlRENGHJqRmqeHEmIzWf2DZjQc7FbL4duV4i+VDwJpVKcLtQjTEi1RKDHjdpiK+02D2zDRKw== X-Received: by 2002:adf:a1d4:: with SMTP id v20mr1809638wrv.168.1634761366959; Wed, 20 Oct 2021 13:22:46 -0700 (PDT) Received: from sqli.sqli.com ([195.53.121.100]) by smtp.googlemail.com with ESMTPSA id n11sm2892949wrw.43.2021.10.20.13.22.45 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Oct 2021 13:22:46 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH 1/2] ctime.3: Use VLA notation for [as]ctime_r() buffer Date: Wed, 20 Oct 2021 22:22:40 +0200 Message-Id: <20211020202241.171180-1-alx.manpages@gmail.com> X-Mailer: git-send-email 2.33.0 MIME-Version: 1.0 X-Spam-Status: No, score=-11.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) 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: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Cc: Alejandro Colomar , linux-man@vger.kernel.org, Jens Gustedt , Glibc Errors-To: libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org Sender: "Libc-alpha" As N2417 (part of C2x) suggests. This syntax is very informative, and also, if used by library implementers, can improve static analysis. Since it is backwards compatible with pointer syntax, we can do this. Signed-off-by: Alejandro Colomar Cc: Jens Gustedt Cc: Glibc --- man3/ctime.3 | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/man3/ctime.3 b/man3/ctime.3 index 0e2068a09..0620741e9 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -41,10 +41,12 @@ localtime_r \- transform date and time to broken-down time or ASCII .B #include .PP .BI "char *asctime(const struct tm *" tm ); -.BI "char *asctime_r(const struct tm *restrict " tm ", char *restrict " buf ); +.BI "char *asctime_r(const struct tm *restrict " tm , +.BI " char " buf "[static restrict 26]);" .PP .BI "char *ctime(const time_t *" timep ); -.BI "char *ctime_r(const time_t *restrict " timep ", char *restrict " buf ); +.BI "char *ctime_r(const time_t *restrict " timep , +.BI " char " buf "[static restrict 26]);" .PP .BI "struct tm *gmtime(const time_t *" timep ); .BI "struct tm *gmtime_r(const time_t *restrict " timep , From patchwork Wed Oct 20 20:22:41 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alejandro Colomar X-Patchwork-Id: 1544039 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: bilbo.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=RL9M7zQY; dkim-atps=neutral Authentication-Results: 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=) 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 RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by bilbo.ozlabs.org (Postfix) with ESMTPS id 4HZMWs2z03z9sPf for ; Thu, 21 Oct 2021 07:23:53 +1100 (AEDT) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id C15CB3857C74 for ; Wed, 20 Oct 2021 20:23:50 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org C15CB3857C74 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1634761430; bh=yK5Gm+fT7CHdXo7oAn9kPEc/l84vCob4Uc/ehHZArJk=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To:Cc: From; b=RL9M7zQYu1QrYiWW5TfsXoZXtKxU9orefvn0Ly8Vqi4laFwqn+oE1TALYyrNKpY9B 4dja5s46NsJe7T3hNXE2ssciImjfeQPEftM3nmWFKf79m9K7di0mHT5atbGClOakb1 Po+9c8cKjjsm5tQIrumMpoHrSDsRuUKjeKPNHLps= X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from mail-wr1-x42d.google.com (mail-wr1-x42d.google.com [IPv6:2a00:1450:4864:20::42d]) by sourceware.org (Postfix) with ESMTPS id 8B4B33858409 for ; Wed, 20 Oct 2021 20:22:49 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 8B4B33858409 Received: by mail-wr1-x42d.google.com with SMTP id y3so49354581wrl.1 for ; Wed, 20 Oct 2021 13:22:49 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=yK5Gm+fT7CHdXo7oAn9kPEc/l84vCob4Uc/ehHZArJk=; b=IwZ9CIrrL6wPSxfq4st+zb/ih/A7/O5KD4sC6MW8tCvXxhXzZl1LKSIYmGOmYuVzen kQhr4X895L806ppRK2dQTdLnuZS5fJdrwz0ysU2Rg+sucqaN1de9saPHF7dwyX3lkE2Y s2qMxA2o84HTcwvNcnm78XStHF9eLP/ld9jYRFKut8P3K//4kXgzcCiY8uaynm989oTe rvXyeUBaKHCxSdML7yw3wK20GwismCcEZaWA0xIbkZHw0avZmInKrT9FiVNsTHTiHg1r 49Mo93haEk6ymLEvg7BWIlyX1OmuKNIzbDoDfsbX8TogDMN6CoCtNWoxPAhQs+ENGj7M o2AQ== X-Gm-Message-State: AOAM532w5CEVFaiqz8EkGlgMDNDYeZj3GkbSOp2IbujdKt5gA8yNFIwa wbCQGzFu+hvNFhFYHsAiESI= X-Google-Smtp-Source: ABdhPJwIFOc0/R3MDTIJkOmc7jPZI9TMCFtzc2HudhoUZTf7pAU1XrMJZClkzuKN/wtcF07YGj+/0g== X-Received: by 2002:a05:6000:154b:: with SMTP id 11mr1705520wry.422.1634761368653; Wed, 20 Oct 2021 13:22:48 -0700 (PDT) Received: from sqli.sqli.com ([195.53.121.100]) by smtp.googlemail.com with ESMTPSA id n11sm2892949wrw.43.2021.10.20.13.22.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 20 Oct 2021 13:22:48 -0700 (PDT) To: mtk.manpages@gmail.com Subject: [PATCH 2/2] ctime.3, strftime.3, strptime.3, timegm.3: Add [[gnu::nonnull]] to prototypes Date: Wed, 20 Oct 2021 22:22:41 +0200 Message-Id: <20211020202241.171180-2-alx.manpages@gmail.com> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20211020202241.171180-1-alx.manpages@gmail.com> References: <20211020202241.171180-1-alx.manpages@gmail.com> MIME-Version: 1.0 X-Spam-Status: No, score=-11.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, FREEMAIL_FROM, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) 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: Alejandro Colomar via Libc-alpha From: Alejandro Colomar Reply-To: Alejandro Colomar Cc: Alejandro Colomar , linux-man@vger.kernel.org, Jens Gustedt , Glibc Errors-To: libc-alpha-bounces+incoming=patchwork.ozlabs.org@sourceware.org Sender: "Libc-alpha" C2X changes the prototypes of functions that accept a pointer that cannot be NULL, to use 'static', which clearly denotes that passing NULL is Undefined Behavior. For example, 'time_t mktime(struct tm tm[static 1]);'. This change is backwards compatible, since array notation is just syntactic sugar for pointers, and the Undefined Behavior in case of a pointer already existed (in the wording); it just wasn't clear from the prototype itself. However, that forces the use of VLA (array) notation for something that is *not* an array. It is cofusing, probably too much for some programmers not so familiar with the difference between an array and a pointer, and that happens more than we would like. Even for programmers that clearly know the difference between an array and a pointer, this is at least misleading. That happens because the standard lacks a 'nonnull' attribute, and only has that (VLA) way of expressing what GCC can express with '[[gnu::nonnull]]' (a.k.a. '__attribute__((__nonnull__))'). Expressing that NULL pointers shall invoke Undefined Behavior in the prototype of a function is *way* more readable than having to read through the whole manual page text, so ideally we should also follow the standard idea of expressing that. But we can make use of more advanced techniques such as the GCC attribute, which help keep the information that those pointers are actually pointers and not arrays. From the 2 different attribute notations, let's use the "C++" one, which will be part of the standard in C2X (unlike __attribute__), and is also shorter, which helps keep the SYNOPSIS short (mostly one-liner prototypes). See Signed-off-by: Alejandro Colomar Cc: Jens Gustedt Cc: Glibc --- man3/ctime.3 | 26 +++++++++++++------------- man3/strftime.3 | 1 + man3/strptime.3 | 1 + man3/timegm.3 | 4 ++-- 4 files changed, 17 insertions(+), 15 deletions(-) diff --git a/man3/ctime.3 b/man3/ctime.3 index 0620741e9..42021a588 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -40,23 +40,23 @@ localtime_r \- transform date and time to broken-down time or ASCII .nf .B #include .PP -.BI "char *asctime(const struct tm *" tm ); -.BI "char *asctime_r(const struct tm *restrict " tm , -.BI " char " buf "[static restrict 26]);" +.BI "[[gnu::nonnull]] char *asctime(const struct tm *" tm ); +.BI "[[gnu::nonnull]] char *asctime_r(const struct tm *restrict " tm , +.BI " char " buf "[static restrict 26]);" .PP -.BI "char *ctime(const time_t *" timep ); -.BI "char *ctime_r(const time_t *restrict " timep , -.BI " char " buf "[static restrict 26]);" +.BI "[[gnu::nonnull]] char *ctime(const time_t *" timep ); +.BI "[[gnu::nonnull]] char *ctime_r(const time_t *restrict " timep , +.BI " char " buf "[static restrict 26]);" .PP -.BI "struct tm *gmtime(const time_t *" timep ); -.BI "struct tm *gmtime_r(const time_t *restrict " timep , -.BI " struct tm *restrict " result ); +.BI "[[gnu::nonnull]] struct tm *gmtime(const time_t *" timep ); +.BI "[[gnu::nonnull]] struct tm *gmtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); .PP -.BI "struct tm *localtime(const time_t *" timep ); -.BI "struct tm *localtime_r(const time_t *restrict " timep , -.BI " struct tm *restrict " result ); +.BI "[[gnu::nonnull]] struct tm *localtime(const time_t *" timep ); +.BI "[[gnu::nonnull]] struct tm *localtime_r(const time_t *restrict " timep , +.BI " struct tm *restrict " result ); .PP -.BI "time_t mktime(struct tm *" tm ); +.BI "[[gnu::nonnull]] time_t mktime(struct tm *" tm ); .fi .PP .RS -4 diff --git a/man3/strftime.3 b/man3/strftime.3 index a24ea720b..715b30edb 100644 --- a/man3/strftime.3 +++ b/man3/strftime.3 @@ -41,6 +41,7 @@ strftime \- format date and time .nf .B #include .PP +.B [[gnu::nonnull]] .BI "size_t strftime(char *restrict " s ", size_t " max , .BI " const char *restrict " format , .BI " const struct tm *restrict " tm ); diff --git a/man3/strptime.3 b/man3/strptime.3 index d6595d4bf..c1b334d87 100644 --- a/man3/strptime.3 +++ b/man3/strptime.3 @@ -36,6 +36,7 @@ strptime \- convert a string representation of time to a time tm structure .BR "#define _XOPEN_SOURCE" " /* See feature_test_macros(7) */" .B #include .PP +.B [[gnu::nonnull]] .BI "char *strptime(const char *restrict " s ", const char *restrict " format , .BI " struct tm *restrict " tm ); .fi diff --git a/man3/timegm.3 b/man3/timegm.3 index b848e83e1..18b6e4847 100644 --- a/man3/timegm.3 +++ b/man3/timegm.3 @@ -29,8 +29,8 @@ timegm, timelocal \- inverses of gmtime and localtime .nf .B #include .PP -.BI "time_t timelocal(struct tm *" tm ); -.BI "time_t timegm(struct tm *" tm ); +.BI "[[gnu::nonnull]] time_t timelocal(struct tm *" tm ); +.BI "[[gnu::nonnull]] time_t timegm(struct tm *" tm ); .PP .fi .RS -4