xref: /freebsd/lib/libc/string/strcat.3 (revision 41f91cb492a2bb7991659912d8be5c0a774cd003)
158f0484fSRodney W. Grimes.\" Copyright (c) 1990, 1991, 1993
258f0484fSRodney W. Grimes.\"	The Regents of the University of California.  All rights reserved.
358f0484fSRodney W. Grimes.\"
458f0484fSRodney W. Grimes.\" This code is derived from software contributed to Berkeley by
558f0484fSRodney W. Grimes.\" Chris Torek and the American National Standards Committee X3,
658f0484fSRodney W. Grimes.\" on Information Processing Systems.
758f0484fSRodney W. Grimes.\"
858f0484fSRodney W. Grimes.\" Redistribution and use in source and binary forms, with or without
958f0484fSRodney W. Grimes.\" modification, are permitted provided that the following conditions
1058f0484fSRodney W. Grimes.\" are met:
1158f0484fSRodney W. Grimes.\" 1. Redistributions of source code must retain the above copyright
1258f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer.
1358f0484fSRodney W. Grimes.\" 2. Redistributions in binary form must reproduce the above copyright
1458f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer in the
1558f0484fSRodney W. Grimes.\"    documentation and/or other materials provided with the distribution.
1658f0484fSRodney W. Grimes.\" 3. All advertising materials mentioning features or use of this software
1758f0484fSRodney W. Grimes.\"    must display the following acknowledgement:
1858f0484fSRodney W. Grimes.\"	This product includes software developed by the University of
1958f0484fSRodney W. Grimes.\"	California, Berkeley and its contributors.
2058f0484fSRodney W. Grimes.\" 4. Neither the name of the University nor the names of its contributors
2158f0484fSRodney W. Grimes.\"    may be used to endorse or promote products derived from this software
2258f0484fSRodney W. Grimes.\"    without specific prior written permission.
2358f0484fSRodney W. Grimes.\"
2458f0484fSRodney W. Grimes.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
2558f0484fSRodney W. Grimes.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
2658f0484fSRodney W. Grimes.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
2758f0484fSRodney W. Grimes.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
2858f0484fSRodney W. Grimes.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
2958f0484fSRodney W. Grimes.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
3058f0484fSRodney W. Grimes.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
3158f0484fSRodney W. Grimes.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
3258f0484fSRodney W. Grimes.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
3358f0484fSRodney W. Grimes.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
3458f0484fSRodney W. Grimes.\" SUCH DAMAGE.
3558f0484fSRodney W. Grimes.\"
3658f0484fSRodney W. Grimes.\"     @(#)strcat.3	8.1 (Berkeley) 6/4/93
377f3dea24SPeter Wemm.\" $FreeBSD$
3858f0484fSRodney W. Grimes.\"
3958f0484fSRodney W. Grimes.Dd June 4, 1993
4058f0484fSRodney W. Grimes.Dt STRCAT 3
4158f0484fSRodney W. Grimes.Os
4258f0484fSRodney W. Grimes.Sh NAME
4358f0484fSRodney W. Grimes.Nm strcat
4458f0484fSRodney W. Grimes.Nd concatenate strings
4525bb73e0SAlexey Zelkin.Sh LIBRARY
4625bb73e0SAlexey Zelkin.Lb libc
4758f0484fSRodney W. Grimes.Sh SYNOPSIS
4832eef9aeSRuslan Ermilov.In string.h
4958f0484fSRodney W. Grimes.Ft char *
5058f0484fSRodney W. Grimes.Fn strcat "char *s" "const char *append"
5158f0484fSRodney W. Grimes.Ft char *
5258f0484fSRodney W. Grimes.Fn strncat "char *s" "const char *append" "size_t count"
5358f0484fSRodney W. Grimes.Sh DESCRIPTION
5458f0484fSRodney W. GrimesThe
5558f0484fSRodney W. Grimes.Fn strcat
5658f0484fSRodney W. Grimesand
5758f0484fSRodney W. Grimes.Fn strncat
5858f0484fSRodney W. Grimesfunctions
5958f0484fSRodney W. Grimesappend a copy of the null-terminated string
6058f0484fSRodney W. Grimes.Fa append
6158f0484fSRodney W. Grimesto the end of the null-terminated string
6258f0484fSRodney W. Grimes.Fa s ,
6358f0484fSRodney W. Grimesthen add a terminating
6458f0484fSRodney W. Grimes.Ql \e0 .
6558f0484fSRodney W. GrimesThe string
6658f0484fSRodney W. Grimes.Fa s
6758f0484fSRodney W. Grimesmust have sufficient space to hold the result.
6858f0484fSRodney W. Grimes.Pp
6958f0484fSRodney W. GrimesThe
7058f0484fSRodney W. Grimes.Fn strncat
7158f0484fSRodney W. Grimesfunction
7258f0484fSRodney W. Grimesappends not more than
7358f0484fSRodney W. Grimes.Fa count
7459f00bcdSMike Pritchardcharacters from
7559f00bcdSMike Pritchard.Fa append ,
7659f00bcdSMike Pritchardand then adds a terminating
7759f00bcdSMike Pritchard.Ql \e0 .
7858f0484fSRodney W. Grimes.Sh RETURN VALUES
7958f0484fSRodney W. GrimesThe
8058f0484fSRodney W. Grimes.Fn strcat
8158f0484fSRodney W. Grimesand
8258f0484fSRodney W. Grimes.Fn strncat
8358f0484fSRodney W. Grimesfunctions
8458f0484fSRodney W. Grimesreturn the pointer
8558f0484fSRodney W. Grimes.Fa s .
8641f91cb4SChris Costello.Sh SECURITY CONSIDERATIONS
8741f91cb4SChris CostelloThe
8841f91cb4SChris Costello.Fn strcat
8941f91cb4SChris Costellofunction is easily misused in a manner
9041f91cb4SChris Costellowhich enables malicious users to arbitrarily change
9141f91cb4SChris Costelloa running program's functionality through a buffer overflow attack.
9241f91cb4SChris Costello(See
9341f91cb4SChris Costellothe FSA.)
9441f91cb4SChris Costello.Pp
9541f91cb4SChris CostelloAvoid using
9641f91cb4SChris Costello.Fn strcat .
9741f91cb4SChris CostelloInstead, use
9841f91cb4SChris Costello.Fn strncat
9941f91cb4SChris Costelloor
10041f91cb4SChris Costello.Fn strlcat
10141f91cb4SChris Costelloand ensure that no more characters are copied to the destination buffer
10241f91cb4SChris Costellothan it can hold.
10341f91cb4SChris Costello.Pp
10441f91cb4SChris CostelloNote that
10541f91cb4SChris Costello.Fn strncat
10641f91cb4SChris Costellocan also be problematic.
10741f91cb4SChris CostelloIt may be a security concern for a string to be truncated at all.
10841f91cb4SChris CostelloSince the truncated string will not be as long as the original,
10941f91cb4SChris Costelloit may refer to a completely different resource
11041f91cb4SChris Costelloand usage of the truncated resource
11141f91cb4SChris Costellocould result in very incorrect behavior.
11241f91cb4SChris CostelloExample:
11341f91cb4SChris Costello.Bd -literal
11441f91cb4SChris Costellovoid
11541f91cb4SChris Costellofoo(const char *arbitrary_string)
11641f91cb4SChris Costello{
11741f91cb4SChris Costello	char onstack[8];
11841f91cb4SChris Costello
11941f91cb4SChris Costello#if defined(BAD)
12041f91cb4SChris Costello	/*
12141f91cb4SChris Costello	 * This first strcat is bad behavior.  Do not use strcat!
12241f91cb4SChris Costello	 */
12341f91cb4SChris Costello	(void)strcat(onstack, arbitrary_string);	/* BAD! */
12441f91cb4SChris Costello#elif defined(BETTER)
12541f91cb4SChris Costello	/*
12641f91cb4SChris Costello	 * The following two lines demonstrate better use of
12741f91cb4SChris Costello	 * strncat().
12841f91cb4SChris Costello	 */
12941f91cb4SChris Costello	(void)strncat(onstack, arbitrary_string,
13041f91cb4SChris Costello	    sizeof(onstack) - strlen(onstack) - 1);
13141f91cb4SChris Costello#elif defined(BEST)
13241f91cb4SChris Costello	/*
13341f91cb4SChris Costello	 * These lines are even more robust due to testing for
13441f91cb4SChris Costello	 * truncation.
13541f91cb4SChris Costello	 */
13641f91cb4SChris Costello	if (strlen(arbitrary_string) + 1 >
13741f91cb4SChris Costello	    sizeof(onstack) - strlen(onstack))
13841f91cb4SChris Costello		err(1, "onstack would be truncated");
13941f91cb4SChris Costello	(void)strncat(onstack, arbitrary_string,
14041f91cb4SChris Costello	    sizeof(onstack) - strlen(onstack) - 1);
14141f91cb4SChris Costello#endif
14241f91cb4SChris Costello}
14341f91cb4SChris Costello
14441f91cb4SChris Costello.Ed
14558f0484fSRodney W. Grimes.Sh SEE ALSO
14658f0484fSRodney W. Grimes.Xr bcopy 3 ,
14758f0484fSRodney W. Grimes.Xr memccpy 3 ,
14858f0484fSRodney W. Grimes.Xr memcpy 3 ,
14958f0484fSRodney W. Grimes.Xr memmove 3 ,
1504e2abf95SWarner Losh.Xr strcpy 3 ,
1514e2abf95SWarner Losh.Xr strlcat 3 ,
1524e2abf95SWarner Losh.Xr strlcpy 3
15341f91cb4SChris Costello.Rs
15441f91cb4SChris Costello.%T "The FreeBSD Security Architecture"
15541f91cb4SChris Costello.%J "/usr/share/doc/{to be decided}"
15641f91cb4SChris Costello.Re
15758f0484fSRodney W. Grimes.Sh STANDARDS
15858f0484fSRodney W. GrimesThe
15958f0484fSRodney W. Grimes.Fn strcat
16058f0484fSRodney W. Grimesand
16158f0484fSRodney W. Grimes.Fn strncat
16258f0484fSRodney W. Grimesfunctions
16358f0484fSRodney W. Grimesconform to
164588a200cSRuslan Ermilov.St -isoC .
165