crypt(3) - Switch SHA256/512 to the Linux implementation
[dragonfly.git] / lib / libc / string / strcpy.3
CommitLineData
984263bc
MD
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.
984263bc
MD
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
716024cd 33.\" $FreeBSD: src/lib/libc/string/strcpy.3,v 1.26 2007/01/09 00:28:12 imp Exp $
d0de9052 34.\" $DragonFly: src/lib/libc/string/strcpy.3,v 1.3 2005/08/05 22:35:10 swildner Exp $
984263bc 35.\"
d8ee3b5d 36.Dd January 20, 2012
984263bc
MD
37.Dt STRCPY 3
38.Os
39.Sh NAME
d0de9052
SW
40.Nm strcpy ,
41.Nm strncpy
984263bc
MD
42.Nd copy strings
43.Sh LIBRARY
44.Lb libc
45.Sh SYNOPSIS
46.In string.h
47.Ft char *
716024cd 48.Fn stpcpy "char *dst" "const char *src"
984263bc 49.Ft char *
d8ee3b5d
SG
50.Fn stpncpy "char * restrict dst" "const char * restrict src" "size_t len"
51.Ft char *
716024cd
PA
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"
984263bc
MD
55.Sh DESCRIPTION
56The
716024cd
PA
57.Fn stpcpy
58and
984263bc 59.Fn strcpy
716024cd
PA
60functions
61copy the string
984263bc
MD
62.Fa src
63to
64.Fa dst
65(including the terminating
66.Ql \e0
716024cd 67character.)
984263bc
MD
68.Pp
69The
d8ee3b5d
SG
70.Fn stpncpy
71and
984263bc 72.Fn strncpy
d8ee3b5d 73functions copy at most
984263bc
MD
74.Fa len
75characters from
76.Fa src
77into
716024cd
PA
78.Fa dst .
79If
984263bc
MD
80.Fa src
81is less than
82.Fa len
716024cd
PA
83characters long,
84the remainder of
984263bc 85.Fa dst
716024cd
PA
86is filled with
87.Ql \e0
88characters.
89Otherwise,
90.Fa dst
91is
92.Em not
93terminated.
984263bc
MD
94.Sh RETURN VALUES
95The
96.Fn strcpy
97and
98.Fn strncpy
99functions
100return
101.Fa dst .
716024cd
PA
102The
103.Fn stpcpy
d8ee3b5d
SG
104and
105.Fn stpncpy
106functions return a pointer to the terminating
716024cd
PA
107.Ql \e0
108character of
109.Fa dst .
d8ee3b5d
SG
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.
984263bc
MD
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
716024cd 148to the length argument.
984263bc
MD
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.
716024cd
PA
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 . )
984263bc
MD
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 .
716024cd
PA
205The
206.Fn stpcpy
d8ee3b5d
SG
207and
208.Fn stpncpy
209functions conform to
210.St -p1003.1-2008 .
716024cd
PA
211.Sh HISTORY
212The
213.Fn stpcpy
214function first appeared in
215.Fx 4.4 ,
d8ee3b5d
SG
216coming from 1998-vintage Linux
217and
218.Fn stpncpy
219first appeared in
220.Dx 2.13 .