Debian Codegraph @

upstream/debian-trixie/man3/strcpy.3

raw
1 '\" t
2 .\" Copyright 2022 Alejandro Colomar <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH strcpy 3 2024-06-15 "Linux man-pages 6.9.1"
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 .P
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 .P
21 .RS -4
22 Feature Test Macro Requirements for glibc (see
23 .BR feature_test_macros (7)):
24 .RE
25 .P
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 .P
58 An implementation of these functions might be:
59 .P
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]\[rs]0\[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 .TS
103 allbox;
104 lbx lb lb
105 l l l.
106 Interface Attribute Value
107 T{
108 .na
109 .nh
110 .BR stpcpy (),
111 .BR strcpy (),
112 .BR strcat ()
113 T} Thread safety MT-Safe
114 .TE
115 .SH STANDARDS
116 .TP
117 .BR stpcpy ()
118 POSIX.1-2008.
119 .TP
120 .BR strcpy ()
121 .TQ
122 .BR strcat ()
123 C11, POSIX.1-2008.
124 .SH STANDARDS
125 .TP
126 .BR stpcpy ()
127 POSIX.1-2008.
128 .TP
129 .BR strcpy ()
130 .TQ
131 .BR strcat ()
132 POSIX.1-2001, C89, SVr4, 4.3BSD.
133 .SH CAVEATS
134 The strings
135 .I src
136 and
137 .I dst
138 may not overlap.
139 .P
140 If the destination buffer is not large enough,
141 the behavior is undefined.
142 See
143 .B _FORTIFY_SOURCE
144 in
145 .BR feature_test_macros (7).
146 .P
147 .BR strcat ()
148 can be very inefficient.
149 Read about
150 .UR https://www.joelonsoftware.com/\:2001/12/11/\:back\-to\-basics/
151 Shlemiel the painter
152 .UE .
153 .SH EXAMPLES
154 .\" SRC BEGIN (strcpy.c)
155 .EX
156 #include <err.h>
157 #include <stdio.h>
158 #include <stdlib.h>
159 #include <string.h>
160 \&
161 int
162 main(void)
163 {
164 char *p;
165 char *buf1;
166 char *buf2;
167 size_t len, maxsize;
168 \&
169 maxsize = strlen("Hello ") + strlen("world") + strlen("!") + 1;
170 buf1 = malloc(sizeof(*buf1) * maxsize);
171 if (buf1 == NULL)
172 err(EXIT_FAILURE, "malloc()");
173 buf2 = malloc(sizeof(*buf2) * maxsize);
174 if (buf2 == NULL)
175 err(EXIT_FAILURE, "malloc()");
176 \&
177 p = buf1;
178 p = stpcpy(p, "Hello ");
179 p = stpcpy(p, "world");
180 p = stpcpy(p, "!");
181 len = p \- buf1;
182 \&
183 printf("[len = %zu]: ", len);
184 puts(buf1); // "Hello world!"
185 free(buf1);
186 \&
187 strcpy(buf2, "Hello ");
188 strcat(buf2, "world");
189 strcat(buf2, "!");
190 len = strlen(buf2);
191 \&
192 printf("[len = %zu]: ", len);
193 puts(buf2); // "Hello world!"
194 free(buf2);
195 \&
196 exit(EXIT_SUCCESS);
197 }
198 .EE
199 .\" SRC END
200 .SH SEE ALSO
201 .BR strdup (3),
202 .BR string (3),
203 .BR wcscpy (3),
204 .BR string_copying (7)