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 .\" 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$
  34 .\"
  35 .Dd August 9, 2001
  36 .Dt STRCPY 3
  37 .Os
  38 .Sh NAME
  39 .Nm 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 strcpy "char * restrict dst" "const char * restrict src"
  49 .Ft char *
  50 .Fn strncpy "char * restrict dst" "const char * restrict src" "size_t len"
  51 .Sh DESCRIPTION
  52 The
  53 .Fn stpcpy
  54 and
  55 .Fn strcpy
  56 functions
  57 copy the string
  58 .Fa src
  59 to
  60 .Fa dst
  61 (including the terminating
  62 .Ql \e0
  63 character.)
  64 .Pp
  65 The
  66 .Fn strncpy
  67 function copies at most
  68 .Fa len
  69 characters from
  70 .Fa src
  71 into
  72 .Fa dst .
  73 If
  74 .Fa src
  75 is less than
  76 .Fa len
  77 characters long,
  78 the remainder of
  79 .Fa dst
  80 is filled with
  81 .Ql \e0
  82 characters.
  83 Otherwise,
  84 .Fa dst
  85 is
  86 .Em not
  87 terminated.
  88 .Sh RETURN VALUES
  89 The
  90 .Fn strcpy
  91 and
  92 .Fn strncpy
  93 functions
  94 return
  95 .Fa dst .
  96 The
  97 .Fn stpcpy
  98 function returns a pointer to the terminating
  99 .Ql \e0
 100 character of
 101 .Fa dst .
 102 .Sh EXAMPLES
 103 The following sets
 104 .Va chararray
 105 to
 106 .Dq Li abc\e0\e0\e0 :
 107 .Bd -literal -offset indent
 108 char chararray[6];
 109
 110 (void)strncpy(chararray, "abc", sizeof(chararray));
 111 .Ed
 112 .Pp
 113 The following sets
 114 .Va chararray
 115 to
 116 .Dq Li abcdef :
 117 .Bd -literal -offset indent
 118 char chararray[6];
 119
 120 (void)strncpy(chararray, "abcdefgh", sizeof(chararray));
 121 .Ed
 122 .Pp
 123 Note that it does
 124 .Em not
 125 .Tn NUL
 126 terminate
 127 .Va chararray
 128 because the length of the source string is greater than or equal
 129 to the length argument.
 130 .Pp
 131 The following copies as many characters from
 132 .Va input
 133 to
 134 .Va buf
 135 as will fit and
 136 .Tn NUL
 137 terminates the result.
 138 Because
 139 .Fn strncpy
 140 does
 141 .Em not
 142 guarantee to
 143 .Tn NUL
 144 terminate the string itself, this must be done explicitly.
 145 .Bd -literal -offset indent
 146 char buf[1024];
 147
 148 (void)strncpy(buf, input, sizeof(buf) - 1);
 149 buf[sizeof(buf) - 1] = '\e0';
 150 .Ed
 151 .Pp
 152 This could be better achieved using
 153 .Xr strlcpy 3 ,
 154 as shown in the following example:
 155 .Pp
 156 .Dl "(void)strlcpy(buf, input, sizeof(buf));"
 157 .Pp
 158 Note that because
 159 .Xr strlcpy 3
 160 is not defined in any standards, it should
 161 only be used when portability is not a concern.
 162 .Sh SECURITY CONSIDERATIONS
 163 The
 164 .Fn strcpy
 165 function is easily misused in a manner which enables malicious users
 166 to arbitrarily change a running program's functionality through a
 167 buffer overflow attack.
 168 (See
 169 the FSA
 170 and
 171 .Sx EXAMPLES . )
 172 .Sh SEE ALSO
 173 .Xr bcopy 3 ,
 174 .Xr memccpy 3 ,
 175 .Xr memcpy 3 ,
 176 .Xr memmove 3 ,
 177 .Xr strlcpy 3
 178 .Sh STANDARDS
 179 The
 180 .Fn strcpy
 181 and
 182 .Fn strncpy
 183 functions
 184 conform to
 185 .St -isoC .
 186 The
 187 .Fn stpcpy
 188 function is an MS-DOS and GNUism.
 189 The
 190 .Fn stpcpy
 191 function
 192 conforms to no standard.
 193 .Sh HISTORY
 194 The
 195 .Fn stpcpy
 196 function first appeared in
 197 .Fx 4.4 ,
 198 coming from 1998-vintage Linux.