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 .\"     from: @(#)strcpy.3      8.1 (Berkeley) 6/4/93
  33 .\"     $NetBSD: strcpy.3,v 1.19 2009/05/02 09:31:08 wiz Exp $
  34 .\"
  35 .Dd May 1, 2009
  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 stpcpy
  59 and
  60 .Fn strcpy
  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 stpncpy
  72 and
  73 .Fn strncpy
  74 functions copy at most
  75 .Fa len
  76 characters from
  77 .Fa src
  78 into
  79 .Fa dst .
  80 If
  81 .Fa src
  82 is less than
  83 .Fa len
  84 characters long,
  85 the remainder of
  86 .Fa dst
  87 is filled with
  88 .Ql \e0
  89 characters.
  90 Otherwise,
  91 .Fa dst
  92 is
  93 .Em not
  94 terminated.
  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[len]
 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 .Dv NUL Ns No -terminate
 144 .Va chararray
 145 because the length of the source string is greater than or equal
 146 to the length parameter.
 147 .Fn strncpy
 148 .Em only
 149 .Dv NUL Ns No -terminates
 150 the destination string when the length of the source
 151 string is less than the length parameter.
 152 .Pp
 153 The following copies as many characters from
 154 .Va input
 155 to
 156 .Va buf
 157 as will fit and
 158 .Dv NUL Ns No -terminates
 159 the result.
 160 Because
 161 .Fn strncpy
 162 does
 163 .Em not
 164 guarantee to
 165 .Dv NUL Ns No -terminate
 166 the string itself, this must be done explicitly.
 167 .Bd -literal -offset indent
 168 char buf[1024];
 169
 170 (void)strncpy(buf, input, sizeof(buf) - 1);
 171 buf[sizeof(buf) - 1] = '\e0';
 172 .Ed
 173 .Pp
 174 This could be better and more simply achieved using
 175 .Xr strlcpy 3 ,
 176 as shown in the following example:
 177 .Bd -literal -offset indent
 178 (void)strlcpy(buf, input, sizeof(buf));
 179 .Ed
 180 .Pp
 181 Note that because
 182 .Xr strlcpy 3
 183 is not defined in any standards, it should
 184 only be used when portability is not a concern.
 185 .Sh SEE ALSO
 186 .Xr bcopy 3 ,
 187 .Xr memccpy 3 ,
 188 .Xr memcpy 3 ,
 189 .Xr memmove 3 ,
 190 .Xr strlcpy 3 ,
 191 .Xr wcscpy 3
 192 .Sh STANDARDS
 193 The
 194 .Fn strcpy
 195 and
 196 .Fn strncpy
 197 functions
 198 conform to
 199 .St -isoC-99 .
 200 The
 201 .Fn stpcpy
 202 and
 203 .Fn stpncpy
 204 functions conform to
 205 .St -p1003.1-2008 .
 206 .Sh HISTORY
 207 The
 208 .Fn stpcpy
 209 and
 210 .Fn stpncpy
 211 functions first appeared in
 212 .Nx 6.0 .
 213 .Sh SECURITY CONSIDERATIONS
 214 The
 215 .Fn strcpy
 216 and
 217 .Fn stpcpy
 218 functions are easily misused in a manner which enables malicious users
 219 to arbitrarily change a running program's functionality through a
 220 buffer overflow attack.