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. 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 stpcpy ,
  44 .Nm strcpy ,
  45 .Nm strncpy
  46 .Nd copy strings
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In string.h
  51 .Ft char *
  52 .Fo stpcpy
  53 .Fa "char *s1"
  54 .Fa "const char *s2"
  55 .Fc
  56 .Ft char *
  57 .Fo strcpy
  58 .Fa "char *restrict s1"
  59 .Fa "const char *restrict s2"
  60 .Fc
  61 .Ft char *
  62 .Fo strncpy
  63 .Fa "char *restrict s1"
  64 .Fa "const char *restrict s2"
  65 .Fa "size_t n"
  66 .Fc
  67 .Sh DESCRIPTION
  68 The
  69 .Fn stpcpy
  70 and
  71 .Fn strcpy
  72 functions
  73 copy the string
  74 .Fa s2
  75 to
  76 .Fa s1
  77 (including the terminating
  78 .Ql \e0
  79 character).
  80 .Pp
  81 The
  82 .Fn strncpy
  83 function copies at most
  84 .Fa n
  85 characters from
  86 .Fa s2
  87 into
  88 .Fa s1 .
  89 If
  90 .Fa s2
  91 is less than
  92 .Fa n
  93 characters long,
  94 the remainder of
  95 .Fa s1
  96 is filled with
  97 .Ql \e0
  98 characters.
  99 Otherwise,
 100 .Fa s1
 101 is
 102 .Em not
 103 terminated.
 104 .Pp
 105 The source and destination strings should not overlap, as the
 106 behavior is undefined.
 107 .Sh RETURN VALUES
 108 The
 109 .Fn strcpy
 110 and
 111 .Fn strncpy
 112 functions
 113 return
 114 .Fa s1 .
 115 The
 116 .Fn stpcpy
 117 function returns a pointer to the terminating
 118 .Ql \e0
 119 character of
 120 .Fa s1 .
 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 function is an MS-DOS and GNUism.
 208 The
 209 .Fn stpcpy
 210 function
 211 conforms to no standard.
 212 .Sh HISTORY
 213 The
 214 .Fn stpcpy
 215 function first appeared in
 216 .Fx 4.4 ,
 217 coming from 1998-vintage Linux.