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.28 2009/04/07 13:42:53 trasz Exp $
  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 .Fo stpcpy
  47 .Fa "char *s1"
  48 .Fa "const char *s2"
  49 .Fc
  50 .Ft char *
  51 .Fo stpncpy
  52 .Fa "char *restrict s1"
  53 .Fa "const char *restrict s2"
  54 .Fa "size_t n"
  55 .Fc
  56 .Ft char *
  57 .Fo strcpy
  58 .Fa "char *restrict s1"
  59 .Fa "const char *restrict s2"
  60 .Fc
  61 .Ft char *
  62 .Fo strncpy
  63 .Fa "char *restrict s1"
  64 .Fa "const char *restrict s2"
  65 .Fa "size_t n"
  66 .Fc
  67 .Sh DESCRIPTION
  68 The
  69 .Fn stpcpy
  70 and
  71 .Fn strcpy
  72 functions
  73 copy the string
  74 .Fa s2
  75 to
  76 .Fa s1
  77 (including the terminating
  78 .Ql \e0
  79 character).
  80 .Pp
  81 The
  82 .Fn stpncpy
  83 and
  84 .Fn strncpy
  85 functions copy at most
  86 .Fa n
  87 characters from
  88 .Fa s2
  89 into
  90 .Fa s1 .
  91 If
  92 .Fa s2
  93 is less than
  94 .Fa n
  95 characters long,
  96 the remainder of
  97 .Fa s1
  98 is filled with
  99 .Ql \e0
 100 characters.
 101 Otherwise,
 102 .Fa s1
 103 is
 104 .Em not
 105 terminated.
 106 .Pp
 107 The source and destination strings should not overlap, as the
 108 behavior is undefined.
 109 .Sh RETURN VALUES
 110 The
 111 .Fn strcpy
 112 and
 113 .Fn strncpy
 114 functions
 115 return
 116 .Fa s1 .
 117 The
 118 .Fn stpcpy
 119 and
 120 .Fn stpncpy
 121 functions return a pointer to the terminating
 122 .Ql \e0
 123 character of
 124 .Fa s1 .
 125 If
 126 .Fn stpncpy
 127 does not terminate
 128 .Fa s1
 129 with a
 130 .Dv NUL
 131 character, it instead returns a pointer to
 132 .Li s1[n]
 133 (which does not necessarily refer to a valid memory location.)
 134 .Sh EXAMPLES
 135 The following sets
 136 .Va chararray
 137 to
 138 .Dq Li abc\e0\e0\e0 :
 139 .Bd -literal -offset indent
 140 char chararray[6];
 141
 142 (void)strncpy(chararray, "abc", sizeof(chararray));
 143 .Ed
 144 .Pp
 145 The following sets
 146 .Va chararray
 147 to
 148 .Dq Li abcdef :
 149 .Bd -literal -offset indent
 150 char chararray[6];
 151
 152 (void)strncpy(chararray, "abcdefgh", sizeof(chararray));
 153 .Ed
 154 .Pp
 155 Note that it does
 156 .Em not
 157 .Tn NUL
 158 terminate
 159 .Va chararray ,
 160 because the length of the source string is greater than or equal
 161 to the length argument.
 162 .Pp
 163 The following copies as many characters from
 164 .Va input
 165 to
 166 .Va buf
 167 as will fit and
 168 .Tn NUL
 169 terminates the result.
 170 Because
 171 .Fn strncpy
 172 does
 173 .Em not
 174 guarantee to
 175 .Tn NUL
 176 terminate the string itself, this must be done explicitly.
 177 .Bd -literal -offset indent
 178 char buf[1024];
 179
 180 (void)strncpy(buf, input, sizeof(buf) - 1);
 181 buf[sizeof(buf) - 1] = '\e0';
 182 .Ed
 183 .Pp
 184 This could be better achieved using
 185 .Xr strlcpy 3 ,
 186 as shown in the following example:
 187 .Pp
 188 .Dl "(void)strlcpy(buf, input, sizeof(buf));"
 189 .Sh SECURITY CONSIDERATIONS
 190 The
 191 .Fn strcpy ,
 192 .Fn strncpy ,
 193 .Fn stpcpy ,
 194 and
 195 .Fn stpncpy
 196 functions are easily misused in a manner which enables malicious users
 197 to arbitrarily change a running program's functionality through a
 198 buffer overflow attack.
 199 (See
 200 the FSA
 201 and
 202 .Sx EXAMPLES . )
 203 .Pp
 204 It is recommended that
 205 .Xr strlcpy 3
 206 be used instead as a way to avoid such problems.
 207 .Xr strlcpy 3
 208 is not defined in any standards, but it has been adopted by most major libc implementations.
 209 .Sh SEE ALSO
 210 .Xr bcopy 3 ,
 211 .Xr memccpy 3 ,
 212 .Xr memcpy 3 ,
 213 .Xr memmove 3 ,
 214 .Xr strlcpy 3 ,
 215 .Xr wcscpy 3
 216 .Sh STANDARDS
 217 The
 218 .Fn strcpy
 219 and
 220 .Fn strncpy
 221 functions
 222 conform to
 223 .St -isoC .
 224 The
 225 .Fn stpcpy
 226 and
 227 .Fn stpncpy
 228 functions conform to
 229 .St -p1003.1-2008 .
 230 .Sh HISTORY
 231 The
 232 .Fn stpcpy
 233 function first appeared in
 234 .Fx 4.4 ,
 235 and
 236 .Fn stpncpy
 237 was added in
 238 .Fx 8.0 .