From 40b3f0a01beb3ace92c7cccbaef9587ed73c058b Mon Sep 17 00:00:00 2001
From: mike <mike@FreeBSD.org>
Date: Thu, 9 Aug 2001 17:10:48 +0000
Subject: [PATCH] o Various mdoc fixes. o Replace strncpy examples with less
 confusing ones from   OpenBSD.  These examples give more detail and also
 suggest   using strlcpy(3).

Reviewed by:	des, ru, sheldonh
Obtained from:	OpenBSD
MFC after:	3 days
---
 lib/libc/string/strcpy.3 | 60 +++++++++++++++++++++++++++++++++-------
 1 file changed, 50 insertions(+), 10 deletions(-)

diff --git a/lib/libc/string/strcpy.3 b/lib/libc/string/strcpy.3
index 00d7df46657a..61d04d32571b 100644
--- a/lib/libc/string/strcpy.3
+++ b/lib/libc/string/strcpy.3
@@ -36,7 +36,7 @@
 .\"     @(#)strcpy.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd August 9, 2001
 .Dt STRCPY 3
 .Os
 .Sh NAME
@@ -80,11 +80,7 @@ characters long, and
 .Em not
 terminating
 .Fa dst
-if
-.Fa src
-is more than
-.Fa len
-characters long.
+otherwise.
 .Sh RETURN VALUES
 The
 .Fn strcpy
@@ -95,20 +91,64 @@ return
 .Fa dst .
 .Sh EXAMPLES
 The following sets
-.Dq Li chararray
+.Va chararray
 to
 .Dq Li abc\e0\e0\e0 :
 .Bd -literal -offset indent
-(void)strncpy(chararray, "abc", 6).
+char chararray[6];
+
+(void)strncpy(chararray, "abc", sizeof(chararray));
 .Ed
 .Pp
 The following sets
-.Dq Li chararray
+.Va chararray
 to
 .Dq Li abcdef :
 .Bd -literal -offset indent
-(void)strncpy(chararray, "abcdefgh", 6);
+char chararray[6];
+
+(void)strncpy(chararray, "abcdefgh", sizeof(chararray));
 .Ed
+.Pp
+Note that it does
+.Em not
+.Tn NUL
+terminate
+.Va chararray
+because the length of the source string is greater than or equal
+to the length parameter.
+.Pp
+The following copies as many characters from
+.Va input
+to
+.Va buf
+as will fit and
+.Tn NUL
+terminates the result.
+Because
+.Fn strncpy
+does
+.Em not
+guarantee to
+.Tn NUL
+terminate the string itself, this must be done explicitly.
+.Bd -literal -offset indent
+char buf[1024];
+
+(void)strncpy(buf, input, sizeof(buf) - 1);
+buf[sizeof(buf) - 1] = '\e0';
+.Ed
+.Pp
+This could be better achieved using
+.Xr strlcpy 3 ,
+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 ,