From patchwork Thu Jan 7 17:24:02 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Eggert X-Patchwork-Id: 10268 Received: (qmail 117183 invoked by alias); 7 Jan 2016 17:24:11 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 117172 invoked by uid 89); 7 Jan 2016 17:24:10 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-2.7 required=5.0 tests=AWL, BAYES_00, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 spammy=2015-12-30, 20151230, coping, limiting X-HELO: zimbra.cs.ucla.edu Subject: Re: [PATCH v7] Implement strlcpy, strlcat [BZ #178] To: Florian Weimer References: <5682DD7E.6000301@redhat.com> <56839678.8040304@cs.ucla.edu> <568ADC5F.5010608@redhat.com> <568B1587.4030905@cs.ucla.edu> <568C08E1.2010604@redhat.com> <568C3ED3.1090405@cs.ucla.edu> <568C50F0.2010402@redhat.com> <568C6DB0.9030600@cs.ucla.edu> <568E4159.7020709@redhat.com> Cc: GNU C Library From: Paul Eggert Message-ID: <568E9F32.6080700@cs.ucla.edu> Date: Thu, 7 Jan 2016 09:24:02 -0800 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.4.0 MIME-Version: 1.0 In-Reply-To: <568E4159.7020709@redhat.com> 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. diff --git a/ChangeLog b/ChangeLog index 749cc78..e96d835 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2015-12-30 Paul Eggert + + 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 * malloc/tst-malloc-thread-fail.c: New file. diff --git a/manual/string.texi b/manual/string.texi index 016fd0b..3d2fff3 100644 --- a/manual/string.texi +++ b/manual/string.texi @@ -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