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

... / ...

Commit	Line	Data
	1	.\" Copyright (c) 1990, 1991, 1993
	2	.\" The Regents of the University of California. All rights reserved.
	3	.\"
	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	.\"
	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.
	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	.\"
	32	.\" @(#)strcat.3 8.1 (Berkeley) 6/4/93
	33	.\" $FreeBSD: src/lib/libc/string/strcat.3,v 1.17 2009/12/01 07:28:56 brueffer Exp $
	34	.\"
	35	.Dd December 1, 2009
	36	.Dt STRCAT 3
	37	.Os
	38	.Sh NAME
	39	.Nm strcat ,
	40	.Nm strncat
	41	.Nd concatenate strings
	42	.Sh LIBRARY
	43	.Lb libc
	44	.Sh SYNOPSIS
	45	.In string.h
	46	.Ft char *
	47	.Fn strcat "char * restrict s" "const char * restrict append"
	48	.Ft char *
	49	.Fn strncat "char * restrict s" "const char * restrict append" "size_t count"
	50	.Sh DESCRIPTION
	51	The
	52	.Fn strcat
	53	and
	54	.Fn strncat
	55	functions
	56	append a copy of the null-terminated string
	57	.Fa append
	58	to the end of the null-terminated string
	59	.Fa s ,
	60	then add a terminating
	61	.Ql \e0 .
	62	The string
	63	.Fa s
	64	must have sufficient space to hold the result.
	65	.Pp
	66	The
	67	.Fn strncat
	68	function
	69	appends not more than
	70	.Fa count
	71	characters from
	72	.Fa append ,
	73	and then adds a terminating
	74	.Ql \e0 .
	75	.Sh RETURN VALUES
	76	The
	77	.Fn strcat
	78	and
	79	.Fn strncat
	80	functions
	81	return the pointer
	82	.Fa s .
	83	.Sh SECURITY CONSIDERATIONS
	84	The
	85	.Fn strcat
	86	function is easily misused in a manner
	87	which enables malicious users to arbitrarily change
	88	a running program's functionality through a buffer overflow attack.
	89	(See
	90	the FSA.)
	91	.Pp
	92	Avoid using
	93	.Fn strcat .
	94	Instead, use
	95	.Fn strncat
	96	or
	97	.Fn strlcat
	98	and ensure that no more characters are copied to the destination buffer
	99	than it can hold.
	100	.Pp
	101	Note that
	102	.Fn strncat
	103	can also be problematic.
	104	It may be a security concern for a string to be truncated at all.
	105	Since the truncated string will not be as long as the original,
	106	it may refer to a completely different resource
	107	and usage of the truncated resource
	108	could result in very incorrect behavior.
	109	Example:
	110	.Bd -literal
	111	void
	112	foo(const char *arbitrary_string)
	113	{
	114	char onstack[8];
	115
	116	#if defined(BAD)
	117	/*
	118	* This first strcat is bad behavior. Do not use strcat!
	119	*/
	120	(void)strcat(onstack, arbitrary_string); /* BAD! */
	121	#elif defined(BETTER)
	122	/*
	123	* The following two lines demonstrate better use of
	124	* strncat().
	125	*/
	126	(void)strncat(onstack, arbitrary_string,
	127	sizeof(onstack) - strlen(onstack) - 1);
	128	#elif defined(BEST)
	129	/*
	130	* These lines are even more robust due to testing for
	131	* truncation.
	132	*/
	133	if (strlen(arbitrary_string) + 1 >
	134	sizeof(onstack) - strlen(onstack))
	135	err(1, "onstack would be truncated");
	136	(void)strncat(onstack, arbitrary_string,
	137	sizeof(onstack) - strlen(onstack) - 1);
	138	#endif
	139	}
	140	.Ed
	141	.Sh SEE ALSO
	142	.Xr bcopy 3 ,
	143	.Xr memccpy 3 ,
	144	.Xr memcpy 3 ,
	145	.Xr memmove 3 ,
	146	.Xr strcpy 3 ,
	147	.Xr strlcat 3 ,
	148	.Xr strlcpy 3 ,
	149	.Xr wcscat 3
	150	.Sh STANDARDS
	151	The
	152	.Fn strcat
	153	and
	154	.Fn strncat
	155	functions
	156	conform to
	157	.St -isoC .