simplify the strlcpy/strlcat manual page substantially. do less

explaining of "what a C string is", and make it more clear that these
functiosn BEHAVE EXACTLY LIKE snprintf with "%s"!  (anyone who wants
to write a 'strlcpy considered harmful' paper should probably write a
'strlcpy and snprintf considered harmful' paper instead).

note to those from other projects reading this commit message: It would
be very good if this new manual was picked up in your project.

ok jmc millert krw

1 files changed, 58 insertions, 70 deletions

diff --git a/lib/libc/string/strlcpy.3 b/lib/libc/string/strlcpy.3
index ead54ec4388..e04284d5c3d 100644
--- a/lib/libc/string/strlcpy.3
+++ b/lib/libc/string/strlcpy.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: strlcpy.3,v 1.20 2011/07/25 00:38:53 schwarze Exp $
+.\"	$OpenBSD: strlcpy.3,v 1.21 2012/04/02 17:33:11 deraadt Exp $
 .\"
 .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 25 2011 $
+.Dd $Mdocdate: April 2 2012 $
 .Dt STRLCPY 3
 .Os
 .Sh NAME
@@ -24,72 +24,79 @@
 .Sh SYNOPSIS
 .Fd #include <string.h>
 .Ft size_t
-.Fn strlcpy "char *dst" "const char *src" "size_t size"
+.Fn strlcpy "char *dst" "const char *src" "size_t dstsize"
 .Ft size_t
-.Fn strlcat "char *dst" "const char *src" "size_t size"
+.Fn strlcat "char *dst" "const char *src" "size_t dstsize"
 .Sh DESCRIPTION
 The
 .Fn strlcpy
 and
 .Fn strlcat
-functions copy and concatenate strings respectively.
-They are designed
-to be safer, more consistent, and less error prone replacements for
+functions copy and concatenate strings with the
+same input parameters and output result as
+.Xr snprintf 3 .
+They are designed to be safer, more consistent, and less error
+prone replacements for the easily misused functions
 .Xr strncpy 3
 and
 .Xr strncat 3 .
-Unlike those functions,
-.Fn strlcpy
-and
-.Fn strlcat
-take the full size of the buffer (not just the length) and guarantee to
-NUL-terminate the result (as long as
-.Fa size
-is larger than 0 or, in the case of
-.Fn strlcat ,
-as long as there is at least one byte free in
-.Fa dst ) .
-Note that a byte for the NUL should be included in
-.Fa size .
-Also note that
+.Pp
 .Fn strlcpy
 and
 .Fn strlcat
-only operate on true
-.Dq C
-strings.
-This means that for
-.Fn strlcpy
-.Fa src
-must be NUL-terminated and for
-.Fn strlcat
-both
-.Fa src
-and
-.Fa dst
-must be NUL-terminated.
+take the full size of the destination buffer and guarantee
+NUL-termination if there is room.
+Note that room for the NUL should be included in
+.Fa dstsize .
 .Pp
-The
 .Fn strlcpy
-function copies up to
-.Fa size
-- 1 characters from the NUL-terminated string
+copies up to
+.Fa dstsize
+\- 1 characters from the string
 .Fa src
 to
 .Fa dst ,
-NUL-terminating the result.
+NUL-terminating the result if
+.Fa dstsize
+is not 0.
 .Pp
-The
 .Fn strlcat
-function appends the NUL-terminated string
+appends string
 .Fa src
 to the end of
 .Fa dst .
 It will append at most
-.Fa size
-- strlen(dst) - 1 bytes, NUL-terminating the result.
+.Fa dstsize
+\- strlen(dst) \- 1 characters.
+It will then NUL-terminate, unless
+.Fa dstsize
+is 0 or the original
+.Fa dst
+string was longer than
+.Fa dstsize
+(in practice this should not happen
+as it means that either
+.Fa dstsize
+is incorrect or that
+.Fa dst
+is not a proper string).
 .Sh RETURN VALUES
-The
+Besides quibbles over the return type
+.Pf ( Va size_t
+versus
+.Va int )
+and signal handler safety
+.Xr ( snprintf 3
+is not entirely safe on some systems), the
+following two are equivalent:
+.Bd -literal -offset indent
+n = strlcpy(dst, src, len);
+n = snprintf(dst, len, "%s", src);
+.Ed
+.Pp
+Like
+.Xr snprintf 3 ,
+the
 .Fn strlcpy
 and
 .Fn strlcat
@@ -105,29 +112,12 @@ that means the initial length of
 plus
 the length of
 .Fa src .
-While this may seem somewhat confusing, it was done to make
-truncation detection simple.
 .Pp
-Note, however, that if
-.Fn strlcat
-traverses
-.Fa size
-characters without finding a NUL, the length of the string is considered
-to be
-.Fa size
-and the destination string will not be NUL-terminated (since there was
-no space for the NUL).
-This keeps
-.Fn strlcat
-from running off the end of a string.
-In practice this should not happen (as it means that either
-.Fa size
-is incorrect or that
-.Fa dst
-is not a proper
-.Dq C
-string).
-The check exists to prevent potential security problems in incorrect code.
+If the return value is
+.Cm >=
+.Va dstsize ,
+the output string has been truncated.
+It is the caller's responsibility to handle this.
 .Sh EXAMPLES
 The following code fragment illustrates the simple case:
 .Bd -literal -offset indent
@@ -179,16 +169,14 @@ As a matter of fact, the first version of this manual page got it wrong.
 .Xr strncpy 3 ,
 .Xr wcslcpy 3
 .Sh HISTORY
-The
 .Fn strlcpy
 and
 .Fn strlcat
-functions first appeared in
+first appeared in
 .Ox 2.4 .
 .Sh AUTHORS
-The
 .Fn strlcpy
 and
 .Fn strlcat
-functions were created by
+were created by
 .An Todd C. Miller Aq Todd.Miller@courtesan.com .