From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from cross.elm.relay.mailchannels.net (cross.elm.relay.mailchannels.net [23.83.212.46]) by sourceware.org (Postfix) with ESMTPS id 080A83858416 for ; Tue, 6 Jun 2023 06:03:06 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 080A83858416 Authentication-Results: sourceware.org; dmarc=none (p=none dis=none) header.from=gotplt.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gotplt.org X-Sender-Id: dreamhost|x-authsender|siddhesh@gotplt.org Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id A0C4C82016D; Tue, 6 Jun 2023 06:03:05 +0000 (UTC) Received: from pdx1-sub0-mail-a283.dreamhost.com (unknown [127.0.0.6]) (Authenticated sender: dreamhost) by relay.mailchannels.net (Postfix) with ESMTPA id 3866A820104; Tue, 6 Jun 2023 06:03:05 +0000 (UTC) ARC-Seal: i=1; s=arc-2022; d=mailchannels.net; t=1686031385; a=rsa-sha256; cv=none; b=Sv5/dkpsvH1kGz8jb+FYdGLJYkdNrK5DaQ6KxwMFva8zCsG9VkUgclstfre2Prv5yXOMac 6TgCdqB3Nezcy2Z6GT7mmjP0nxpiBIWVDFfS21+S3oP5gkM+Wm5DsgBVmXkyooGwF8Hc3/ 7O5HQiynq6loZsPv6vt6EyhsxmKiNGoVl0UvktfEhKfFKjt8FxaBEonhqDkllOoOqE9toJ sq/M1YuIhZgPCC3wlJ9m5ZtYPQoQNNpmQZ6s/01is+glD9Lb7BXYSM0ZbE7O3nKJblE1wC wVbkIf6KStBNEswHCQQIvJLWA0V4JQZd7PxGFSnJFtunYmz30xiLSYG/rRURAQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=mailchannels.net; s=arc-2022; t=1686031385; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:dkim-signature; bh=w3KQh+6Loh1170ijc2zkjZXubTyFw6u2GFCzASbV8sA=; b=2zCuY2YtU3g8gfHOR9qMPJed0rZ1ybiolOnctxrkATz8VBhTjt5QYBEnZj6pVypIt3wLal cXT40DYgePraVMwCa1DNQclGpsLV0D0WOyNUygrZiA4nqDrWtYdpZ/cP6OhTfussvwaDiv i8iN5O8Eu5iiezBn7ugRTYewVRcbIBOtcfNrS2xGlEqnzT7Yo0celf2Aoh89N0n/4D87UP K2eSXUWu1vZPr5/XZoAyGRGlNviLTZPyK/nujWFTNqMevN1zuckENyzo9HLZ6W91qkASu6 sCTloQq9AdgSomvFQweBz2w/k4PUumf8Mx1aeLproFZUvjBlqwkMNY2C2K34fA== ARC-Authentication-Results: i=1; rspamd-5f966895c-kr92x; auth=pass smtp.auth=dreamhost smtp.mailfrom=siddhesh@gotplt.org X-Sender-Id: dreamhost|x-authsender|siddhesh@gotplt.org X-MC-Relay: Neutral X-MailChannels-SenderId: dreamhost|x-authsender|siddhesh@gotplt.org X-MailChannels-Auth-Id: dreamhost X-Lyrical-Grain: 465ac45d22f0cba9_1686031385483_2150401268 X-MC-Loop-Signature: 1686031385483:2958386836 X-MC-Ingress-Time: 1686031385483 Received: from pdx1-sub0-mail-a283.dreamhost.com (pop.dreamhost.com [64.90.62.162]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384) by 100.125.42.131 (trex/6.8.1); Tue, 06 Jun 2023 06:03:05 +0000 Received: from [192.168.0.182] (bras-vprn-toroon4834w-lp130-02-142-113-138-85.dsl.bell.ca [142.113.138.85]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) (Authenticated sender: siddhesh@gotplt.org) by pdx1-sub0-mail-a283.dreamhost.com (Postfix) with ESMTPSA id 4Qb0JS5hWjzB3; Mon, 5 Jun 2023 23:03:04 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gotplt.org; s=dreamhost; t=1686031385; bh=w3KQh+6Loh1170ijc2zkjZXubTyFw6u2GFCzASbV8sA=; h=Date:Subject:To:From:Content-Type:Content-Transfer-Encoding; b=jShsiEnOvtrFcrF9hlzQm1vYREwNLId11NGK5v+4jLs5bHVFSOUP2zyexl/o4chRD xnMo+Q7lON7cLnrniqyLRiNeYMEozkoqOmWaMFFE0lSXNxUlRgayW5+EWG1x3dSyDR bLSfz7WyngVzJmJ5AkOg4YTsmBRzcXX/I2ViOupoKmum3RccV68PW2PXTWkMUvGZ+v 79IBZPF2+J6YHeVLUDre+zood6np9N8ky5ero8Cxf39VuZH2xn7wOuJqf7T8E27QrW 6TTQyQTmYki/ki1BdWzh/TUcp/e0eKzsUgSPjV29DL6BNUhFhMPugr4q2rdGwvFVLO 8Ho6Ly43FAy7w== Message-ID: <7bfe308b-d558-9094-9d42-b62784fc4669@gotplt.org> Date: Tue, 6 Jun 2023 02:03:03 -0400 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.10.0 Subject: Re: [PATCH v2 3/3] manual: Manual update for strlcat, strlcpy, wcslcat, wclscpy Content-Language: en-US To: Florian Weimer , libc-alpha@sourceware.org References: From: Siddhesh Poyarekar In-Reply-To: Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 7bit X-Spam-Status: No, score=-3037.4 required=5.0 tests=BAYES_00,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,GIT_PATCH_0,NICE_REPLY_A,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H5,RCVD_IN_MSPIKE_WL,SPF_HELO_NONE,SPF_PASS,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 List-Id: On 2023-04-20 08:28, Florian Weimer via Libc-alpha wrote: > From: Paul Eggert > > Co-authored-by: Florian Weimer > --- > manual/maint.texi | 8 ++++ > manual/string.texi | 96 ++++++++++++++++++++++++++++++++++++++++++++-- > 2 files changed, 101 insertions(+), 3 deletions(-) > > diff --git a/manual/maint.texi b/manual/maint.texi > index a8441e20b6..89da704f45 100644 > --- a/manual/maint.texi > +++ b/manual/maint.texi > @@ -371,6 +371,10 @@ The following functions and macros are fortified in @theglibc{}: > > @item @code{strcpy} > > +@item @code{strlcat} > + > +@item @code{strlcpy} > + > @item @code{strncat} > > @item @code{strncpy} > @@ -411,6 +415,10 @@ The following functions and macros are fortified in @theglibc{}: > > @item @code{wcscpy} > > +@item @code{wcslcat} > + > +@item @code{wcslcpy} > + > @item @code{wcsncat} > > @item @code{wcsncpy} > diff --git a/manual/string.texi b/manual/string.texi > index ad57265274..4149d54ee7 100644 > --- a/manual/string.texi > +++ b/manual/string.texi > @@ -726,8 +726,8 @@ This function has undefined results if the strings overlap. > As noted below, this function has significant performance issues. > @end deftypefun > > -Programmers using the @code{strcat} or @code{wcscat} function (or the > -@code{strncat} or @code{wcsncat} functions defined in > +Programmers using the @code{strcat} or @code{wcscat} functions (or the > +@code{strlcat}, @code{strncat} and @code{wcsncat} functions defined in > a later section, for that matter) > can easily be recognized as lazy and reckless. In almost all situations > the lengths of the participating strings are known (it better should be > @@ -848,7 +848,8 @@ function. The example would work for wide characters the same way. > Whenever a programmer feels the need to use @code{strcat} she or he > should think twice and look through the program to see whether the code cannot > be rewritten to take advantage of already calculated results. > -The related functions @code{strncat} and @code{wcscat} > +The related functions @code{strlcat}, @code{strncat}, > +@code{wcscat} and @code{wcsncat} > are almost always unnecessary, too. > Again: it is almost always unnecessary to use functions like @code{strcat}. > > @@ -1076,6 +1077,95 @@ processing strings. Also, this function has significant performance > issues. @xref{Concatenating Strings}. > @end deftypefun > > +@deftypefun size_t strlcpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) > +@standards{BSD, string.h} > +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > +This function copies the string @var{from} to the destination array > +@var{to}, limiting the result's size (including the null terminator) > +to @var{size}. The caller should ensure that @var{size} includes room > +for the result's terminating null byte. > + > +If @var{size} is greater than the length of the string @var{from}, > +this function copies the non-null bytes of the string > +@var{from} to the destination array @var{to}, > +and terminates the copy with a null byte. Like other > +string functions such as @code{strcpy}, but unlike @code{strncpy}, any > +remaining bytes in the destination array remain unchanged. > + > +If @var{size} is nonzero and less than or equal to the the length of the string > +@var{from}, this function copies only the first @samp{@var{size} - 1} > +bytes to the destination array @var{to}, and writes a terminating null > +byte to the last byte of the array. > + > +This function returns the length of the string @var{from}. This means > +that truncation occurs if and only if the returned value is greater > +than or equal to @var{size}. > + > +The behavior is undefined if @var{to} or @var{from} is a null pointer, > +or if the destination array's size is less than @var{size}, or if the > +string @var{from} overlaps the first @var{size} bytes of the > +destination array. Shouldn't this be undefined for all kinds of overlaps between @var{to} and @var{from} and not just when the @{from} overlaps with the first @var{size} bytes of @var{to}? Also, perhaps s/destination array/@var{to}/ to make it clearer. > + > +As noted below, this function is generally a poor choice for > +processing strings. Also, this function has a performance issue, > +as its time cost is proportional to the length of @var{from} > +even when @var{size} is small. > + > +This function is derived from OpenBSD 2.4. > +@end deftypefun > + > +@deftypefun size_t wcslcpy (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) > +@standards{BSD, string.h} > +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > +This function is a variant of @code{strlcpy} for wide strings. > +The @var{size} argument counts the length of the destination buffer in > +wide characters (and not bytes). > + > +This function is derived from BSD. > +@end deftypefun > + > +@deftypefun size_t strlcat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size}) > +@standards{BSD, string.h} > +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > +This function appends the string @var{from} to the > +string @var{to}, limiting the result's total size (including the null > +terminator) to @var{size}. The caller should ensure that @var{size} > +includes room for the result's terminating null byte. > + > +This function copies as much as possible of the string @var{from} into > +the array at @var{to} of @var{size} bytes, starting at the terminating > +null byte of the original string @var{to}. In effect, this appends > +the string @var{from} to the string @var{to}. Although the resulting > +string will contain a null terminator, it can be truncated (not all > +bytes in @var{from} may be copied). > + > +This function returns the sum of the original length of @var{to} and > +the length of @var{from}. This means that truncation occurs if and > +only if the returned value is greater than or equal to @var{size}. > + > +The behavior is undefined if @var{to} or @var{from} is a null pointer, > +or if the destination array's size is less than @var{size}, or if the > +destination array does not contain a null byte in its first @var{size} > +bytes, or if the string @var{from} overlaps the first @var{size} bytes > +of the destination array. Same question about overlaps, shouldn't we specify all overlaps as undefined? > + > +As noted below, this function is generally a poor choice for > +processing strings. Also, this function has significant performance > +issues. @xref{Concatenating Strings}. > + > +This function is derived from OpenBSD 2.4. > +@end deftypefun > + > +@deftypefun size_t wcslcat (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size}) > +@standards{BSD, string.h} > +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} > +This function is a variant of @code{strlcat} for wide strings. > +The @var{size} argument counts the length of the destination buffer in > +wide characters (and not bytes). > + > +This function is derived from BSD. > +@end deftypefun > + > Because these functions can abruptly truncate strings or wide strings, > they are generally poor choices for processing them. When copying or > concatening multibyte strings, they can truncate within a multibyte