git.saurik.com Git - apple/libc.git/blame

Commit	Line	Data
5b2abdfb	1	.\" Copyright (c) 1990, 1991, 1993
e9ce8d39 A	2	.\" The Regents of the University of California. All rights reserved.
e9ce8d39 A	3	.\"
5b2abdfb A	4	.\" This code is derived from software contributed to Berkeley by
	5	.\" Chris Torek and the American National Standards Committee X3,
	6	.\" on Information Processing Systems.
	7	.\"
e9ce8d39 A	8	.\" Redistribution and use in source and binary forms, with or without
	9	.\" modification, are permitted provided that the following conditions
	10	.\" are met:
	11	.\" 1. Redistributions of source code must retain the above copyright
	12	.\" notice, this list of conditions and the following disclaimer.
	13	.\" 2. Redistributions in binary form must reproduce the above copyright
	14	.\" notice, this list of conditions and the following disclaimer in the
	15	.\" documentation and/or other materials provided with the distribution.
e9ce8d39 A	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
5b2abdfb	32	.\" @(#)strcat.3 8.1 (Berkeley) 6/4/93
1f2f436a	33	.\" $FreeBSD: src/lib/libc/string/strcat.3,v 1.17 2009/12/01 07:28:56 brueffer Exp $
e9ce8d39	34	.\"
1f2f436a	35	.Dd December 1, 2009
5b2abdfb	36	.Dt STRCAT 3
e9ce8d39 A	37	.Os
e9ce8d39 A	38	.Sh NAME
1f2f436a A	39	.Nm strcat ,
1f2f436a A	40	.Nm strncat
5b2abdfb	41	.Nd concatenate strings
e9ce8d39 A	42	.Sh LIBRARY
	43	.Lb libc
	44	.Sh SYNOPSIS
5b2abdfb A	45	.In string.h
5b2abdfb A	46	.Ft char *
ad3c9f2a A	47	.Fo strcat
	48	.Fa "char *restrict s1"
	49	.Fa "const char *restrict s2"
	50	.Fc
5b2abdfb	51	.Ft char *
ad3c9f2a A	52	.Fo strncat
	53	.Fa "char *restrict s1"
	54	.Fa "const char *restrict s2"
	55	.Fa "size_t n"
	56	.Fc
e9ce8d39 A	57	.Sh DESCRIPTION
e9ce8d39 A	58	The
5b2abdfb	59	.Fn strcat
e9ce8d39	60	and
5b2abdfb A	61	.Fn strncat
	62	functions
	63	append a copy of the null-terminated string
ad3c9f2a	64	.Fa s2
5b2abdfb	65	to the end of the null-terminated string
ad3c9f2a	66	.Fa s1 ,
5b2abdfb A	67	then add a terminating
	68	.Ql \e0 .
	69	The string
ad3c9f2a	70	.Fa s1
5b2abdfb A	71	must have sufficient space to hold the result.
5b2abdfb A	72	.Pp
e9ce8d39	73	The
5b2abdfb A	74	.Fn strncat
	75	function
	76	appends not more than
ad3c9f2a	77	.Fa n
5b2abdfb	78	characters from
ad3c9f2a	79	.Fa s2 ,
5b2abdfb A	80	and then adds a terminating
5b2abdfb A	81	.Ql \e0 .
ad3c9f2a A	82	.Pp
	83	The source and destination strings should not overlap, as the
	84	behavior is undefined.
e9ce8d39	85	.Sh RETURN VALUES
5b2abdfb A	86	The
	87	.Fn strcat
	88	and
	89	.Fn strncat
	90	functions
	91	return the pointer
ad3c9f2a	92	.Fa s1 .
9385eb3d A	93	.Sh SECURITY CONSIDERATIONS
	94	The
	95	.Fn strcat
	96	function is easily misused in a manner
	97	which enables malicious users to arbitrarily change
	98	a running program's functionality through a buffer overflow attack.
	99	(See
	100	the FSA.)
	101	.Pp
	102	Avoid using
	103	.Fn strcat .
	104	Instead, use
	105	.Fn strncat
	106	or
	107	.Fn strlcat
	108	and ensure that no more characters are copied to the destination buffer
	109	than it can hold.
	110	.Pp
	111	Note that
	112	.Fn strncat
	113	can also be problematic.
	114	It may be a security concern for a string to be truncated at all.
	115	Since the truncated string will not be as long as the original,
	116	it may refer to a completely different resource
	117	and usage of the truncated resource
	118	could result in very incorrect behavior.
	119	Example:
	120	.Bd -literal
	121	void
	122	foo(const char *arbitrary_string)
	123	{
ad3c9f2a	124	char onstack[8] = "";
9385eb3d A	125
	126	#if defined(BAD)
	127	/*
	128	* This first strcat is bad behavior. Do not use strcat!
	129	*/
	130	(void)strcat(onstack, arbitrary_string); /* BAD! */
	131	#elif defined(BETTER)
	132	/*
	133	* The following two lines demonstrate better use of
	134	* strncat().
	135	*/
	136	(void)strncat(onstack, arbitrary_string,
	137	sizeof(onstack) - strlen(onstack) - 1);
	138	#elif defined(BEST)
	139	/*
	140	* These lines are even more robust due to testing for
	141	* truncation.
	142	*/
	143	if (strlen(arbitrary_string) + 1 >
	144	sizeof(onstack) - strlen(onstack))
	145	err(1, "onstack would be truncated");
	146	(void)strncat(onstack, arbitrary_string,
	147	sizeof(onstack) - strlen(onstack) - 1);
	148	#endif
	149	}
	150	.Ed
e9ce8d39	151	.Sh SEE ALSO
5b2abdfb A	152	.Xr bcopy 3 ,
	153	.Xr memccpy 3 ,
	154	.Xr memcpy 3 ,
	155	.Xr memmove 3 ,
	156	.Xr strcpy 3 ,
	157	.Xr strlcat 3 ,
1f2f436a A	158	.Xr strlcpy 3 ,
1f2f436a A	159	.Xr wcscat 3
5b2abdfb	160	.Sh STANDARDS
e9ce8d39	161	The
5b2abdfb A	162	.Fn strcat
	163	and
	164	.Fn strncat
	165	functions
	166	conform to
	167	.St -isoC .