man3/strcat.3

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