string/FreeBSD/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 * 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.