Re: [PATCH 1/2] Implement strlcpy and strlcat [BZ #178]

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 794 bytes --]

On 2023-04-08 15:08, Paul Eggert wrote:

> the overlapping move constraint doesn't apply to the null 
> terminator.

Oh, sorry, scratch that: it does apply, because of the 'restrict' 
constraints on the argument pointers. Hence (contrary to my previous 
assertion) PATCH 1/2's code does conform to draft POSIX.

However, it's still worrisome that PATCH 1/2's behavior disagrees with 
OpenBSD's for some nonconforming calls. If the main point of the patch 
is compatibility, surely it is better to be compatible with existing 
practice, not merely with draft POSIX.

Anyway, please ignore the documentation patch I sent yesterday in this 
thread, and look instead at the attached. This is the same patch, except 
with fixed wording under strlcpy and strlcat as to whether behavior is 
undefined.

[-- Attachment #2: 0001-manual-improve-strlcpy-strlcat-doc.patch --]
[-- Type: text/x-patch, Size: 8356 bytes --]

From 9b5eee6f05d0728c0cf026b6c5c276855fdfc637 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Sat, 8 Apr 2023 13:54:37 -0700
Subject: [PATCH 1/2 COMMENT v2] manual: improve strlcpy/strlcat doc

* NEWS: Remove duplicate announcement of strlcpy/strlcat.
* manual/maint.texi (Source Fortification):
Mention strlcpy and strlcat.
* manual/string.texi (Truncating Strings): In strlcpy/strlcat,
mention that the caller should ensure room for the terminating
null byte, as draft POSIX does.  Don't say that the behavior
is undefined merely because the size is zero, since it's well defined.
Accurately describe the constraints imposed by 'restrict',
which are stricter than the constraints imposed by not allowing
overlapping copies.
Use the same language about string-processing choice
and about performance that we already use for strncpy and strncat.
Avoid unnecessarily-different wording between strlcpy and strlcat
that might cause the reader to mistakenly think of other differences.
Mention that strlcpy is O(max(size, strlen(src))), not O(size).
---
 NEWS               |  4 +--
 manual/maint.texi  |  4 +++
 manual/string.texi | 63 ++++++++++++++++++++++++++++++----------------
 3 files changed, 47 insertions(+), 24 deletions(-)

diff --git a/NEWS b/NEWS
index 60b40fabcf..b21c4c10aa 100644
--- a/NEWS
+++ b/NEWS
@@ -22,7 +22,7 @@ Major new features:
 * PRIb* and PRIB* macros from C2X have been added to <inttypes.h>.
 
 * The strlcpy and strlcat functions have been added.  They are derived
-  from OpenBSD, and are expected to be added to a future POSIX versions.
+  from OpenBSD, and are expected to be added to a future POSIX version.
 
 Deprecated and removed features, and other changes affecting compatibility:
 
@@ -226,8 +226,6 @@ Major new features:
 
   The LoongArch ABI is 64-bit little-endian.
 
-* The functions strlcpy and strlcat have been added.
-
 Deprecated and removed features, and other changes affecting compatibility:
 
 * Support for prelink will be removed in the next release; this includes
diff --git a/manual/maint.texi b/manual/maint.texi
index a8441e20b6..3ad4647cf3 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}
diff --git a/manual/string.texi b/manual/string.texi
index 57e3f6a619..31c98dfcb3 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}.
 
@@ -1079,13 +1080,15 @@ issues.  @xref{Concatenating Strings}.
 @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 is similar to @code{strcpy}, but copies at most
-@var{size} bytes from the string @var{from} into the destination
-array @var{to}, including a terminating null byte.
+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 all of the string @var{from} to the destination
-array @var{to}, including the terminating null byte.  Like other
+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.
 
@@ -1094,13 +1097,21 @@ If @var{size} is nonzero and less than or equal to the the length of the string
 bytes to the destination array @var{to}, and writes a terminating null
 byte to the last byte of the array.
 
-The return value @var{result} of @code{strlcpy} is the length of the
-string @var{from}.  This means that @samp{@var{result} >= @var{size}} is
-true whenever truncation occurs.
+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 of @code{strlcpy} is undefined if @var{size} is zero, or if
-the source string and the first @var{size} bytes of the destination
-array overlap.
+The behavior is undefined if @var{to} or @var{from} is a null pointer,
+or if the destination array's size is both less than @var{size} and
+less than or equal to the length of the string @var{from}, or if
+the string @var{from} overlaps the result (that is, if @var{from}
+overlaps the first @samp{MIN (@var{size}, strlen (@var{from}) + 1)}
+bytes of the the destination array @var{to}).
+
+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
@@ -1109,8 +1120,9 @@ This function is derived from OpenBSD 2.4.
 @standards{BSD, string.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
 This function appends the string @var{from} to the
-string @var{to}, limiting the total size of the result string at
-@var{to} (including the null terminator) to @var{size}.
+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
@@ -1120,12 +1132,21 @@ 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 unless
-the returned value is less than @var{size}.
+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 does not contain a null byte in its first
+@var{size} bytes, or if the destination array's size is both less than
+@var{size} and less than or equal to the sum of the lengths of the
+strings @var{from} and @var{to}, or if the string @var{from} overlaps
+the total result (that is, if @var{from} overlaps the first @samp{MIN
+(@var{size}, strlen (@var{from}) + strlen (@var{to}) + 1)} bytes of
+the destination array @var{to}).
 
-The behavior is undefined if the array at @var{to} does not contain a
-null byte in its first @var{size} bytes, or if the source string and the
-first @var{size} bytes of @var{to} overlap.
+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
-- 
2.39.2