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