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.\"     from: @(#)strcpy.3	8.1 (Berkeley) 6/4/93
33.\"	$NetBSD: strcpy.3,v 1.23 2015/04/01 20:18:17 riastradh Exp $
34.\"
35.Dd April 1, 2015
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).
69.Pp
70The
71.Fn stpncpy
72and
73.Fn strncpy
74functions copy at most
75.Fa len
76characters from
77.Fa src
78into
79.Fa dst .
80If
81.Fa src
82is less than
83.Fa len
84characters long,
85the remainder of
86.Fa dst
87is filled with
88.Ql \e0
89characters.
90Otherwise,
91.Fa dst
92is
93.Em not
94terminated.
95.Pp
96The strings
97.Fa src
98and
99.Fa dst
100may not overlap.
101.Sh RETURN VALUES
102The
103.Fn strcpy
104and
105.Fn strncpy
106functions
107return
108.Fa dst .
109The
110.Fn stpcpy
111and
112.Fn stpncpy
113functions return a pointer to the terminating
114.Ql \e0
115character of
116.Fa dst .
117If
118.Fn stpncpy
119does not terminate
120.Fa dst
121with a
122.Dv NUL
123character, it instead returns a pointer to
124.Li dst[len]
125(which does not necessarily refer to a valid memory location.)
126.Sh EXAMPLES
127The following sets
128.Va chararray
129to
130.Dq Li abc\e0\e0\e0 :
131.Bd -literal -offset indent
132char chararray[6];
133
134(void)strncpy(chararray, "abc", sizeof(chararray));
135.Ed
136.Pp
137The following sets
138.Va chararray
139to
140.Dq Li abcdef :
141.Bd -literal -offset indent
142char chararray[6];
143
144(void)strncpy(chararray, "abcdefgh", sizeof(chararray));
145.Ed
146.Pp
147Note that it does
148.Em not
149.Dv NUL Ns No -terminate
150.Va chararray
151because the length of the source string is greater than or equal
152to the length parameter.
153.Fn strncpy
154.Em only
155.Dv NUL Ns No -terminates
156the destination string when the length of the source
157string is less than the length parameter.
158.Pp
159The following copies as many characters from
160.Va input
161to
162.Va buf
163as will fit and
164.Dv NUL Ns No -terminates
165the result.
166Because
167.Fn strncpy
168does
169.Em not
170guarantee to
171.Dv NUL Ns No -terminate
172the 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 and more simply achieved using
181.Xr strlcpy 3 ,
182as shown in the following example:
183.Bd -literal -offset indent
184(void)strlcpy(buf, input, sizeof(buf));
185.Ed
186.Pp
187Note that because
188.Xr strlcpy 3
189is not defined in any standards, it should
190only be used when portability is not a concern.
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.Xr wcscpy 3
198.Sh STANDARDS
199The
200.Fn strcpy
201and
202.Fn strncpy
203functions
204conform to
205.St -isoC-99 .
206The
207.Fn stpcpy
208and
209.Fn stpncpy
210functions conform to
211.St -p1003.1-2008 .
212.Sh HISTORY
213The
214.Fn stpcpy
215and
216.Fn stpncpy
217functions first appeared in
218.Nx 6.0 .
219.Sh SECURITY CONSIDERATIONS
220The
221.Fn strcpy
222and
223.Fn stpcpy
224functions are easily misused in a manner which enables malicious users
225to arbitrarily change a running program's functionality through a
226buffer overflow attack.
227