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