[PATCH v5 5/5] strncat.3: Rewrite to be consistent with string_copy.7.

[Alejandro Colomar <alx.manpages@gmail.com>]

Cc: Martin Sebor <msebor@redhat.com>
Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: Douglas McIlroy <douglas.mcilroy@dartmouth.edu>
Cc: Jakub Wilk <jwilk@jwilk.net>
Cc: Serge Hallyn <serge@hallyn.com>
Cc: Iker Pedrosa <ipedrosa@redhat.com>
Cc: Andrew Pinski <pinskia@gmail.com>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man3/strncat.3 | 147 +++++++++++++++----------------------------------
 1 file changed, 45 insertions(+), 102 deletions(-)

diff --git a/man3/strncat.3 b/man3/strncat.3
index 6e4bf6d78..108a9c450 100644
--- a/man3/strncat.3
+++ b/man3/strncat.3
@@ -4,7 +4,7 @@
 .\"
 .TH strncat 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-strncat \- concatenate an unterminated string into a string
+strncat \- concatenate a null-padded character sequence into a string
 .SH LIBRARY
 Standard C library
 .RI ( libc ", " \-lc )
@@ -12,53 +12,39 @@ .SH SYNOPSIS
 .nf
 .B #include <string.h>
 .PP
-.BI "char *strncat(char " dest "[restrict strlen(." dest ") + ." n " + 1],"
-.BI "              const char " src "[restrict ." n ],
-.BI "              size_t " n );
+.BI "char *strncat(char *restrict " dst ", const char " src "[restrict ." sz ],
+.BI "               size_t " sz );
 .fi
 .SH DESCRIPTION
-.IR Note :
-This is probably not the function you want to use.
-For string concatenation with truncation, see
-.BR strlcat (3bsd).
-For copying or concatenating a string into a fixed-length buffer
-with zeroing of the rest, see
-.BR stpncpy (3).
-.PP
-.BR strncat ()
-appends at most
-.I n
-characters of
-.I src
-to the end of
+This function catenates the input character sequence
+contained in a null-padded fixed-width buffer,
+into a string at the buffer pointed to by
 .IR dst .
-It always terminates with a null character the string placed in
-.IR dest .
+The programmer is responsible for allocating a buffer large enough, that is,
+.IR "strlen(dst) + strnlen(src, sz) + 1" .
 .PP
-An implementation of
-.BR strncat ()
-might be:
+An implementation of this function might be:
 .PP
 .in +4n
 .EX
 char *
-strncat(char *dest, const char *src, size_t n)
+strncat(char *restrict dst, const char *restrict src, size_t sz)
 {
-    char    *cat;
-    size_t  len;
+    int   len;
+    char  *end;
 
-    cat = dest + strlen(dest);
-    len = strnlen(src, n);
-    memcpy(cat, src, len);
-    cat[len] = \(aq\e0\(aq;
+    len = strnlen(src, sz);
+    end = dst + strlen(dst);
+    end = mempcpy(end, src, len);
+    *end = \(aq\e0\(aq;
 
-    return dest;
+    return dst;
 }
 .EE
 .in
 .SH RETURN VALUE
 .BR strncat ()
-returns a pointer to the resulting string
+returns
 .IR dest .
 .SH ATTRIBUTES
 For an explanation of the terms used in this section, see
@@ -79,93 +65,50 @@ .SH ATTRIBUTES
 .sp 1
 .SH STANDARDS
 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
-.SH NOTES
-.SS ustr2stpe()
-You may want to write your own function similar to
-.BR strncpy (),
-with the following improvements:
-.IP \(bu 3
-Copy, instead of concatenating.
-There's no equivalent of
-.BR strncat ()
-that copies instead of concatenating.
-.IP \(bu
-Allow chaining the function,
-by returning a suitable pointer.
-Copy chaining is faster than concatenating.
-.IP \(bu
-Don't check for null characters in the middle of the unterminated string.
-If the string is terminated, this function should not be used.
-If the string is unterminated, it is unnecessary.
-.IP \(bu
-A name that tells what it does:
-Copy from an
-.IR u nterminated
-.IR str ing
-to a
-.IR st ring,
-and return a
-.IR p ointer
-to its end.
-.PP
-.in +4n
-.EX
-/* This code is in the public domain.
- *
- * char *ustr2stp(char dst[restrict .n+1],
- *                const char src[restrict .n],
- *                size_t len);
- */
-char *
-ustr2stp(char *restrict dst, const char *restrict src, size_t len)
-{
-    memcpy(dst, src, len);
-    dst[len] = \(aq\e0\(aq;
-
-    return dst + len;
-}
-.EE
-.in
 .SH CAVEATS
-This function doesn't know the size of the destination buffer,
-so it can overrun the buffer if the programmer wasn't careful enough.
-.SH BUGS
-.BR strncat (3)
-has a misleading name;
-it has no relationship with
+The name of this function is confusing.
+This function has no relation to
 .BR strncpy (3).
+.PP
+If the destination buffer is not large enough,
+the behavior is undefined.
+See
+.B _FORTIFY_SOURCE
+in
+.BR feature_test_macros (7).
+.SH BUGS
+This function can be very inefficient.
+Read about
+.UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
+Shlemiel the painter
+.UE .
 .SH EXAMPLES
-The following program creates a string
-from a concatenation of unterminated strings.
 .\" SRC BEGIN (strncpy.c)
 .EX
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
-#define nitems(arr)  (sizeof((arr)) / sizeof((arr)[0]))
-
 int
 main(void)
 {
-    char pre[4] = "pre.";
-    char *post = ".post";
-    char *src = "some_long_body.post";
-    char dest[100];
+    char    buf[BUFSIZ];
+    size_t  len;
 
-    dest[0] = \(aq\e0\(aq;
-    strncat(dest, pre, nitems(pre));
-    strncat(dest, src, strlen(src) \- strlen(post));
+    buf[0] = \(aq\e0\(aq;  // There's no 'cpy' function to this 'cat'.
+    strncat(buf, "Hello XXX", 6);
+    strncat(buf, "world", 42);
+    strncat(buf, "!", 1);
+    len = strlen(buf);
+
+    printf("[len = %zu]: ", len);
+    puts(buf);  // "Hello world!"
 
-    puts(dest);  // "pre.some_long_body"
     exit(EXIT_SUCCESS);
 }
 .EE
 .\" SRC END
 .in
 .SH SEE ALSO
-.BR memccpy (3),
-.BR memcpy (3),
-.BR mempcpy (3),
-.BR strcpy (3),
-.BR string (3)
+.BR string (3),
+.BR string_copy (3)
-- 
2.38.1