Libc-763.11.tar.gz

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

diff --git a/string/strcat.3 b/string/strcat.3
index e6e9b512c2465163c6c8982cdf3b6ec94f1bd678..9eb86eccaf270599fe9a92fda1b1940badcfbf06 100644 (file)
--- a/string/strcat.3
+++ b/string/strcat.3
@@ -13,10 +13,6 @@
 .\" 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
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
@@ -34,22 +30,30 @@
 .\" 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.17 2009/12/01 07:28:56 brueffer Exp $
 .\"
-.Dd June 4, 1993
+.Dd December 1, 2009
 .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 *
-.Fn strcat "char *s" "const char *append"
+.Fo strcat
+.Fa "char *restrict s1"
+.Fa "const char *restrict s2"
+.Fc
 .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
@@ -57,24 +61,27 @@ and
 .Fn strncat
 functions
 append a copy of the null-terminated string
-.Fa append
+.Fa s2
 to the end of the null-terminated string
-.Fa s ,
+.Fa s1 ,
 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
-.Fa count
+.Fa n
 characters from
-.Fa append ,
+.Fa s2 ,
 and then adds a terminating
 .Ql \e0 .
+.Pp
+The source and destination strings should not overlap, as the
+behavior is undefined.
 .Sh RETURN VALUES
 The
 .Fn strcat
@@ -82,7 +89,65 @@ and
 .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 ,
@@ -90,7 +155,8 @@ return the pointer
 .Xr memmove 3 ,
 .Xr strcpy 3 ,
 .Xr strlcat 3 ,
-.Xr strlcpy 3
+.Xr strlcpy 3 ,
+.Xr wcscat 3
 .Sh STANDARDS
 The
 .Fn strcat