From patchwork Thu Apr 20 12:28:25 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 68062 X-Patchwork-Delegate: siddhesh@gotplt.org Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 33D9F3858421 for ; Thu, 20 Apr 2023 12:30:09 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 33D9F3858421 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1681993809; bh=eWsGMtI/RQms8JL+Uwauynmwe1vxDo9ywG7R3spIHMA=; h=To:Subject:In-Reply-To:References:Date:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=vSPtRFMLkjsYVZh8iWzIOxgn5kRZVMdiITfonfUhlPPXteCRdOZB5lneMLMaEXRgl zQfZYrDqCENbpjIFnrZ6O85GB1RN294pj3jSz5uCotTSsITdJkDJPxGQpTU4WXRL49 EWBmX0J+cq3qI+8UQDXk3I2AI/CAM44vsHCqaJx4= 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 ESMTPS id C9DBD385770F for ; Thu, 20 Apr 2023 12:28:28 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org C9DBD385770F Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-367-m0vEUyS4M_C1Pz2vnw1aGw-1; Thu, 20 Apr 2023 08:28:27 -0400 X-MC-Unique: m0vEUyS4M_C1Pz2vnw1aGw-1 Received: from smtp.corp.redhat.com (int-mx05.intmail.prod.int.rdu2.redhat.com [10.11.54.5]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id F3F98185A78B for ; Thu, 20 Apr 2023 12:28:26 +0000 (UTC) Received: from oldenburg.str.redhat.com (unknown [10.2.16.5]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 3FADB440BC for ; Thu, 20 Apr 2023 12:28:26 +0000 (UTC) To: libc-alpha@sourceware.org Subject: [PATCH v2 3/3] manual: Manual update for strlcat, strlcpy, wcslcat, wclscpy In-Reply-To: References: X-From-Line: f39fcf3e4b98dd53f27a2d196038c73e91148cd4 Mon Sep 17 00:00:00 2001 Message-Id: Date: Thu, 20 Apr 2023 14:28:25 +0200 User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.1 on 10.11.54.5 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com X-Spam-Status: No, score=-10.5 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_H2, SPF_HELO_NONE, SPF_NONE, 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 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: Florian Weimer via Libc-alpha From: Florian Weimer Reply-To: Florian Weimer Errors-To: libc-alpha-bounces+patchwork=sourceware.org@sourceware.org Sender: "Libc-alpha" From: Paul Eggert Co-authored-by: Florian Weimer Reviewed-by: Siddhesh Poyarekar --- 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. + +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. + +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