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  .\"     @(#)strcpy.3	8.1 (Berkeley) 6/4/93
 33  .\" $FreeBSD$
 34  .\"
 35  .Dd February 28, 2009
 36  .Dt STRCPY 3
 37  .Os
 38  .Sh NAME
 39  .Nm stpcpy, stpncpy, strcpy , strncpy
 40  .Nd copy strings
 41  .Sh LIBRARY
 42  .Lb libc
 43  .Sh SYNOPSIS
 44  .In string.h
 45  .Ft char *
 46  .Fn stpcpy "char * dst" "const char * src"
 47  .Ft char *
 48  .Fn stpncpy "char * dst" "const char * src" "size_t len"
 49  .Ft char *
 50  .Fn strcpy "char * dst" "const char * src"
 51  .Ft char *
 52  .Fn strncpy "char * dst" "const char * 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 stpncpy
 69  and
 70  .Fn strncpy
 71  functions copy at most
 72  .Fa len
 73  characters from
 74  .Fa src
 75  into
 76  .Fa dst .
 77  If
 78  .Fa src
 79  is less than
 80  .Fa len
 81  characters long,
 82  the remainder of
 83  .Fa dst
 84  is filled with
 85  .Ql \e0
 86  characters.
 87  Otherwise,
 88  .Fa dst
 89  is
 90  .Em not
 91  terminated.
 92  .Pp
 93  The source and destination strings should not overlap, as the
 94  behavior is undefined.
 95  .Sh RETURN VALUES
 96  The
 97  .Fn strcpy
 98  and
 99  .Fn strncpy
100  functions
101  return
102  .Fa dst .
103  The
104  .Fn stpcpy
105  and
106  .Fn stpncpy
107  functions return a pointer to the terminating
108  .Ql \e0
109  character of
110  .Fa dst .
111  If
112  .Fn stpncpy
113  does not terminate
114  .Fa dst
115  with a
116  .Dv NUL
117  character, it instead returns a pointer to
118  .Li dst[n]
119  (which does not necessarily refer to a valid memory location.)
120  .Sh EXAMPLES
121  The following sets
122  .Va chararray
123  to
124  .Dq Li abc\e0\e0\e0 :
125  .Bd -literal -offset indent
126  char chararray[6];
127  
128  (void)strncpy(chararray, "abc", sizeof(chararray));
129  .Ed
130  .Pp
131  The following sets
132  .Va chararray
133  to
134  .Dq Li abcdef :
135  .Bd -literal -offset indent
136  char chararray[6];
137  
138  (void)strncpy(chararray, "abcdefgh", sizeof(chararray));
139  .Ed
140  .Pp
141  Note that it does
142  .Em not
143  .Tn NUL
144  terminate
145  .Va chararray
146  because the length of the source string is greater than or equal
147  to the length argument.
148  .Pp
149  The following copies as many characters from
150  .Va input
151  to
152  .Va buf
153  as will fit and
154  .Tn NUL
155  terminates the result.
156  Because
157  .Fn strncpy
158  does
159  .Em not
160  guarantee to
161  .Tn NUL
162  terminate the string itself, this must be done explicitly.
163  .Bd -literal -offset indent
164  char buf[1024];
165  
166  (void)strncpy(buf, input, sizeof(buf) - 1);
167  buf[sizeof(buf) - 1] = '\e0';
168  .Ed
169  .Pp
170  This could be better achieved using
171  .Xr strlcpy 3 ,
172  as shown in the following example:
173  .Pp
174  .Dl "(void)strlcpy(buf, input, sizeof(buf));"
175  .Pp
176  Note that because
177  .Xr strlcpy 3
178  is not defined in any standards, it should
179  only be used when portability is not a concern.
180  .Sh SEE ALSO
181  .Xr bcopy 3 ,
182  .Xr memccpy 3 ,
183  .Xr memcpy 3 ,
184  .Xr memmove 3 ,
185  .Xr strlcpy 3 ,
186  .Xr wcscpy 3
187  .Sh STANDARDS
188  The
189  .Fn strcpy
190  and
191  .Fn strncpy
192  functions
193  conform to
194  .St -isoC .
195  The
196  .Fn stpcpy
197  and
198  .Fn stpncpy
199  functions conform to
200  .St -p1003.1-2008 .
201  .Sh HISTORY
202  The
203  .Fn stpcpy
204  function first appeared in
205  .Fx 4.4 ,
206  and
207  .Fn stpncpy
208  was added in
209  .Fx 8.0 .
210  .Sh SECURITY CONSIDERATIONS
211  The
212  .Fn strcpy
213  function is easily misused in a manner which enables malicious users
214  to arbitrarily change a running program's functionality through a
215  buffer overflow attack.