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