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 (date) "Linux man-pages (unreleased)"
  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 \(bu 3
  50 it will use at most
  51 .I n
  52 bytes from
  53 .IR src ;
  54 and
  55 .IP \(bu
  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 .I 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 STANDARDS
 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 .in +4n
 137 .EX
 138 size_t strlcat(char *dest, const char *src, size_t size);
 139 .EE
 140 .in
 141 .PP
 142 This function appends the null-terminated string
 143 .I src
 144 to the string
 145 .IR dest ,
 146 copying at most
 147 .I size\-strlen(dest)\-1
 148 from
 149 .IR src ,
 150 and adds a terminating null byte to the result,
 151 .I unless
 152 .I size
 153 is less than
 154 .IR strlen(dest) .
 155 This function fixes the buffer overrun problem of
 156 .BR strcat (),
 157 but the caller must still handle the possibility of data loss if
 158 .I size
 159 is too small.
 160 The function returns the length of the string
 161 .BR strlcat ()
 162 tried to create; if the return value is greater than or equal to
 163 .IR size ,
 164 data loss occurred.
 165 If data loss matters, the caller
 166 .I must
 167 either check the arguments before the call, or test the function return value.
 168 .BR strlcat ()
 169 is not present in glibc and is not standardized by POSIX,
 170 .\" https://lwn.net/Articles/506530/
 171 but is available on Linux via the
 172 .I libbsd
 173 library.
 174 .\"
 175 .SH EXAMPLES
 176 Because
 177 .BR strcat ()
 178 and
 179 .BR strncat ()
 180 must find the null byte that terminates the string
 181 .I dest
 182 using a search that starts at the beginning of the string,
 183 the execution time of these functions
 184 scales according to the length of the string
 185 .IR dest .
 186 This can be demonstrated by running the program below.
 187 (If the goal is to concatenate many strings to one target,
 188 then manually copying the bytes from each source string
 189 while maintaining a pointer to the end of the target string
 190 will provide better performance.)
 191 .\"
 192 .SS Program source
 193 \&
 194 .\" SRC BEGIN (strcat.c)
 195 .EX
 196 #include <stdint.h>
 197 #include <stdio.h>
 198 #include <string.h>
 199 #include <time.h>
 200
 201 int
 202 main(void)
 203 {
 204 #define LIM 4000000
 205     char p[LIM + 1];    /* +1 for terminating null byte */
 206     time_t base;
 207
 208     base = time(NULL);
 209     p[0] = \(aq\e0\(aq;
 210
 211     for (unsigned int j = 0; j < LIM; j++) {
 212         if ((j % 10000) == 0)
 213             printf("%u %jd\en", j, (intmax_t) (time(NULL) \- base));
 214         strcat(p, "a");
 215     }
 216 }
 217 .EE
 218 .\" SRC END
 219 .SH SEE ALSO
 220 .BR bcopy (3),
 221 .BR memccpy (3),
 222 .BR memcpy (3),
 223 .BR strcpy (3),
 224 .BR string (3),
 225 .BR strncpy (3),
 226 .BR wcscat (3),
 227 .BR wcsncat (3)