strcpy.3, strncpy.3: Split the page and document them separately

strncpy(3) is completely unrelated to strcpy(3).  Rewrite its
documentation to be more explicit about this.

Signed-off-by: Alejandro Colomar <alx@kernel.org>

2 files changed, 122 insertions, 118 deletions

diff --git a/man3/strcpy.3 b/man3/strcpy.3
index 1b41e08a2..74c3180ae 100644
--- a/man3/strcpy.3
+++ b/man3/strcpy.3
@@ -14,7 +14,7 @@
 .\"
 .TH strcpy 3 (date) "Linux man-pages (unreleased)"
 .SH NAME
-strcpy, strncpy \- copy a string
+strcpy \- copy a string
 .SH LIBRARY
 Standard C library
 .RI ( libc ", " \-lc )
@@ -23,9 +23,6 @@ Standard C library
 .B #include <string.h>
 .PP
 .BI "char *strcpy(char *restrict " dest ", const char *restrict " src );
-.BI "char *strncpy(char " dest "[restrict ." n "], \
-const char " src "[restrict ." n ],
-.BI "              size_t " n );
 .fi
 .SH DESCRIPTION
 The
@@ -40,61 +37,10 @@ The strings may not overlap, and the destination string
 must be large enough to receive the copy.
 .I Beware of buffer overruns!
 (See BUGS.)
-.PP
-The
-.BR strncpy ()
-function is similar, except that at most
-.I n
-bytes of
-.I src
-are copied.
-.BR Warning :
-If there is no null byte
-among the first
-.I n
-bytes of
-.IR src ,
-the string placed in
-.I dest
-will not be null-terminated.
-.PP
-If the length of
-.I src
-is less than
-.IR n ,
-.BR strncpy ()
-writes additional null bytes to
-.I dest
-to ensure that a total of
-.I n
-bytes are written.
-.PP
-A simple implementation of
-.BR strncpy ()
-might be:
-.PP
-.in +4n
-.EX
-char *
-strncpy(char *dest, const char *src, size_t n)
-{
-    size_t i;
-
-    for (i = 0; i < n && src[i] != \(aq\e0\(aq; i++)
-        dest[i] = src[i];
-    for ( ; i < n; i++)
-        dest[i] = \(aq\e0\(aq;
-
-    return dest;
-}
-.EE
-.in
 .SH RETURN VALUE
 The
 .BR strcpy ()
-and
-.BR strncpy ()
-functions return a pointer to
+function returns a pointer to
 the destination string
 .IR dest .
 .SH ATTRIBUTES
@@ -108,8 +54,7 @@ lbx lb lb
 l l l.
 Interface	Attribute	Value
 T{
-.BR strcpy (),
-.BR strncpy ()
+.BR strcpy ()
 T}	Thread safety	MT-Safe
 .TE
 .hy
@@ -118,57 +63,6 @@ T}	Thread safety	MT-Safe
 .SH STANDARDS
 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
 .SH NOTES
-Some programmers consider
-.BR strncpy ()
-to be inefficient and error prone.
-If the programmer knows (i.e., includes code to test!)
-that the size of
-.I dest
-is greater than
-the length of
-.IR src ,
-then
-.BR strcpy ()
-can be used.
-.PP
-One valid (and intended) use of
-.BR strncpy ()
-is to copy a C string to a fixed-length buffer
-while ensuring both that the buffer is not overflowed
-and that unused bytes in the destination buffer are zeroed out
-(perhaps to prevent information leaks if the buffer is to be
-written to media or transmitted to another process via an
-interprocess communication technique).
-.PP
-If there is no terminating null byte in the first
-.I n
-bytes of
-.IR src ,
-.BR strncpy ()
-produces an unterminated string in
-.IR dest .
-If
-.I buf
-has length
-.IR buflen ,
-you can force termination using something like the following:
-.PP
-.in +4n
-.EX
-if (buflen > 0) {
-    strncpy(buf, str, buflen \- 1);
-    buf[buflen \- 1]= \(aq\e0\(aq;
-}
-.EE
-.in
-.PP
-(Of course, the above technique ignores the fact that, if
-.I src
-contains more than
-.I "buflen\ \-\ 1"
-bytes, information is lost in the copying to
-.IR dest .)
-.\"
 .SS strlcpy()
 Some systems (the BSDs, Solaris, and others) provide the following function:
 .PP
@@ -182,17 +76,15 @@ size_t strlcpy(char *dest, const char *src, size_t size);
 .\"     "strlcpy and strlcat - consistent, safe, string copy and concatenation"
 .\"     1999 USENIX Annual Technical Conference
 This function is similar to
-.BR strncpy (),
+.BR strcpy (),
 but it copies at most
 .I size\-1
 bytes to
 .IR dest ,
-always adds a terminating null byte,
-and does not pad the destination with (further) null bytes.
+truncating the string as necessary.
+It always adds a terminating null byte.
 This function fixes some of the problems of
 .BR strcpy ()
-and
-.BR strncpy (),
 but the caller must still handle the possibility of data loss if
 .I size
 is too small.
@@ -229,8 +121,6 @@ in ways that may make the impossible possible.
 .BR memcpy (3),
 .BR memmove (3),
 .BR stpcpy (3),
-.BR stpncpy (3),
 .BR strdup (3),
 .BR string (3),
-.BR wcscpy (3),
-.BR wcsncpy (3)
+.BR wcscpy (3)
diff --git a/man3/strncpy.3 b/man3/strncpy.3
index ff7476a84..5c1340030 100644
--- a/man3/strncpy.3
+++ b/man3/strncpy.3
@@ -1 +1,115 @@
-.so man3/strcpy.3
+.\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" References consulted:
+.\"     Linux libc source code
+.\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
+.\"     386BSD man pages
+.\" Modified Sat Jul 24 18:06:49 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified Fri Aug 25 23:17:51 1995 by Andries Brouwer (aeb@cwi.nl)
+.\" Modified Wed Dec 18 00:47:18 1996 by Andries Brouwer (aeb@cwi.nl)
+.\" 2007-06-15, Marc Boyer <marc.boyer@enseeiht.fr> + mtk
+.\"     Improve discussion of strncpy().
+.\"
+.TH strcpy 3 (date) "Linux man-pages (unreleased)"
+.SH NAME
+strncpy \- copy a string
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <string.h>
+.PP
+.BI "char *strncpy(char " dest "[restrict ." n "], \
+const char " src "[restrict ." n ],
+.BI "              size_t " n );
+.fi
+.SH DESCRIPTION
+.BI Note: " This is probably not the function you want to use."
+For safe string copying, see
+.BR strlcpy (3bsd).
+.PP
+The
+.BR strncpy ()
+copies at most
+.I n
+bytes of
+.IR src ,
+and fills the rest of the
+.I dest
+buffer with null bytes.
+.BR Warning :
+If there is no null byte
+among the first
+.I n
+bytes of
+.IR src ,
+the string placed in
+.I dest
+will not be null-terminated.
+.PP
+A simple implementation of
+.BR strncpy ()
+might be:
+.PP
+.in +4n
+.EX
+char *
+strncpy(char *dest, const char *src, size_t n)
+{
+    bzero(dest, n);
+    memccpy(dest, src, '\e0', n);
+
+    return dest;
+}
+.EE
+.in
+.SH RETURN VALUE
+The
+.BR strncpy ()
+function returns a pointer to
+the destination buffer
+.IR dest .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.ad l
+.nh
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR strncpy ()
+T}	Thread safety	MT-Safe
+.TE
+.hy
+.ad
+.sp 1
+.SH STANDARDS
+POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
+.SH NOTES
+The only valid (and intended) use of
+.BR strncpy ()
+is to copy a C string to a fixed-length buffer
+while ensuring that unused bytes in the destination buffer are zeroed out
+(perhaps to prevent information leaks if the buffer is to be
+written to media or transmitted to another process via an
+interprocess communication technique).
+.SH CAVEATS
+.BR strncpy ()
+has a misleading name.
+It doesn't produce a (null-terminated) string;
+and it should never be used for producing a string.
+.SH SEE ALSO
+.BR bzero (3),
+.BR memccpy (3),
+.BR memcpy (3),
+.BR memmove (3),
+.BR memset (3),
+.BR stpncpy (3),
+.BR string (3),
+.BR wcsncpy (3)