string/FreeBSD/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. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)strcpy.3    8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/string/strcpy.3,v 1.24 2002/12/19 09:40:24 ru Exp $
  38 .\"
  39 .Dd August 9, 2001
  40 .Dt STRCPY 3
  41 .Os
  42 .Sh NAME
  43 .Nm strcpy , strncpy
  44 .Nd copy strings
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In string.h
  49 .Ft char *
  50 .Fn stpcpy "char *dst" "const char *src"
  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 strncpy
  71 function copies at most
  72 .Fa len
  73 characters from
  74 .Fa src
  75 into
  76 .Fa dst .
  77 If
  78 .Fa src
  79 is less than
  80 .Fa len
  81 characters long,
  82 the remainder of
  83 .Fa dst
  84 is filled with
  85 .Ql \e0
  86 characters.
  87 Otherwise,
  88 .Fa dst
  89 is
  90 .Em not
  91 terminated.
  92 .Sh RETURN VALUES
  93 The
  94 .Fn strcpy
  95 and
  96 .Fn strncpy
  97 functions
  98 return
  99 .Fa dst .
 100 The
 101 .Fn stpcpy
 102 function returns a pointer to the terminating
 103 .Ql \e0
 104 character of
 105 .Fa dst .
 106 .Sh EXAMPLES
 107 The following sets
 108 .Va chararray
 109 to
 110 .Dq Li abc\e0\e0\e0 :
 111 .Bd -literal -offset indent
 112 char chararray[6];
 113
 114 (void)strncpy(chararray, "abc", sizeof(chararray));
 115 .Ed
 116 .Pp
 117 The following sets
 118 .Va chararray
 119 to
 120 .Dq Li abcdef :
 121 .Bd -literal -offset indent
 122 char chararray[6];
 123
 124 (void)strncpy(chararray, "abcdefgh", sizeof(chararray));
 125 .Ed
 126 .Pp
 127 Note that it does
 128 .Em not
 129 .Tn NUL
 130 terminate
 131 .Va chararray
 132 because the length of the source string is greater than or equal
 133 to the length argument.
 134 .Pp
 135 The following copies as many characters from
 136 .Va input
 137 to
 138 .Va buf
 139 as will fit and
 140 .Tn NUL
 141 terminates the result.
 142 Because
 143 .Fn strncpy
 144 does
 145 .Em not
 146 guarantee to
 147 .Tn NUL
 148 terminate the string itself, this must be done explicitly.
 149 .Bd -literal -offset indent
 150 char buf[1024];
 151
 152 (void)strncpy(buf, input, sizeof(buf) - 1);
 153 buf[sizeof(buf) - 1] = '\e0';
 154 .Ed
 155 .Pp
 156 This could be better achieved using
 157 .Xr strlcpy 3 ,
 158 as shown in the following example:
 159 .Pp
 160 .Dl "(void)strlcpy(buf, input, sizeof(buf));"
 161 .Pp
 162 Note that because
 163 .Xr strlcpy 3
 164 is not defined in any standards, it should
 165 only be used when portability is not a concern.
 166 .Sh SECURITY CONSIDERATIONS
 167 The
 168 .Fn strcpy
 169 function is easily misused in a manner which enables malicious users
 170 to arbitrarily change a running program's functionality through a
 171 buffer overflow attack.
 172 (See
 173 the FSA
 174 and
 175 .Sx EXAMPLES . )
 176 .Sh SEE ALSO
 177 .Xr bcopy 3 ,
 178 .Xr memccpy 3 ,
 179 .Xr memcpy 3 ,
 180 .Xr memmove 3 ,
 181 .Xr strlcpy 3
 182 .Rs
 183 .%T "The FreeBSD Security Architecture"
 184 .Re
 185 (See
 186 .Pa "/usr/share/doc/{to be decided}" . )
 187 .Sh STANDARDS
 188 The
 189 .Fn strcpy
 190 and
 191 .Fn strncpy
 192 functions
 193 conform to
 194 .St -isoC .
 195 The
 196 .Fn stpcpy
 197 function is an MS-DOS and GNUism.
 198 The
 199 .Fn stpcpy
 200 function
 201 conforms to no standard.
 202 .Sh HISTORY
 203 The
 204 .Fn stpcpy
 205 function first appeared in
 206 .Fx 4.4 ,
 207 coming from 1998-vintage Linux.