From b7e471c2b26889d6e533b047980018c5c905cb6c Mon Sep 17 00:00:00 2001
From: Conrad Meyer <cem@FreeBSD.org>
Date: Wed, 6 Jun 2018 20:09:21 +0000
Subject: [PATCH] strcpy.3: Improve legibility and clarity

In the DESCRIPTION, put the more commonly used functions first in the
corresponding sentence, to help catch the eye.

Pull out the note about overlapping buffers to its own paragraph, as it
applies to all routines documented by this page.

Emphasize the potentially surprising strncpy(3) behavior of zero-filling the
remainder of a buffer larger than the source string.

Encourage strlcpy use; remove portability note about strlcpy(3).  Adapting a
strlcpy-using code base to a platform that does not provide strlcpy in libc
is so trivial as to not be worth mentioning.  (Just copy strlcpy.c out of
any BSD libc, or include and link the pre-packaged libbsd library on non-BSD
platforms.)

Likewise, expand the page's warning about ease of potential misuse to cover
all functions documented herein, and explicitly suggest using strlcpy most
of the time.  The text was mostly cribbed from a similar suggestion in
gets(3).

Finally, document the remaining valid use of strncpy -- the rare
fixed-length record with no expectation of nul-termination.

Sponsored by:	Dell EMC Isilon
---
 lib/libc/string/strcpy.3 | 52 +++++++++++++++++++++++-----------------
 1 file changed, 30 insertions(+), 22 deletions(-)

diff --git a/lib/libc/string/strcpy.3 b/lib/libc/string/strcpy.3
index 36ad1d33cd4c..ce586f95e5dc 100644
--- a/lib/libc/string/strcpy.3
+++ b/lib/libc/string/strcpy.3
@@ -32,7 +32,7 @@
 .\"     @(#)strcpy.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd February 28, 2009
+.Dd June 6, 2018
 .Dt STRCPY 3
 .Os
 .Sh NAME
@@ -55,9 +55,9 @@
 .Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
 .Sh DESCRIPTION
 The
-.Fn stpcpy
-and
 .Fn strcpy
+and
+.Fn stpcpy
 functions
 copy the string
 .Fa src
@@ -66,22 +66,18 @@ to
 (including the terminating
 .Ql \e0
 character.)
-If
-.Fa src
-and
-.Fa dst
-overlap, the results are undefined.
 .Pp
 The
-.Fn stpncpy
-and
 .Fn strncpy
+and
+.Fn stpncpy
 functions copy at most
 .Fa len
 characters from
 .Fa src
 into
 .Fa dst .
+.Bf Sy
 If
 .Fa src
 is less than
@@ -92,16 +88,25 @@ the remainder of
 is filled with
 .Ql \e0
 characters.
+.Ef
 Otherwise,
 .Fa dst
 is
 .Em not
 terminated.
-If
+.Pp
+For all of
+.Fn strcpy ,
+.Fn strncpy ,
+.Fn stpcpy ,
+and
+.Fn stpncpy ,
+the result is undefined
+if
 .Fa src
 and
 .Fa dst
-overlap, the results are undefined.
+overlap.
 .Sh RETURN VALUES
 The
 .Fn strcpy
@@ -182,11 +187,6 @@ This could be better achieved using
 as shown in the following example:
 .Pp
 .Dl "(void)strlcpy(buf, input, sizeof(buf));"
-.Pp
-Note that because
-.Xr strlcpy 3
-is not defined in any standards, it should
-only be used when portability is not a concern.
 .Sh SEE ALSO
 .Xr bcopy 3 ,
 .Xr memccpy 3 ,
@@ -218,8 +218,16 @@ and
 was added in
 .Fx 8.0 .
 .Sh SECURITY CONSIDERATIONS
-The
-.Fn strcpy
-function is easily misused in a manner which enables malicious users
-to arbitrarily change a running program's functionality through a
-buffer overflow attack.
+All of the functions documented in this manual page are easily misused in a
+manner which enables malicious users to arbitrarily change a running program's
+functionality through a buffer overflow attack.
+.Pp
+It is strongly suggested that the
+.Fn strlcpy
+function be used in almost all cases.
+.Pp
+For some, but not all, fixed-length records, non-terminated strings may be both
+valid and desirable.
+In that specific case, the
+.Fn strncpy
+function may be most sensible.