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