svn commit: r334733 - head/lib/libc/string
Conrad Meyer
cem at FreeBSD.org
Wed Jun 6 20:09:22 UTC 2018
Author: cem
Date: Wed Jun 6 20:09:21 2018
New Revision: 334733
URL: https://svnweb.freebsd.org/changeset/base/334733
Log:
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
Modified:
head/lib/libc/string/strcpy.3
Modified: head/lib/libc/string/strcpy.3
==============================================================================
--- head/lib/libc/string/strcpy.3 Wed Jun 6 20:03:35 2018 (r334732)
+++ head/lib/libc/string/strcpy.3 Wed Jun 6 20:09:21 2018 (r334733)
@@ -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.
More information about the svn-src-head
mailing list