man3/strcat.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   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.
  12 .\"
  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.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  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)
  30 .\" 2007-06-15, Marc Boyer <marc.boyer@enseeiht.fr> + mtk
  31 .\"     Improve discussion of strncat().
  32 .TH STRCAT 3  2020-11-01 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 strcat, strncat \- concatenate two strings
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <string.h>
  38 .PP
  39 .BI "char *strcat(char *" dest ", const char *" src );
  40 .BI "char *strncat(char *" dest ", const char *" src ", size_t " n );
  41 .fi
  42 .SH DESCRIPTION
  43 The
  44 .BR strcat ()
  45 function appends the
  46 .I src
  47 string to the
  48 .I dest
  49 string,
  50 overwriting the terminating null byte (\(aq\e0\(aq) at the end of
  51 .IR dest ,
  52 and then adds a terminating null byte.
  53 The strings may not overlap, and the
  54 .I dest
  55 string must have
  56 enough space for the result.
  57 If
  58 .I dest
  59 is not large enough, program behavior is unpredictable;
  60 .IR "buffer overruns are a favorite avenue for attacking secure programs" .
  61 .PP
  62 The
  63 .BR strncat ()
  64 function is similar, except that
  65 .IP * 3
  66 it will use at most
  67 .I n
  68 bytes from
  69 .IR src ;
  70 and
  71 .IP *
  72 .I src
  73 does not need to be null-terminated if it contains
  74 .I n
  75 or more bytes.
  76 .PP
  77 As with
  78 .BR strcat (),
  79 the resulting string in
  80 .I dest
  81 is always null-terminated.
  82 .PP
  83 If
  84 .IR src
  85 contains
  86 .I n
  87 or more bytes,
  88 .BR strncat ()
  89 writes
  90 .I n+1
  91 bytes to
  92 .I dest
  93 .RI ( n
  94 from
  95 .I src
  96 plus the terminating null byte).
  97 Therefore, the size of
  98 .I dest
  99 must be at least
 100 .IR "strlen(dest)+n+1" .
 101 .PP
 102 A simple implementation of
 103 .BR strncat ()
 104 might be:
 105 .PP
 106 .in +4n
 107 .EX
 108 char *
 109 strncat(char *dest, const char *src, size_t n)
 110 {
 111     size_t dest_len = strlen(dest);
 112     size_t i;
 113
 114     for (i = 0 ; i < n && src[i] != \(aq\e0\(aq ; i++)
 115         dest[dest_len + i] = src[i];
 116     dest[dest_len + i] = \(aq\e0\(aq;
 117
 118     return dest;
 119 }
 120 .EE
 121 .in
 122 .SH RETURN VALUE
 123 The
 124 .BR strcat ()
 125 and
 126 .BR strncat ()
 127 functions return a pointer to the resulting string
 128 .IR dest .
 129 .SH ATTRIBUTES
 130 For an explanation of the terms used in this section, see
 131 .BR attributes (7).
 132 .ad l
 133 .nh
 134 .TS
 135 allbox;
 136 lbx lb lb
 137 l l l.
 138 Interface       Attribute       Value
 139 T{
 140 .BR strcat (),
 141 .BR strncat ()
 142 T}      Thread safety   MT-Safe
 143 .TE
 144 .hy
 145 .ad
 146 .sp 1
 147 .SH CONFORMING TO
 148 POSIX.1-2001, POSIX.1-2008, C89, C99, SVr4, 4.3BSD.
 149 .SH NOTES
 150 Some systems (the BSDs, Solaris, and others) provide the following function:
 151 .PP
 152     size_t strlcat(char *dest, const char *src, size_t size);
 153 .PP
 154 This function appends the null-terminated string
 155 .I src
 156 to the string
 157 .IR dest ,
 158 copying at most
 159 .IR "size\-strlen(dest)\-1"
 160 from
 161 .IR src ,
 162 and adds a terminating null byte to the result,
 163 .I unless
 164 .IR size
 165 is less than
 166 .IR strlen(dest) .
 167 This function fixes the buffer overrun problem of
 168 .BR strcat (),
 169 but the caller must still handle the possibility of data loss if
 170 .I size
 171 is too small.
 172 The function returns the length of the string
 173 .BR strlcat ()
 174 tried to create; if the return value is greater than or equal to
 175 .IR size ,
 176 data loss occurred.
 177 If data loss matters, the caller
 178 .I must
 179 either check the arguments before the call, or test the function return value.
 180 .BR strlcat ()
 181 is not present in glibc and is not standardized by POSIX,
 182 .\" https://lwn.net/Articles/506530/
 183 but is available on Linux via the
 184 .IR libbsd
 185 library.
 186 .\"
 187 .SH EXAMPLES
 188 Because
 189 .BR strcat ()
 190 and
 191 .BR strncat ()
 192 must find the null byte that terminates the string
 193 .I dest
 194 using a search that starts at the beginning of the string,
 195 the execution time of these functions
 196 scales according to the length of the string
 197 .IR dest .
 198 This can be demonstrated by running the program below.
 199 (If the goal is to concatenate many strings to one target,
 200 then manually copying the bytes from each source string
 201 while maintaining a pointer to the end of the target string
 202 will provide better performance.)
 203 .\"
 204 .SS Program source
 205 \&
 206 .EX
 207 #include <stdint.h>
 208 #include <string.h>
 209 #include <time.h>
 210 #include <stdio.h>
 211
 212 int
 213 main(int argc, char *argv[])
 214 {
 215 #define LIM 4000000
 216     char p[LIM + 1];    /* +1 for terminating null byte */
 217     time_t base;
 218
 219     base = time(NULL);
 220     p[0] = \(aq\e0\(aq;
 221
 222     for (int j = 0; j < LIM; j++) {
 223         if ((j % 10000) == 0)
 224             printf("%d %jd\en", j, (intmax_t) (time(NULL) \- base));
 225         strcat(p, "a");
 226     }
 227 }
 228 .EE
 229 .\"
 230 .SH SEE ALSO
 231 .BR bcopy (3),
 232 .BR memccpy (3),
 233 .BR memcpy (3),
 234 .BR strcpy (3),
 235 .BR string (3),
 236 .BR strncpy (3),
 237 .BR wcscat (3),
 238 .BR wcsncat (3)