Re: [PATCH] Implement strlcat [BZ#178]

[Florian Weimer <fweimer at redhat dot com>]

On 11/26/2015 11:34 AM, Paul Eggert wrote:
> Florian Weimer wrote:
>> I'm attaching the consolidated documentation patch.
> 
> Thanks.  Attached are three patches fixing the problems I mentioned
> earlier, relative to the current glibc master.  The first two patches
> are independent of strlcpy+strlcat: they switch to less-confusing
> terminology (e.g., "byte" instead of "character" when talking about
> strcpy), and split the enormous "Copying Strings and Arrays" section
> into more-manageable subsections while adding advice about string
> truncation.  The third patch adds strlcpy/strlcat and relies on the
> earlier two patches.

I looked at the first patch, and have the followign comments.

+null byte always represents the null character.  A @dfn{multibyte
+character string} is a string that consists entirely of multibyte
+characters.  In contrast, a @dfn{wide character string} is a
+null-terminated sequence of @code{wchar_t} objects and as for strings
+usually pointers of type @code{wchar_t *} are used.  @xref{Extended
+Char Intro}.

I don't understand the âand as for strings usually pointers â are usedâ
part.

Standard uses âwide stringâ by the way, not âwide character stringâ.

-A null character is quite different conceptually from a null pointer,
+A null byte is quite different conceptually from a null pointer,
 although both are represented by the integer @code{0}.

Please also use âinteger constant @code{0}â.  Only the integer constant
zero represents a null pointer, an integer variable which stores the
value zero does not.

+literal.  Strings can also be formed by @dfn{string concatenation}:
+@code{"a" "b"} is the

The original had âstring literalâ.  As this only works for string
literals, it's best to keep it.

 blocks of memory, and functions that are specific to null-terminated
-arrays of characters and wide characters.
+strings and wide strings.

Should be âspecific to strings and wide character stringsâ (the
ânull-terminatedâ is redundant, and âwide stringsâ has not been defined.

Most of the remaining ânull-terminatedâ occurrences in string.texi
should be removed, for consistency and clarity.

@@ -309,7 +318,8 @@ returns @var{maxlen}.  Therefore this function is
equivalent to
 @code{(strlen (@var{s}) < @var{maxlen} ? strlen (@var{s}) : @var{maxlen})}
 but it
 is more efficient and works even if the string @var{s} is not
-null-terminated.
+null-terminated so long as @var{maxlen} does not exceed the
+size of @var{s}'s array.

This doesn't make much sense anymore because strings are defined to be
always null-terminated.

The documentation of strncpy now implies that the source must be
null-terminated, which is not correct.  Same for wcsncpy and wcsnlen.

> I still would rather not add strlcpy+strlcat, but if we're going to add
> them they will need decent documentation, and I hope this is good enough.

Understood.

> PS.  This time around I noticed that in some cases strlcat is required
> to not null-terminate its output, even when there's room for a null byte
> in the destination buffer.  Eeeuuuw.  Do we really want to document that
> particular misfeature?  Does user code really require it?

It's part of the specification, as far as I can tell.

Florian