Use somewhat harsher language and better examples; demonstrate that

non-dangerous use functions is difficult.
ok guenther

1 files changed, 45 insertions, 40 deletions

diff --git a/src/lib/libc/string/strncat.3 b/src/lib/libc/string/strncat.3
index bd15ef10fa..c0a0da57c7 100644
--- a/src/lib/libc/string/strncat.3
+++ b/src/lib/libc/string/strncat.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: strncat.3,v 1.2 2013/12/19 22:00:58 jmc Exp $
+.\"     $OpenBSD: strncat.3,v 1.3 2014/04/19 11:30:40 deraadt Exp $
 .\"
 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
 .\" All rights reserved.
@@ -31,7 +31,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 19 2013 $
+.Dd $Mdocdate: April 19 2014 $
 .Dt STRNCAT 3
 .Os
 .Sh NAME
@@ -40,86 +40,91 @@
 .Sh SYNOPSIS
 .In string.h
 .Ft char *
-.Fn strncat "char *s" "const char *append" "size_t count"
+.Fn strncat "char *dst" "const char *append" "size_t count"
 .Sh DESCRIPTION
 The
 .Fn strncat
 function appends not more than
 .Fa count
-characters of the NUL-terminated string
+characters of the string
 .Fa append
-to the end of the NUL-terminated string
-.Fa s .
+to the end of the string found in the buffer
+.Fa dst .
 Space for the terminating
 .Ql \e0
 should not be included in
 .Fa count .
-The string
-.Fa s
-must have sufficient space to hold the result.
+.Pp
+Bounds checking must be performed manually with great care.
+If the buffer
+.Fa dst
+is not large enough to hold the result,
+subsequent memory will be damaged.
 .Sh RETURN VALUES
 The
 .Fn strncat
 function returns the pointer
-.Fa s .
+.Fa dst .
 .Sh EXAMPLES
-The following appends
-.Dq Li abc
-to
-.Va chararray :
-.Bd -literal -offset indent
-char *letters = "abcdefghi";
-
-(void)strncat(chararray, letters, 3);
-.Ed
-.Pp
 The following example shows how to use
 .Fn strncat
-safely in conjunction with
-.Xr strncpy 3 .
+in conjunction with
+.Xr strncpy 3 :
 .Bd -literal -offset indent
 char buf[BUFSIZ];
-char *input, *suffix;
+char *base, *suffix;
 
-(void)strncpy(buf, input, sizeof(buf) - 1);
+(void)strncpy(buf, base, sizeof(buf) - 1);
 buf[sizeof(buf) - 1] = '\e0';
 (void)strncat(buf, suffix, sizeof(buf) - 1 - strlen(buf));
 .Ed
 .Pp
 The above will copy as many characters from
-.Va input
+.Va base
 to
 .Va buf
 as will fit.
 It then appends as many characters from
 .Va suffix
-as will fit (or none
-if there is no space).
-For operations like this, the
+as will fit.
+If either
+.Va base
+or
+.Va suffix
+are too large, truncation will occur without detection.
+.Pp
+The above example shows dangerous coding patterns, including an
+inability to detect truncation.
+.Fn strncat
+and
+.Fn strncpy
+are dangerously easy to misuse.
+The
 .Xr strlcpy 3
 and
 .Xr strlcat 3
-functions are a better choice, as shown below.
+functions are safer for this kind of operation:
+.Bd -literal -offset indent
+if (strlcpy(buf, base, sizeof(buf)) >= sizeof(buf) ||
+    strlcat(buf, suffix, sizeof(buf)) >= sizeof(buf))
+        goto toolong;
+
+.Ed
+or for greatest portability,
 .Bd -literal -offset indent
-(void)strlcpy(buf, input, sizeof(buf));
-(void)strlcat(buf, suffix, sizeof(buf));
+if (snprintf(buf, sizeof(buf), "%s%s",
+    base, suffix) >= sizeof(buf))
+        goto toolong;
 .Ed
+
 .Sh SEE ALSO
-.Xr bcopy 3 ,
-.Xr memccpy 3 ,
-.Xr memcpy 3 ,
-.Xr memmove 3 ,
-.Xr strcat 3 ,
-.Xr strcpy 3 ,
 .Xr strlcpy 3 ,
 .Xr wcscat 3 ,
 .Xr wcslcpy 3
 .Sh STANDARDS
 The
-.Fn strcat
-and
 .Fn strncat
-functions conform to
+function conform to
 .St -ansiC .
 .Sh HISTORY
 The