xref: /dragonfly/lib/libc/string/strcpy.3 (revision 9ddb8543) 
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 August 9, 2001
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 strcpy "char * restrict dst" "const char * restrict src"
51.Ft char *
52.Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
53.Sh DESCRIPTION
54The
55.Fn stpcpy
56and
57.Fn strcpy
58functions
59copy the string
60.Fa src
61to
62.Fa dst
63(including the terminating
64.Ql \e0
65character.)
66.Pp
67The
68.Fn strncpy
69function copies at most
70.Fa len
71characters from
72.Fa src
73into
74.Fa dst .
75If
76.Fa src
77is less than
78.Fa len
79characters long,
80the remainder of
81.Fa dst
82is filled with
83.Ql \e0
84characters.
85Otherwise,
86.Fa dst
87is
88.Em not
89terminated.
90.Sh RETURN VALUES
91The
92.Fn strcpy
93and
94.Fn strncpy
95functions
96return
97.Fa dst .
98The
99.Fn stpcpy
100function returns a pointer to the terminating
101.Ql \e0
102character of
103.Fa dst .
104.Sh EXAMPLES
105The following sets
106.Va chararray
107to
108.Dq Li abc\e0\e0\e0 :
109.Bd -literal -offset indent
110char chararray[6];
111
112(void)strncpy(chararray, "abc", sizeof(chararray));
113.Ed
114.Pp
115The following sets
116.Va chararray
117to
118.Dq Li abcdef :
119.Bd -literal -offset indent
120char chararray[6];
121
122(void)strncpy(chararray, "abcdefgh", sizeof(chararray));
123.Ed
124.Pp
125Note that it does
126.Em not
127.Tn NUL
128terminate
129.Va chararray
130because the length of the source string is greater than or equal
131to the length argument.
132.Pp
133The following copies as many characters from
134.Va input
135to
136.Va buf
137as will fit and
138.Tn NUL
139terminates the result.
140Because
141.Fn strncpy
142does
143.Em not
144guarantee to
145.Tn NUL
146terminate the string itself, this must be done explicitly.
147.Bd -literal -offset indent
148char buf[1024];
149
150(void)strncpy(buf, input, sizeof(buf) - 1);
151buf[sizeof(buf) - 1] = '\e0';
152.Ed
153.Pp
154This could be better achieved using
155.Xr strlcpy 3 ,
156as shown in the following example:
157.Pp
158.Dl "(void)strlcpy(buf, input, sizeof(buf));"
159.Pp
160Note that because
161.Xr strlcpy 3
162is not defined in any standards, it should
163only be used when portability is not a concern.
164.Sh SECURITY CONSIDERATIONS
165The
166.Fn strcpy
167function is easily misused in a manner which enables malicious users
168to arbitrarily change a running program's functionality through a
169buffer overflow attack.
170(See
171the FSA
172and
173.Sx EXAMPLES . )
174.Sh SEE ALSO
175.Xr bcopy 3 ,
176.Xr memccpy 3 ,
177.Xr memcpy 3 ,
178.Xr memmove 3 ,
179.Xr strlcpy 3
180.Sh STANDARDS
181The
182.Fn strcpy
183and
184.Fn strncpy
185functions
186conform to
187.St -isoC .
188The
189.Fn stpcpy
190function is an MS-DOS and GNUism.
191The
192.Fn stpcpy
193function
194conforms to no standard.
195.Sh HISTORY
196The
197.Fn stpcpy
198function first appeared in
199.Fx 4.4 ,
200coming from 1998-vintage Linux.
201