]>
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(). |
ef3e8464 | 32 | .TH STRCAT 3 2012-07-19 "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> | |
38 | .sp | |
39 | .BI "char *strcat(char *" dest ", const char *" src ); | |
40 | .sp | |
41 | .BI "char *strncat(char *" dest ", const char *" src ", size_t " n ); | |
42 | .fi | |
43 | .SH DESCRIPTION | |
60a90ecd MK |
44 | The |
45 | .BR strcat () | |
46 | function appends the \fIsrc\fP string to the | |
71d9e7ae MK |
47 | \fIdest\fP string, |
48 | overwriting the terminating null byte (\(aq\\0\(aq) at the end of | |
668fdda1 | 49 | \fIdest\fP, and then adds a terminating null byte. |
c13182ef | 50 | The strings may not overlap, and the \fIdest\fP string must have |
fea681da | 51 | enough space for the result. |
1f577d97 MK |
52 | If |
53 | .I dest | |
54 | is not large enough, program behavior is unpredictable; | |
55 | .IR "buffer overruns are a favorite avenue for attacking secure programs" . | |
fea681da | 56 | .PP |
60a90ecd MK |
57 | The |
58 | .BR strncat () | |
388ab548 MK |
59 | function is similar, except that |
60 | .IP * 3 | |
a00b7454 | 61 | it will use at most \fIn\fP bytes from \fIsrc\fP; and |
388ab548 | 62 | .IP * |
bd74a873 | 63 | \fIsrc\fP does not need to be null-terminated if it contains |
a00b7454 | 64 | \fIn\fP or more bytes. |
388ab548 MK |
65 | .PP |
66 | As with | |
67 | .BR strcat (), | |
bd74a873 | 68 | the resulting string in \fIdest\fP is always null-terminated. |
388ab548 | 69 | .PP |
a00b7454 | 70 | If \fIsrc\fP contains \fIn\fP or more bytes, |
cd117d48 | 71 | .BR strncat () |
a00b7454 | 72 | writes \fIn+1\fP bytes to \fIdest\fP (\fIn\fP |
668fdda1 MK |
73 | from \fIsrc\fP plus the terminating null byte). |
74 | Therefore, the size of \fIdest\fP must be at least | |
388ab548 MK |
75 | \fIstrlen(dest)+n+1\fP. |
76 | ||
77 | A simple implementation of | |
668fdda1 | 78 | .BR strncat () |
388ab548 | 79 | might be: |
088a639b | 80 | .in +4n |
388ab548 MK |
81 | .nf |
82 | ||
83 | char* | |
84 | strncat(char *dest, const char *src, size_t n) | |
85 | { | |
86 | size_t dest_len = strlen(dest); | |
145039e9 | 87 | size_t i; |
388ab548 | 88 | |
f81fb444 | 89 | for (i = 0 ; i < n && src[i] != \(aq\\0\(aq ; i++) |
388ab548 | 90 | dest[dest_len + i] = src[i]; |
f81fb444 | 91 | dest[dest_len + i] = \(aq\\0\(aq; |
388ab548 MK |
92 | |
93 | return dest; | |
94 | } | |
95 | .fi | |
96 | .in | |
47297adb | 97 | .SH RETURN VALUE |
60a90ecd MK |
98 | The |
99 | .BR strcat () | |
100 | and | |
101 | .BR strncat () | |
388ab548 | 102 | functions return a pointer to the resulting string \fIdest\fP. |
47297adb | 103 | .SH CONFORMING TO |
68e1685c | 104 | SVr4, 4.3BSD, C89, C99. |
ef3e8464 MK |
105 | .SH NOTES |
106 | Some systems (the BSDs, Solaris, and others) provide the following function: | |
107 | ||
108 | size_t strlcat(char *dest, const char *src, size_t size); | |
109 | ||
110 | This function appends the null-terminated string | |
111 | .I src | |
112 | to the string | |
d4dfdd5b | 113 | .IR dest , |
ef3e8464 MK |
114 | copying at most |
115 | .IR "size\-strlen(dest)\-1" | |
116 | from | |
117 | .IR src , | |
118 | and adds a null terminator to the result, | |
119 | .I unless | |
120 | .IR size | |
121 | is less than | |
122 | .IR strlen(dest) . | |
123 | This function fixes the buffer overrun problem of | |
124 | .BR strcat (), | |
125 | but the caller must still handle the possibility of data loss if | |
126 | .I size | |
127 | is too small. | |
128 | The function returns the length of the string | |
129 | .BR strlcat () | |
130 | tried to create; if the return value is greater than or equal to | |
131 | .IR size , | |
132 | data loss occurred. | |
133 | If data loss matters, the caller | |
134 | .I must | |
135 | either check the arguments before the call, or test the function return value. | |
136 | .BR strlcat () | |
137 | is not present in glibc and is not standardized by POSIX, | |
138 | .\" https://lwn.net/Articles/506530/ | |
139 | but is available on Linux via the | |
140 | .IR libbsd | |
141 | library. | |
47297adb | 142 | .SH SEE ALSO |
fea681da MK |
143 | .BR bcopy (3), |
144 | .BR memccpy (3), | |
145 | .BR memcpy (3), | |
146 | .BR strcpy (3), | |
d095200e | 147 | .BR string (3), |
fea681da MK |
148 | .BR strncpy (3), |
149 | .BR wcscat (3), | |
150 | .BR wcsncat (3) |