]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" References consulted: | |
26 | .\" Linux libc source code | |
27 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
28 | .\" 386BSD man pages | |
29 | .\" Modified Sat Jul 24 18:11:47 1993 by Rik Faith (faith@cs.unc.edu) | |
668fdda1 | 30 | .\" 2007-06-15, Marc Boyer <marc.boyer@enseeiht.fr> + mtk |
388ab548 | 31 | .\" Improve discussion of strncat(). |
4b8c67d9 | 32 | .TH STRCAT 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
33 | .SH NAME |
34 | strcat, strncat \- concatenate two strings | |
35 | .SH SYNOPSIS | |
36 | .nf | |
37 | .B #include <string.h> | |
68e4db0a | 38 | .PP |
fea681da | 39 | .BI "char *strcat(char *" dest ", const char *" src ); |
68e4db0a | 40 | .PP |
fea681da MK |
41 | .BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); |
42 | .fi | |
43 | .SH DESCRIPTION | |
60a90ecd MK |
44 | The |
45 | .BR strcat () | |
46d8df8e MK |
46 | function appends the |
47 | .I src | |
48 | string to the | |
49 | .I dest | |
50 | string, | |
71d9e7ae | 51 | overwriting the terminating null byte (\(aq\\0\(aq) at the end of |
46d8df8e MK |
52 | .IR dest , |
53 | and then adds a terminating null byte. | |
54 | The strings may not overlap, and the | |
55 | .I dest | |
56 | string must have | |
fea681da | 57 | enough space for the result. |
1f577d97 MK |
58 | If |
59 | .I dest | |
60 | is not large enough, program behavior is unpredictable; | |
61 | .IR "buffer overruns are a favorite avenue for attacking secure programs" . | |
fea681da | 62 | .PP |
60a90ecd MK |
63 | The |
64 | .BR strncat () | |
388ab548 MK |
65 | function is similar, except that |
66 | .IP * 3 | |
46d8df8e MK |
67 | it will use at most |
68 | .I n | |
69 | bytes from | |
70 | .IR src ; | |
71 | and | |
388ab548 | 72 | .IP * |
46d8df8e MK |
73 | .I src |
74 | does not need to be null-terminated if it contains | |
75 | .I n | |
76 | or more bytes. | |
388ab548 MK |
77 | .PP |
78 | As with | |
79 | .BR strcat (), | |
46d8df8e MK |
80 | the resulting string in |
81 | .I dest | |
82 | is always null-terminated. | |
388ab548 | 83 | .PP |
46d8df8e | 84 | If |
51700fd7 | 85 | .IR src |
46d8df8e MK |
86 | contains |
87 | .I n | |
88 | or more bytes, | |
cd117d48 | 89 | .BR strncat () |
51700fd7 | 90 | writes |
46d8df8e MK |
91 | .I n+1 |
92 | bytes to | |
93 | .I dest | |
94 | .RI ( n | |
95 | from | |
96 | .I src | |
97 | plus the terminating null byte). | |
98 | Therefore, the size of | |
99 | .I dest | |
100 | must be at least | |
101 | .IR "strlen(dest)+n+1" . | |
847e0d88 | 102 | .PP |
388ab548 | 103 | A simple implementation of |
668fdda1 | 104 | .BR strncat () |
388ab548 | 105 | might be: |
e646a1ba | 106 | .PP |
088a639b | 107 | .in +4n |
e646a1ba | 108 | .EX |
b739e8e1 | 109 | char * |
388ab548 MK |
110 | strncat(char *dest, const char *src, size_t n) |
111 | { | |
112 | size_t dest_len = strlen(dest); | |
145039e9 | 113 | size_t i; |
388ab548 | 114 | |
f81fb444 | 115 | for (i = 0 ; i < n && src[i] != \(aq\\0\(aq ; i++) |
388ab548 | 116 | dest[dest_len + i] = src[i]; |
f81fb444 | 117 | dest[dest_len + i] = \(aq\\0\(aq; |
388ab548 MK |
118 | |
119 | return dest; | |
120 | } | |
b8302363 | 121 | .EE |
388ab548 | 122 | .in |
47297adb | 123 | .SH RETURN VALUE |
60a90ecd MK |
124 | The |
125 | .BR strcat () | |
126 | and | |
127 | .BR strncat () | |
46d8df8e MK |
128 | functions return a pointer to the resulting string |
129 | .IR dest . | |
9a55cdeb | 130 | .SH ATTRIBUTES |
cb392f65 PH |
131 | For an explanation of the terms used in this section, see |
132 | .BR attributes (7). | |
133 | .TS | |
134 | allbox; | |
135 | lbw19 lb lb | |
136 | l l l. | |
137 | Interface Attribute Value | |
138 | T{ | |
139 | .BR strcat (), | |
9a55cdeb | 140 | .BR strncat () |
cb392f65 PH |
141 | T} Thread safety MT-Safe |
142 | .TE | |
47297adb | 143 | .SH CONFORMING TO |
f7031d92 | 144 | POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD. |
ef3e8464 MK |
145 | .SH NOTES |
146 | Some systems (the BSDs, Solaris, and others) provide the following function: | |
847e0d88 | 147 | .PP |
ef3e8464 | 148 | size_t strlcat(char *dest, const char *src, size_t size); |
847e0d88 | 149 | .PP |
ef3e8464 MK |
150 | This function appends the null-terminated string |
151 | .I src | |
152 | to the string | |
d4dfdd5b | 153 | .IR dest , |
ef3e8464 MK |
154 | copying at most |
155 | .IR "size\-strlen(dest)\-1" | |
156 | from | |
157 | .IR src , | |
be7d49c1 | 158 | and adds a terminating null byte to the result, |
ef3e8464 MK |
159 | .I unless |
160 | .IR size | |
161 | is less than | |
162 | .IR strlen(dest) . | |
163 | This function fixes the buffer overrun problem of | |
164 | .BR strcat (), | |
165 | but the caller must still handle the possibility of data loss if | |
166 | .I size | |
167 | is too small. | |
168 | The function returns the length of the string | |
169 | .BR strlcat () | |
170 | tried to create; if the return value is greater than or equal to | |
171 | .IR size , | |
172 | data loss occurred. | |
173 | If data loss matters, the caller | |
174 | .I must | |
175 | either check the arguments before the call, or test the function return value. | |
176 | .BR strlcat () | |
177 | is not present in glibc and is not standardized by POSIX, | |
178 | .\" https://lwn.net/Articles/506530/ | |
179 | but is available on Linux via the | |
180 | .IR libbsd | |
181 | library. | |
b2f0984e MK |
182 | .\" |
183 | .SH EXAMPLE | |
184 | Because | |
185 | .BR strcat () | |
186 | and | |
187 | .BR strncat () | |
188 | must find the null byte that terminates the string | |
189 | .I dest | |
190 | using a search that starts at the beginning of the string, | |
191 | the execution time of these functions | |
192 | scales according to the length of the string | |
193 | .IR dest . | |
194 | This can be demonstrated by running the program below. | |
195 | (If the goal is to concatenate many strings to one target, | |
196 | then manually copying the bytes from each source string | |
197 | while maintaining a pointer to the end of the target string | |
198 | will provide better performance.) | |
199 | .\" | |
200 | .SS Program source | |
201 | \& | |
e7d0bb47 | 202 | .EX |
b2f0984e MK |
203 | #include <string.h> |
204 | #include <time.h> | |
205 | #include <stdio.h> | |
206 | ||
207 | int | |
208 | main(int argc, char *argv[]) | |
209 | { | |
210 | #define LIM 4000000 | |
211 | int j; | |
212 | char p[LIM]; | |
213 | time_t base; | |
2ae96e8a | 214 | |
b2f0984e MK |
215 | base = time(NULL); |
216 | p[0] = \(aq\\0\(aq; | |
217 | ||
218 | for (j = 0; j < LIM; j++) { | |
219 | if ((j % 10000) == 0) | |
220 | printf("%d %ld\\n", j, (long) (time(NULL) \- base)); | |
221 | strcat(p, "a"); | |
222 | } | |
223 | } | |
e7d0bb47 | 224 | .EE |
b2f0984e | 225 | .\" |
47297adb | 226 | .SH SEE ALSO |
fea681da MK |
227 | .BR bcopy (3), |
228 | .BR memccpy (3), | |
229 | .BR memcpy (3), | |
230 | .BR strcpy (3), | |
d095200e | 231 | .BR string (3), |
fea681da MK |
232 | .BR strncpy (3), |
233 | .BR wcscat (3), | |
234 | .BR wcsncat (3) |