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. 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.4.2.5 2001/12/14 18:33:59 ru Exp $
  38 .\" $DragonFly: src/lib/libc/string/strcpy.3,v 1.3 2005/08/05 22:35:10 swildner Exp $
  39 .\"
  40 .Dd August 9, 2001
  41 .Dt STRCPY 3
  42 .Os
  43 .Sh NAME
  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 .Fn strcpy "char *dst" "const char *src"
  53 .Ft char *
  54 .Fn strncpy "char *dst" "const char *src" "size_t len"
  55 .Sh DESCRIPTION
  56 The
  57 .Fn strcpy
  58 function
  59 copies the string
  60 .Fa src
  61 to
  62 .Fa dst
  63 (including the terminating
  64 .Ql \e0
  65 character).
  66 .Pp
  67 The
  68 .Fn strncpy
  69 function copies not more than
  70 .Fa len
  71 characters from
  72 .Fa src
  73 into
  74 .Fa dst ,
  75 appending
  76 .Ql \e0
  77 characters if
  78 .Fa src
  79 is less than
  80 .Fa len
  81 characters long, and
  82 .Em not
  83 terminating
  84 .Fa dst
  85 otherwise.
  86 .Sh RETURN VALUES
  87 The
  88 .Fn strcpy
  89 and
  90 .Fn strncpy
  91 functions
  92 return
  93 .Fa dst .
  94 .Sh EXAMPLES
  95 The following sets
  96 .Va chararray
  97 to
  98 .Dq Li abc\e0\e0\e0 :
  99 .Bd -literal -offset indent
 100 char chararray[6];
 101
 102 (void)strncpy(chararray, "abc", sizeof(chararray));
 103 .Ed
 104 .Pp
 105 The following sets
 106 .Va chararray
 107 to
 108 .Dq Li abcdef :
 109 .Bd -literal -offset indent
 110 char chararray[6];
 111
 112 (void)strncpy(chararray, "abcdefgh", sizeof(chararray));
 113 .Ed
 114 .Pp
 115 Note that it does
 116 .Em not
 117 .Tn NUL
 118 terminate
 119 .Va chararray
 120 because the length of the source string is greater than or equal
 121 to the length parameter.
 122 .Pp
 123 The following copies as many characters from
 124 .Va input
 125 to
 126 .Va buf
 127 as will fit and
 128 .Tn NUL
 129 terminates the result.
 130 Because
 131 .Fn strncpy
 132 does
 133 .Em not
 134 guarantee to
 135 .Tn NUL
 136 terminate the string itself, this must be done explicitly.
 137 .Bd -literal -offset indent
 138 char buf[1024];
 139
 140 (void)strncpy(buf, input, sizeof(buf) - 1);
 141 buf[sizeof(buf) - 1] = '\e0';
 142 .Ed
 143 .Pp
 144 This could be better achieved using
 145 .Xr strlcpy 3 ,
 146 as shown in the following example:
 147 .Pp
 148 .Dl "(void)strlcpy(buf, input, sizeof(buf));"
 149 .Pp
 150 Note that because
 151 .Xr strlcpy 3
 152 is not defined in any standards, it should
 153 only be used when portability is not a concern.
 154 .Sh SEE ALSO
 155 .Xr bcopy 3 ,
 156 .Xr memccpy 3 ,
 157 .Xr memcpy 3 ,
 158 .Xr memmove 3 ,
 159 .Xr strlcpy 3
 160 .Sh STANDARDS
 161 The
 162 .Fn strcpy
 163 and
 164 .Fn strncpy
 165 functions
 166 conform to
 167 .St -isoC .