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