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 .Sh RETURN VALUES
 105 The
 106 .Fn strcpy
 107 and
 108 .Fn strncpy
 109 functions
 110 return
 111 .Fa s1 .
 112 The
 113 .Fn stpcpy
 114 function returns a pointer to the terminating
 115 .Ql \e0
 116 character of
 117 .Fa s1 .
 118 .Sh EXAMPLES
 119 The following sets
 120 .Va chararray
 121 to
 122 .Dq Li abc\e0\e0\e0 :
 123 .Bd -literal -offset indent
 124 char chararray[6];
 125
 126 (void)strncpy(chararray, "abc", sizeof(chararray));
 127 .Ed
 128 .Pp
 129 The following sets
 130 .Va chararray
 131 to
 132 .Dq Li abcdef :
 133 .Bd -literal -offset indent
 134 char chararray[6];
 135
 136 (void)strncpy(chararray, "abcdefgh", sizeof(chararray));
 137 .Ed
 138 .Pp
 139 Note that it does
 140 .Em not
 141 .Tn NUL
 142 terminate
 143 .Va chararray ,
 144 because the length of the source string is greater than or equal
 145 to the length argument.
 146 .Pp
 147 The following copies as many characters from
 148 .Va input
 149 to
 150 .Va buf
 151 as will fit and
 152 .Tn NUL
 153 terminates the result.
 154 Because
 155 .Fn strncpy
 156 does
 157 .Em not
 158 guarantee to
 159 .Tn NUL
 160 terminate the string itself, this must be done explicitly.
 161 .Bd -literal -offset indent
 162 char buf[1024];
 163
 164 (void)strncpy(buf, input, sizeof(buf) - 1);
 165 buf[sizeof(buf) - 1] = '\e0';
 166 .Ed
 167 .Pp
 168 This could be better achieved using
 169 .Xr strlcpy 3 ,
 170 as shown in the following example:
 171 .Pp
 172 .Dl "(void)strlcpy(buf, input, sizeof(buf));"
 173 .Pp
 174 Note that, because
 175 .Xr strlcpy 3
 176 is not defined in any standards, it should
 177 only be used when portability is not a concern.
 178 .Sh SECURITY CONSIDERATIONS
 179 The
 180 .Fn strcpy
 181 function is easily misused in a manner which enables malicious users
 182 to arbitrarily change a running program's functionality through a
 183 buffer overflow attack.
 184 (See
 185 the FSA
 186 and
 187 .Sx EXAMPLES . )
 188 .Sh SEE ALSO
 189 .Xr bcopy 3 ,
 190 .Xr memccpy 3 ,
 191 .Xr memcpy 3 ,
 192 .Xr memmove 3 ,
 193 .Xr strlcpy 3
 194 .Sh STANDARDS
 195 The
 196 .Fn strcpy
 197 and
 198 .Fn strncpy
 199 functions
 200 conform to
 201 .St -isoC .
 202 The
 203 .Fn stpcpy
 204 function is an MS-DOS and GNUism.
 205 The
 206 .Fn stpcpy
 207 function
 208 conforms to no standard.
 209 .Sh HISTORY
 210 The
 211 .Fn stpcpy
 212 function first appeared in
 213 .Fx 4.4 ,
 214 coming from 1998-vintage Linux.