lib/libc/string/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.14 2009/01/12 06:10:48 delphij Exp $
  29 .\" $DragonFly: src/lib/libc/string/strlcpy.3,v 1.2 2003/06/17 04:26:46 dillon Exp $
  30 .\"
  31 .Dd June 22, 1998
  32 .Dt STRLCPY 3
  33 .Os
  34 .Sh NAME
  35 .Nm strlcpy ,
  36 .Nm strlcat
  37 .Nd size-bounded string copying and concatenation
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In string.h
  42 .Ft size_t
  43 .Fn strlcpy "char *dst" "const char *src" "size_t size"
  44 .Ft size_t
  45 .Fn strlcat "char *dst" "const char *src" "size_t size"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn strlcpy
  49 and
  50 .Fn strlcat
  51 functions copy and concatenate strings respectively.
  52 They are designed
  53 to be safer, more consistent, and less error prone replacements for
  54 .Xr strncpy 3
  55 and
  56 .Xr strncat 3 .
  57 Unlike those functions,
  58 .Fn strlcpy
  59 and
  60 .Fn strlcat
  61 take the full size of the buffer (not just the length) and guarantee to
  62 NUL-terminate the result (as long as
  63 .Fa size
  64 is larger than 0 or, in the case of
  65 .Fn strlcat ,
  66 as long as there is at least one byte free in
  67 .Fa dst ) .
  68 Note that a byte for the NUL should be included in
  69 .Fa size .
  70 Also note that
  71 .Fn strlcpy
  72 and
  73 .Fn strlcat
  74 only operate on true
  75 .Dq C
  76 strings.
  77 This means that for
  78 .Fn strlcpy
  79 .Fa src
  80 must be NUL-terminated and for
  81 .Fn strlcat
  82 both
  83 .Fa src
  84 and
  85 .Fa dst
  86 must be NUL-terminated.
  87 .Pp
  88 The
  89 .Fn strlcpy
  90 function copies up to
  91 .Fa size
  92 - 1 characters from the NUL-terminated string
  93 .Fa src
  94 to
  95 .Fa dst ,
  96 NUL-terminating the result.
  97 .Pp
  98 The
  99 .Fn strlcat
 100 function appends the NUL-terminated string
 101 .Fa src
 102 to the end of
 103 .Fa dst .
 104 It will append at most
 105 .Fa size
 106 - strlen(dst) - 1 bytes, NUL-terminating the result.
 107 .Sh RETURN VALUES
 108 The
 109 .Fn strlcpy
 110 and
 111 .Fn strlcat
 112 functions return the total length of the string they tried to
 113 create.
 114 For
 115 .Fn strlcpy
 116 that means the length of
 117 .Fa src .
 118 For
 119 .Fn strlcat
 120 that means the initial length of
 121 .Fa dst
 122 plus
 123 the length of
 124 .Fa src .
 125 While this may seem somewhat confusing, it was done to make
 126 truncation detection simple.
 127 .Pp
 128 Note however, that if
 129 .Fn strlcat
 130 traverses
 131 .Fa size
 132 characters without finding a NUL, the length of the string is considered
 133 to be
 134 .Fa size
 135 and the destination string will not be NUL-terminated (since there was
 136 no space for the NUL).
 137 This keeps
 138 .Fn strlcat
 139 from running off the end of a string.
 140 In practice this should not happen (as it means that either
 141 .Fa size
 142 is incorrect or that
 143 .Fa dst
 144 is not a proper
 145 .Dq C
 146 string).
 147 The check exists to prevent potential security problems in incorrect code.
 148 .Sh EXAMPLES
 149 The following code fragment illustrates the simple case:
 150 .Bd -literal -offset indent
 151 char *s, *p, buf[BUFSIZ];
 152
 153 \&...
 154
 155 (void)strlcpy(buf, s, sizeof(buf));
 156 (void)strlcat(buf, p, sizeof(buf));
 157 .Ed
 158 .Pp
 159 To detect truncation, perhaps while building a pathname, something
 160 like the following might be used:
 161 .Bd -literal -offset indent
 162 char *dir, *file, pname[MAXPATHLEN];
 163
 164 \&...
 165
 166 if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
 167         goto toolong;
 168 if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
 169         goto toolong;
 170 .Ed
 171 .Pp
 172 Since it is known how many characters were copied the first time, things
 173 can be sped up a bit by using a copy instead of an append
 174 .Bd -literal -offset indent
 175 char *dir, *file, pname[MAXPATHLEN];
 176 size_t n;
 177
 178 \&...
 179
 180 n = strlcpy(pname, dir, sizeof(pname));
 181 if (n >= sizeof(pname))
 182         goto toolong;
 183 if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
 184         goto toolong;
 185 .Ed
 186 .Pp
 187 However, one may question the validity of such optimizations, as they
 188 defeat the whole purpose of
 189 .Fn strlcpy
 190 and
 191 .Fn strlcat .
 192 As a matter of fact, the first version of this manual page got it wrong.
 193 .Sh SEE ALSO
 194 .Xr snprintf 3 ,
 195 .Xr strncat 3 ,
 196 .Xr strncpy 3
 197 .Sh HISTORY
 198 The
 199 .Fn strlcpy
 200 and
 201 .Fn strlcat
 202 functions first appeared in
 203 .Ox 2.4 ,
 204 and made their appearance in
 205 .Fx 3.3 .