1 files changed, 68 insertions, 21 deletions

diff --git a/src/lib/libc/string/strcat.3 b/src/lib/libc/string/strcat.3
index 5357d65754..81aae19a63 100644
--- a/src/lib/libc/string/strcat.3
+++ b/src/lib/libc/string/strcat.3
@@ -1,3 +1,5 @@
+.\"     $OpenBSD: strcat.3,v 1.13 2011/07/25 00:38:52 schwarze Exp $
+.\"
 .\" Copyright (c) 1990, 1991 The Regents of the University of California.
 .\" All rights reserved.
 .\"
@@ -13,11 +15,7 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"     This product includes software developed by the University of
-.\"     California, Berkeley and its contributors.
-.\" 4. Neither the name of the University nor the names of its contributors
+.\" 3. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
 .\"
@@ -33,14 +31,12 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     from: @(#)strcat.3      5.6 (Berkeley) 6/29/91
-.\"     $Id: strcat.3,v 1.1.1.1 1995/10/18 08:42:22 deraadt Exp $
-.\"
-.Dd June 29, 1991
+.Dd $Mdocdate: July 25 2011 $
 .Dt STRCAT 3
 .Os
 .Sh NAME
-.Nm strcat
+.Nm strcat ,
+.Nm strncat
 .Nd concatenate strings
 .Sh SYNOPSIS
 .Fd #include <string.h>
@@ -53,10 +49,9 @@ The
 .Fn strcat
 and
 .Fn strncat
-functions
-append a copy of the null-terminated string
+functions append a copy of the NUL-terminated string
 .Fa append
-to the end of the null-terminated string
+to the end of the NUL-terminated string
 .Fa s ,
 then add a terminating
 .Ql \e0 .
@@ -66,29 +61,81 @@ must have sufficient space to hold the result.
 .Pp
 The
 .Fn strncat
-function
-appends not more than
+function appends not more than
 .Fa count
-characters.
+characters where space for the terminating
+.Ql \e0
+should not be included in
+.Fa count .
 .Sh RETURN VALUES
 The
 .Fn strcat
 and
 .Fn strncat
-functions
-return the pointer
+functions return the pointer
 .Fa s .
+.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 .
+.Bd -literal -offset indent
+char buf[BUFSIZ];
+char *input, *suffix;
+
+(void)strncpy(buf, input, 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
+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
+.Xr strlcpy 3
+and
+.Xr strlcat 3
+functions are a better choice, as shown below.
+.Bd -literal -offset indent
+(void)strlcpy(buf, input, sizeof(buf));
+(void)strlcat(buf, suffix, sizeof(buf));
+.Ed
 .Sh SEE ALSO
 .Xr bcopy 3 ,
 .Xr memccpy 3 ,
 .Xr memcpy 3 ,
 .Xr memmove 3 ,
-.Xr strcpy 3
+.Xr strcpy 3 ,
+.Xr strlcpy 3 ,
+.Xr wcscat 3 ,
+.Xr wcslcpy 3
 .Sh STANDARDS
 The
 .Fn strcat
 and
 .Fn strncat
-functions
-conform to
+functions conform to
 .St -ansiC .
+.Sh HISTORY
+The
+.Fn strcat
+and
+.Fn strncat
+functions first appeared in
+.At v7 .