stpcpy(3)

1strcpy(3)                  Library Functions Manual                  strcpy(3)
2
3
4

NAME

6       stpcpy, strcpy, strcat - copy or catenate a string
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <string.h>
13
14       char *stpcpy(char *restrict dst, const char *restrict src);
15       char *strcpy(char *restrict dst, const char *restrict src);
16       char *strcat(char *restrict dst, const char *restrict src);
17
18   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
19
20       stpcpy():
21           Since glibc 2.10:
22               _POSIX_C_SOURCE >= 200809L
23           Before glibc 2.10:
24               _GNU_SOURCE
25

DESCRIPTION

27       stpcpy()
28       strcpy()
29              These functions copy the string pointed to by src, into a string
30              at the buffer pointed to by dst.  The programmer is  responsible
31              for  allocating  a  destination  buffer  large  enough, that is,
32              strlen(src) + 1.  For the difference between the two  functions,
33              see RETURN VALUE.
34
35       strcat()
36              This  function catenates the string pointed to by src, after the
37              string pointed to  by  dst  (overwriting  its  terminating  null
38              byte).   The programmer is responsible for allocating a destina‐
39              tion buffer large enough, that is, strlen(dst) +  strlen(src)  +
40              1.
41
42       An implementation of these functions might be:
43
44           char *
45           stpcpy(char *restrict dst, const char *restrict src)
46           {
47               char  *p;
48
49               p = mempcpy(dst, src, strlen(src));
50               *p = '\0';
51
52               return p;
53           }
54
55           char *
56           strcpy(char *restrict dst, const char *restrict src)
57           {
58               stpcpy(dst, src);
59               return dst;
60           }
61
62           char *
63           strcat(char *restrict dst, const char *restrict src)
64           {
65               stpcpy(dst + strlen(dst), src);
66               return dst;
67           }
68

RETURN VALUE

70       stpcpy()
71              This  function returns a pointer to the terminating null byte of
72              the copied string.
73
74       strcpy()
75       strcat()
76              These functions return dst.
77

ATTRIBUTES

79       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
80       tributes(7).
81
82       ┌────────────────────────────────────────────┬───────────────┬─────────┐
83       │Interface                                   │ Attribute     │ Value   │
84       ├────────────────────────────────────────────┼───────────────┼─────────┤
85       │stpcpy(), strcpy(), strcat()                │ Thread safety │ MT-Safe │
86       └────────────────────────────────────────────┴───────────────┴─────────┘
87

STANDARDS

89       stpcpy()
90              POSIX.1-2008.
91
92       strcpy()
93       strcat()
94              C11, POSIX.1-2008.
95

STANDARDS

97       stpcpy()
98              POSIX.1-2008.
99
100       strcpy()
101       strcat()
102              POSIX.1-2001, C89, SVr4, 4.3BSD.
103

CAVEATS

105       The strings src and dst may not overlap.
106
107       If  the  destination  buffer is not large enough, the behavior is unde‐
108       fined.  See _FORTIFY_SOURCE in feature_test_macros(7).
109
110       strcat() can be very  inefficient.   Read  about  Shlemiel  the painter
111       ⟨https://www.joelonsoftware.com/2001/12/11/back-to-basics/⟩.
112

EXAMPLES

114       #include <err.h>
115       #include <stdio.h>
116       #include <stdlib.h>
117       #include <string.h>
118
119       int
120       main(void)
121       {
122           char    *p;
123           char    *buf1;
124           char    *buf2;
125           size_t  len, maxsize;
126
127           maxsize = strlen("Hello ") + strlen("world") + strlen("!") + 1;
128           buf1 = malloc(sizeof(*buf1) * maxsize);
129           if (buf1 == NULL)
130               err(EXIT_FAILURE, "malloc()");
131           buf2 = malloc(sizeof(*buf2) * maxsize);
132           if (buf2 == NULL)
133               err(EXIT_FAILURE, "malloc()");
134
135           p = buf1;
136           p = stpcpy(p, "Hello ");
137           p = stpcpy(p, "world");
138           p = stpcpy(p, "!");
139           len = p - buf1;
140
141           printf("[len = %zu]: ", len);
142           puts(buf1);  // "Hello world!"
143           free(buf1);
144
145           strcpy(buf2, "Hello ");
146           strcat(buf2, "world");
147           strcat(buf2, "!");
148           len = strlen(buf2);
149
150           printf("[len = %zu]: ", len);
151           puts(buf2);  // "Hello world!"
152           free(buf2);
153
154           exit(EXIT_SUCCESS);
155       }
156