[v7] Implement strlcpy, strlcat [BZ #178]
Commit Message
On 01/07/2016 02:43 AM, Florian Weimer wrote:
> I think you wanted size 0 to be undefined in the documentation?
Yes.
> If we do that, we can simplify the description.
How so? I'm attaching a diff of my latest proposal against master, to
help check that we're on the same page here.
Comments
On 01/07/2016 06:24 PM, Paul Eggert wrote:
> On 01/07/2016 02:43 AM, Florian Weimer wrote:
>> I think you wanted size 0 to be undefined in the documentation?
> Yes.
>
>> If we do that, we can simplify the description.
> How so? I'm attaching a diff of my latest proposal against master, to
> help check that we're on the same page here.
Thanks. This looks good to me. I'll post a consolidated patch tomorrow.
Florian
@@ -1,3 +1,11 @@
+2015-12-30 Paul Eggert <eggert@cs.ucla.edu>
+
+ Document strlcpy, strlcat
+ [BZ #178]
+ This patch was partly derived from text by Florian Weimer in:
+ https://sourceware.org/ml/libc-alpha/2015-12/msg00593.html
+ * manual/string.texi (Truncating Strings): New functions from BSD.
+
2015-12-29 Florian Weimer <fweimer@redhat.com>
* malloc/tst-malloc-thread-fail.c: New file.
@@ -1099,6 +1099,79 @@ processing text. Also, this function has significant performance
issues. @xref{Concatenating Strings}.
@end deftypefun
+@comment string.h
+@comment BSD
+@deftypefun size_t strlcpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
+@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.
+
+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
+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.
+
+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.
+
+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.
+
+As noted below, this function is generally a poor choice for processing
+text. Unlike @code{strncpy}, @code{strlcpy} requires @var{size} to be
+nonzero and the source string to be null-terminated, computes the
+source string's length, ensures that the destination is
+null-terminated, and does not fill the remaining part of the destination
+with null bytes.
+
+This function is derived from BSD.
+@end deftypefun
+
+@comment string.h
+@comment BSD
+@deftypefun size_t strlcat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
+@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}.
+
+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} are 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 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
+text. Also, this function has significant performance issues.
+@xref{Concatenating Strings}. Unlike @code{strncat}, @var{size}
+specifies the maximum total size of the result string (including its
+null terminator), not the number of bytes copied from the source string
+@var{from}.
+Also, unlike @code{strncat} this function requires the source and
+destination to be null-terminated, computes the source string's
+length, and keeps the destination null-terminated.
+
+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 text. When coping or
concatening multibyte strings, they can truncate within a multibyte