Libc-498.tar.gz

[apple/libc.git] / string / strcat.3

diff --git a/string/strcat.3 b/string/strcat.3
index e6e9b512c2465163c6c8982cdf3b6ec94f1bd678..2986070dcc6f6d685f237376f4c9605027763be4 100644 (file)
--- a/string/strcat.3
+++ b/string/strcat.3
@@ -34,22 +34,30 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)strcat.3   8.1 (Berkeley) 6/4/93
 .\" SUCH DAMAGE.
 .\"
 .\"     @(#)strcat.3   8.1 (Berkeley) 6/4/93

-.\" $FreeBSD: src/lib/libc/string/strcat.3,v 1.9 2001/10/01 16:09:00 ru Exp $
+.\" $FreeBSD: src/lib/libc/string/strcat.3,v 1.13 2002/09/06 11:24:06 tjr Exp $

 .\"
 .Dd June 4, 1993
 .Dt STRCAT 3
 .Os
 .Sh NAME
 .\"
 .Dd June 4, 1993
 .Dt STRCAT 3
 .Os
 .Sh NAME

-.Nm strcat
+.Nm strcat ,
+.Nm strncat

 .Nd concatenate strings
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In string.h
 .Ft char *
 .Nd concatenate strings
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
 .In string.h
 .Ft char *

-.Fn strcat "char *s" "const char *append"
+.Fo strcat
+.Fa "char *restrict s1"
+.Fa "const char *restrict s2"
+.Fc

 .Ft char *
 .Ft char *

-.Fn strncat "char *s" "const char *append" "size_t count"
+.Fo strncat
+.Fa "char *restrict s1"
+.Fa "const char *restrict s2"
+.Fa "size_t n"
+.Fc

 .Sh DESCRIPTION
 The
 .Fn strcat
 .Sh DESCRIPTION
 The
 .Fn strcat


@@ -57,22 +65,22 @@ and
 .Fn strncat
 functions
 append a copy of the null-terminated string
 .Fn strncat
 functions
 append a copy of the null-terminated string

-.Fa append
+.Fa s2

 to the end of the null-terminated string
 to the end of the null-terminated string

-.Fa s ,
+.Fa s1 ,

 then add a terminating
 .Ql \e0 .
 The string
 then add a terminating
 .Ql \e0 .
 The string

-.Fa s
+.Fa s1

 must have sufficient space to hold the result.
 .Pp
 The
 .Fn strncat
 function
 appends not more than
 must have sufficient space to hold the result.
 .Pp
 The
 .Fn strncat
 function
 appends not more than

-.Fa count
+.Fa n

 characters from
 characters from

-.Fa append ,
+.Fa s2 ,

 and then adds a terminating
 .Ql \e0 .
 .Sh RETURN VALUES
 and then adds a terminating
 .Ql \e0 .
 .Sh RETURN VALUES


@@ -82,7 +90,65 @@ and
 .Fn strncat
 functions
 return the pointer
 .Fn strncat
 functions
 return the pointer

-.Fa s .
+.Fa s1 .
+.Sh SECURITY CONSIDERATIONS
+The
+.Fn strcat
+function is easily misused in a manner
+which enables malicious users to arbitrarily change
+a running program's functionality through a buffer overflow attack.
+(See
+the FSA.)
+.Pp
+Avoid using
+.Fn strcat .
+Instead, use
+.Fn strncat
+or
+.Fn strlcat
+and ensure that no more characters are copied to the destination buffer
+than it can hold.
+.Pp
+Note that
+.Fn strncat
+can also be problematic.
+It may be a security concern for a string to be truncated at all.
+Since the truncated string will not be as long as the original,
+it may refer to a completely different resource
+and usage of the truncated resource
+could result in very incorrect behavior.
+Example:
+.Bd -literal
+void
+foo(const char *arbitrary_string)
+{
+       char onstack[8] = "";
+
+#if defined(BAD)
+       /*
+        * This first strcat is bad behavior.  Do not use strcat!
+        */
+       (void)strcat(onstack, arbitrary_string);        /* BAD! */
+#elif defined(BETTER)
+       /*
+        * The following two lines demonstrate better use of
+        * strncat().
+        */
+       (void)strncat(onstack, arbitrary_string,
+           sizeof(onstack) - strlen(onstack) - 1);
+#elif defined(BEST)
+       /*
+        * These lines are even more robust due to testing for
+        * truncation.
+        */
+       if (strlen(arbitrary_string) + 1 >
+           sizeof(onstack) - strlen(onstack))
+               err(1, "onstack would be truncated");
+       (void)strncat(onstack, arbitrary_string,
+           sizeof(onstack) - strlen(onstack) - 1);
+#endif
+}
+.Ed

 .Sh SEE ALSO
 .Xr bcopy 3 ,
 .Xr memccpy 3 ,
 .Sh SEE ALSO
 .Xr bcopy 3 ,
 .Xr memccpy 3 ,