1 files changed, 56 insertions, 19 deletions

diff --git a/src/lib/libc/string/strcat.3 b/src/lib/libc/string/strcat.3
index 5357d65754..5b878c3e8c 100644
--- a/src/lib/libc/string/strcat.3
+++ b/src/lib/libc/string/strcat.3
@@ -13,11 +13,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 +29,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.9 2003/06/02 20:18:38 millert 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 +49,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 +61,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 .