string/FreeBSD/strlcpy.3

   1 .\" $OpenBSD: strlcpy.3,v 1.19 2007/05/31 19:19:32 jmc Exp $
   2 .\"
   3 .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  19 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
  20 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  21 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  22 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  23 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  24 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  25 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  26 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/lib/libc/string/strlcpy.3,v 1.16 2009/04/07 13:42:53 trasz Exp $
  29 .\"
  30 .Dd June 22, 1998
  31 .Dt STRLCPY 3
  32 .Os
  33 .Sh NAME
  34 .Nm strlcpy ,
  35 .Nm strlcat
  36 .Nd size-bounded string copying and concatenation
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In string.h
  41 .Ft size_t
  42 .Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t size"
  43 .Ft size_t
  44 .Fn strlcat "char * restrict dst" "const char * restrict src" "size_t size"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn strlcpy
  48 and
  49 .Fn strlcat
  50 functions copy and concatenate strings respectively.
  51 They are designed
  52 to be safer, more consistent, and less error prone replacements for
  53 .Xr strncpy 3
  54 and
  55 .Xr strncat 3 .
  56 Unlike those functions,
  57 .Fn strlcpy
  58 and
  59 .Fn strlcat
  60 take the full size of the buffer (not just the length) and guarantee to
  61 NUL-terminate the result (as long as
  62 .Fa size
  63 is larger than 0 or, in the case of
  64 .Fn strlcat ,
  65 as long as there is at least one byte free in
  66 .Fa dst ) .
  67 Note that a byte for the NUL should be included in
  68 .Fa size .
  69 Also note that
  70 .Fn strlcpy
  71 and
  72 .Fn strlcat
  73 only operate on true
  74 .Dq C
  75 strings.
  76 This means that for
  77 .Fn strlcpy
  78 .Fa src
  79 must be NUL-terminated and for
  80 .Fn strlcat
  81 both
  82 .Fa src
  83 and
  84 .Fa dst
  85 must be NUL-terminated.
  86 .Pp
  87 The
  88 .Fn strlcpy
  89 function copies up to
  90 .Fa size
  91 - 1 characters from the NUL-terminated string
  92 .Fa src
  93 to
  94 .Fa dst ,
  95 NUL-terminating the result.
  96 .Pp
  97 The
  98 .Fn strlcat
  99 function appends the NUL-terminated string
 100 .Fa src
 101 to the end of
 102 .Fa dst .
 103 It will append at most
 104 .Fa size
 105 - strlen(dst) - 1 bytes, NUL-terminating the result.
 106 .Pp
 107 The source and destination strings should not overlap, as the
 108 behavior is undefined.
 109 .Sh RETURN VALUES
 110 The
 111 .Fn strlcpy
 112 and
 113 .Fn strlcat
 114 functions return the total length of the string they tried to
 115 create.
 116 For
 117 .Fn strlcpy
 118 that means the length of
 119 .Fa src .
 120 For
 121 .Fn strlcat
 122 that means the initial length of
 123 .Fa dst
 124 plus
 125 the length of
 126 .Fa src .
 127 While this may seem somewhat confusing, it was done to make
 128 truncation detection simple.
 129 .Pp
 130 Note however, that if
 131 .Fn strlcat
 132 traverses
 133 .Fa size
 134 characters without finding a NUL, the length of the string is considered
 135 to be
 136 .Fa size
 137 and the destination string will not be NUL-terminated (since there was
 138 no space for the NUL).
 139 This keeps
 140 .Fn strlcat
 141 from running off the end of a string.
 142 In practice this should not happen (as it means that either
 143 .Fa size
 144 is incorrect or that
 145 .Fa dst
 146 is not a proper
 147 .Dq C
 148 string).
 149 The check exists to prevent potential security problems in incorrect code.
 150 .Sh EXAMPLES
 151 The following code fragment illustrates the simple case:
 152 .Bd -literal -offset indent
 153 char *s, *p, buf[BUFSIZ];
 154
 155 \&...
 156
 157 (void)strlcpy(buf, s, sizeof(buf));
 158 (void)strlcat(buf, p, sizeof(buf));
 159 .Ed
 160 .Pp
 161 To detect truncation, perhaps while building a pathname, something
 162 like the following might be used:
 163 .Bd -literal -offset indent
 164 char *dir, *file, pname[MAXPATHLEN];
 165
 166 \&...
 167
 168 if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
 169         goto toolong;
 170 if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
 171         goto toolong;
 172 .Ed
 173 .Pp
 174 Since it is known how many characters were copied the first time, things
 175 can be sped up a bit by using a copy instead of an append
 176 .Bd -literal -offset indent
 177 char *dir, *file, pname[MAXPATHLEN];
 178 size_t n;
 179
 180 \&...
 181
 182 n = strlcpy(pname, dir, sizeof(pname));
 183 if (n >= sizeof(pname))
 184         goto toolong;
 185 if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
 186         goto toolong;
 187 .Ed
 188 .Pp
 189 However, one may question the validity of such optimizations, as they
 190 defeat the whole purpose of
 191 .Fn strlcpy
 192 and
 193 .Fn strlcat .
 194 As a matter of fact, the first version of this manual page got it wrong.
 195 .Sh SEE ALSO
 196 .Xr snprintf 3 ,
 197 .Xr strncat 3 ,
 198 .Xr strncpy 3 ,
 199 .Xr wcslcpy 3
 200 .Sh HISTORY
 201 The
 202 .Fn strlcpy
 203 and
 204 .Fn strlcat
 205 functions first appeared in
 206 .Ox 2.4 ,
 207 and made their appearance in
 208 .Fx 3.3 .