man3/strcpy.3

   1 '\" t
   2 .\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .TH strcpy 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 stpcpy, strcpy, strcat \- copy or catenate a string
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .SH SYNOPSIS
  13 .nf
  14 .B #include <string.h>
  15 .PP
  16 .BI "char *stpcpy(char *restrict " dst ", const char *restrict " src );
  17 .BI "char *strcpy(char *restrict " dst ", const char *restrict " src );
  18 .BI "char *strcat(char *restrict " dst ", const char *restrict " src );
  19 .fi
  20 .PP
  21 .RS -4
  22 Feature Test Macro Requirements for glibc (see
  23 .BR feature_test_macros (7)):
  24 .RE
  25 .PP
  26 .BR stpcpy ():
  27 .nf
  28     Since glibc 2.10:
  29         _POSIX_C_SOURCE >= 200809L
  30     Before glibc 2.10:
  31         _GNU_SOURCE
  32 .fi
  33 .SH DESCRIPTION
  34 .TP
  35 .BR stpcpy ()
  36 .TQ
  37 .BR strcpy ()
  38 These functions copy the string pointed to by
  39 .IR src ,
  40 into a string
  41 at the buffer pointed to by
  42 .IR dst .
  43 The programmer is responsible for allocating a destination buffer large enough,
  44 that is,
  45 .IR "strlen(src) + 1" .
  46 For the difference between the two functions, see RETURN VALUE.
  47 .TP
  48 .BR strcat ()
  49 This function catenates the string pointed to by
  50 .IR src ,
  51 after the string pointed to by
  52 .I dst
  53 (overwriting its terminating null byte).
  54 The programmer is responsible for allocating a destination buffer large enough,
  55 that is,
  56 .IR "strlen(dst) + strlen(src) + 1" .
  57 .PP
  58 An implementation of these functions might be:
  59 .PP
  60 .in +4n
  61 .EX
  62 char *
  63 stpcpy(char *restrict dst, const char *restrict src)
  64 {
  65     char  *p;
  66
  67     p = mempcpy(dst, src, strlen(src));
  68     *p = \[aq]\e0\[aq];
  69
  70     return p;
  71 }
  72
  73 char *
  74 strcpy(char *restrict dst, const char *restrict src)
  75 {
  76     stpcpy(dst, src);
  77     return dst;
  78 }
  79
  80 char *
  81 strcat(char *restrict dst, const char *restrict src)
  82 {
  83     stpcpy(dst + strlen(dst), src);
  84     return dst;
  85 }
  86 .EE
  87 .in
  88 .SH RETURN VALUE
  89 .TP
  90 .BR stpcpy ()
  91 This function returns
  92 a pointer to the terminating null byte of the copied string.
  93 .TP
  94 .BR strcpy ()
  95 .TQ
  96 .BR strcat ()
  97 These functions return
  98 .IR dst .
  99 .SH ATTRIBUTES
 100 For an explanation of the terms used in this section, see
 101 .BR attributes (7).
 102 .ad l
 103 .nh
 104 .TS
 105 allbox;
 106 lbx lb lb
 107 l l l.
 108 Interface       Attribute       Value
 109 T{
 110 .BR stpcpy (),
 111 .BR strcpy (),
 112 .BR strcat ()
 113 T}      Thread safety   MT-Safe
 114 .TE
 115 .hy
 116 .ad
 117 .sp 1
 118 .SH STANDARDS
 119 .TP
 120 .BR stpcpy ()
 121 POSIX.1-2008.
 122 .TP
 123 .BR strcpy ()
 124 .TQ
 125 .BR strcat ()
 126 POSIX.1-2001, POSIX.1-2008, C99, SVr4, 4.3BSD.
 127 .SH CAVEATS
 128 The strings
 129 .I src
 130 and
 131 .I dst
 132 may not overlap.
 133 .PP
 134 If the destination buffer is not large enough,
 135 the behavior is undefined.
 136 See
 137 .B _FORTIFY_SOURCE
 138 in
 139 .BR feature_test_macros (7).
 140 .PP
 141 .BR strcat ()
 142 can be very inefficient.
 143 Read about
 144 .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
 145 Shlemiel the painter
 146 .UE .
 147 .SH EXAMPLES
 148 .\" SRC BEGIN (strcpy.c)
 149 .EX
 150 #include <err.h>
 151 #include <stdio.h>
 152 #include <stdlib.h>
 153 #include <string.h>
 154
 155 int
 156 main(void)
 157 {
 158     char    *p;
 159     char    *buf1;
 160     char    *buf2;
 161     size_t  len, maxsize;
 162
 163     maxsize = strlen("Hello ") + strlen("world") + strlen("!") + 1;
 164     buf1 = malloc(sizeof(*buf1) * maxsize);
 165     if (buf1 == NULL)
 166         err(EXIT_FAILURE, "malloc()");
 167     buf2 = malloc(sizeof(*buf2) * maxsize);
 168     if (buf2 == NULL)
 169         err(EXIT_FAILURE, "malloc()");
 170
 171     p = buf1;
 172     p = stpcpy(p, "Hello ");
 173     p = stpcpy(p, "world");
 174     p = stpcpy(p, "!");
 175     len = p \- buf1;
 176
 177     printf("[len = %zu]: ", len);
 178     puts(buf1);  // "Hello world!"
 179     free(buf1);
 180
 181     strcpy(buf2, "Hello ");
 182     strcat(buf2, "world");
 183     strcat(buf2, "!");
 184     len = strlen(buf2);
 185
 186     printf("[len = %zu]: ", len);
 187     puts(buf2);  // "Hello world!"
 188     free(buf2);
 189
 190     exit(EXIT_SUCCESS);
 191 }
 192 .EE
 193 .\" SRC END
 194 .SH SEE ALSO
 195 .BR strdup (3),
 196 .BR string (3),
 197 .BR wcscpy (3),
 198 .BR string_copying (7)