xref: /freebsd/lib/libc/string/strcpy.3 (revision 4f52dfbb) 
1.\" Copyright (c) 1990, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" Chris Torek and the American National Standards Committee X3,
6.\" on Information Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)strcpy.3	8.1 (Berkeley) 6/4/93
33.\" $FreeBSD$
34.\"
35.Dd February 28, 2009
36.Dt STRCPY 3
37.Os
38.Sh NAME
39.Nm stpcpy ,
40.Nm stpncpy ,
41.Nm strcpy ,
42.Nm strncpy
43.Nd copy strings
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In string.h
48.Ft char *
49.Fn stpcpy "char * restrict dst" "const char * restrict src"
50.Ft char *
51.Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len"
52.Ft char *
53.Fn strcpy "char * restrict dst" "const char * restrict src"
54.Ft char *
55.Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
56.Sh DESCRIPTION
57The
58.Fn stpcpy
59and
60.Fn strcpy
61functions
62copy the string
63.Fa src
64to
65.Fa dst
66(including the terminating
67.Ql \e0
68character.)
69If
70.Fa src
71and
72.Fa dst
73overlap, the results are undefined.
74.Pp
75The
76.Fn stpncpy
77and
78.Fn strncpy
79functions copy at most
80.Fa len
81characters from
82.Fa src
83into
84.Fa dst .
85If
86.Fa src
87is less than
88.Fa len
89characters long,
90the remainder of
91.Fa dst
92is filled with
93.Ql \e0
94characters.
95Otherwise,
96.Fa dst
97is
98.Em not
99terminated.
100If
101.Fa src
102and
103.Fa dst
104overlap, the results are undefined.
105.Sh RETURN VALUES
106The
107.Fn strcpy
108and
109.Fn strncpy
110functions
111return
112.Fa dst .
113The
114.Fn stpcpy
115and
116.Fn stpncpy
117functions return a pointer to the terminating
118.Ql \e0
119character of
120.Fa dst .
121If
122.Fn stpncpy
123does not terminate
124.Fa dst
125with a
126.Dv NUL
127character, it instead returns a pointer to
128.Li dst[n]
129(which does not necessarily refer to a valid memory location.)
130.Sh EXAMPLES
131The following sets
132.Va chararray
133to
134.Dq Li abc\e0\e0\e0 :
135.Bd -literal -offset indent
136char chararray[6];
137
138(void)strncpy(chararray, "abc", sizeof(chararray));
139.Ed
140.Pp
141The following sets
142.Va chararray
143to
144.Dq Li abcdef :
145.Bd -literal -offset indent
146char chararray[6];
147
148(void)strncpy(chararray, "abcdefgh", sizeof(chararray));
149.Ed
150.Pp
151Note that it does
152.Em not
153.Tn NUL
154terminate
155.Va chararray
156because the length of the source string is greater than or equal
157to the length argument.
158.Pp
159The following copies as many characters from
160.Va input
161to
162.Va buf
163as will fit and
164.Tn NUL
165terminates the result.
166Because
167.Fn strncpy
168does
169.Em not
170guarantee to
171.Tn NUL
172terminate the string itself, this must be done explicitly.
173.Bd -literal -offset indent
174char buf[1024];
175
176(void)strncpy(buf, input, sizeof(buf) - 1);
177buf[sizeof(buf) - 1] = '\e0';
178.Ed
179.Pp
180This could be better achieved using
181.Xr strlcpy 3 ,
182as shown in the following example:
183.Pp
184.Dl "(void)strlcpy(buf, input, sizeof(buf));"
185.Pp
186Note that because
187.Xr strlcpy 3
188is not defined in any standards, it should
189only be used when portability is not a concern.
190.Sh SEE ALSO
191.Xr bcopy 3 ,
192.Xr memccpy 3 ,
193.Xr memcpy 3 ,
194.Xr memmove 3 ,
195.Xr strlcpy 3 ,
196.Xr wcscpy 3
197.Sh STANDARDS
198The
199.Fn strcpy
200and
201.Fn strncpy
202functions
203conform to
204.St -isoC .
205The
206.Fn stpcpy
207and
208.Fn stpncpy
209functions conform to
210.St -p1003.1-2008 .
211.Sh HISTORY
212The
213.Fn stpcpy
214function first appeared in
215.Fx 4.4 ,
216and
217.Fn stpncpy
218was added in
219.Fx 8.0 .
220.Sh SECURITY CONSIDERATIONS
221The
222.Fn strcpy
223function is easily misused in a manner which enables malicious users
224to arbitrarily change a running program's functionality through a
225buffer overflow attack.
226