1 files changed, 55 insertions, 14 deletions

diff --git a/src/lib/libc/string/strcat.3 b/src/lib/libc/string/strcat.3
index 5357d65754..e9e5163bd3 100644
--- a/src/lib/libc/string/strcat.3
+++ b/src/lib/libc/string/strcat.3
@@ -33,14 +33,14 @@
 .\" 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 $
+.\"     $OpenBSD: strcat.3,v 1.8 2000/04/21 15:24:19 aaron Exp $
 .\"
-.Dd June 29, 1991
+.Dd July 8, 1997
 .Dt STRCAT 3
 .Os
 .Sh NAME
-.Nm strcat
+.Nm strcat ,
+.Nm strncat
 .Nd concatenate strings
 .Sh SYNOPSIS
 .Fd #include <string.h>
@@ -53,8 +53,7 @@ The
 .Fn strcat
 and
 .Fn strncat
-functions
-append a copy of the null-terminated string
+functions append a copy of the null-terminated string
 .Fa append
 to the end of the null-terminated string
 .Fa s ,
@@ -66,29 +65,71 @@ 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
+.Dq Li 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
+.Dq Li input
+to
+.Dq Li buf
+as will fit.
+It then appends as many characters from 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 strlcat 3 ,
+.Xr strlcpy 3
 .Sh STANDARDS
 The
 .Fn strcat
 and
 .Fn strncat
-functions
-conform to
+functions conform to
 .St -ansiC .