xref: /dragonfly/lib/libc/string/strcpy.3 (revision 52f9f0d9) 
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.\" 4. 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: src/lib/libc/string/strcpy.3,v 1.26 2007/01/09 00:28:12 imp Exp $
34.\" $DragonFly: src/lib/libc/string/strcpy.3,v 1.3 2005/08/05 22:35:10 swildner Exp $
35.\"
36.Dd January 20, 2012
37.Dt STRCPY 3
38.Os
39.Sh NAME
40.Nm strcpy ,
41.Nm strncpy
42.Nd copy strings
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In string.h
47.Ft char *
48.Fn stpcpy "char *dst" "const char *src"
49.Ft char *
50.Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len"
51.Ft char *
52.Fn strcpy "char * restrict dst" "const char * restrict src"
53.Ft char *
54.Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
55.Sh DESCRIPTION
56The
57.Fn stpcpy
58and
59.Fn strcpy
60functions
61copy the string
62.Fa src
63to
64.Fa dst
65(including the terminating
66.Ql \e0
67character.)
68.Pp
69The
70.Fn stpncpy
71and
72.Fn strncpy
73functions copy at most
74.Fa len
75characters from
76.Fa src
77into
78.Fa dst .
79If
80.Fa src
81is less than
82.Fa len
83characters long,
84the remainder of
85.Fa dst
86is filled with
87.Ql \e0
88characters.
89Otherwise,
90.Fa dst
91is
92.Em not
93terminated.
94.Sh RETURN VALUES
95The
96.Fn strcpy
97and
98.Fn strncpy
99functions
100return
101.Fa dst .
102The
103.Fn stpcpy
104and
105.Fn stpncpy
106functions return a pointer to the terminating
107.Ql \e0
108character of
109.Fa dst .
110If
111.Fn stpncpy
112does not null-terminate
113.Fa dst
114because the length of
115.Fa src
116was greater than
117.Fa len ,
118then it returns a pointer to
119.Li dst[len] ,
120which may not be valid.
121.Sh EXAMPLES
122The following sets
123.Va chararray
124to
125.Dq Li abc\e0\e0\e0 :
126.Bd -literal -offset indent
127char chararray[6];
128
129(void)strncpy(chararray, "abc", sizeof(chararray));
130.Ed
131.Pp
132The following sets
133.Va chararray
134to
135.Dq Li abcdef :
136.Bd -literal -offset indent
137char chararray[6];
138
139(void)strncpy(chararray, "abcdefgh", sizeof(chararray));
140.Ed
141.Pp
142Note that it does
143.Em not
144.Tn NUL
145terminate
146.Va chararray
147because the length of the source string is greater than or equal
148to the length argument.
149.Pp
150The following copies as many characters from
151.Va input
152to
153.Va buf
154as will fit and
155.Tn NUL
156terminates the result.
157Because
158.Fn strncpy
159does
160.Em not
161guarantee to
162.Tn NUL
163terminate the string itself, this must be done explicitly.
164.Bd -literal -offset indent
165char buf[1024];
166
167(void)strncpy(buf, input, sizeof(buf) - 1);
168buf[sizeof(buf) - 1] = '\e0';
169.Ed
170.Pp
171This could be better achieved using
172.Xr strlcpy 3 ,
173as shown in the following example:
174.Pp
175.Dl "(void)strlcpy(buf, input, sizeof(buf));"
176.Pp
177Note that because
178.Xr strlcpy 3
179is not defined in any standards, it should
180only be used when portability is not a concern.
181.Sh SECURITY CONSIDERATIONS
182The
183.Fn strcpy
184function is easily misused in a manner which enables malicious users
185to arbitrarily change a running program's functionality through a
186buffer overflow attack.
187(See
188the FSA
189and
190.Sx EXAMPLES . )
191.Sh SEE ALSO
192.Xr bcopy 3 ,
193.Xr memccpy 3 ,
194.Xr memcpy 3 ,
195.Xr memmove 3 ,
196.Xr strlcpy 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 ,
216coming from 1998-vintage Linux
217and
218.Fn stpncpy
219first appeared in
220.Dx 2.13 .
221