[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/string/strlcpy.3

Version: -  FREEBSD  -  FREEBSD10  -  FREEBSD9  -  FREEBSD92  -  FREEBSD91  -  FREEBSD90  -  FREEBSD8  -  FREEBSD82  -  FREEBSD81  -  FREEBSD80  -  FREEBSD7  -  FREEBSD74  -  FREEBSD73  -  FREEBSD72  -  FREEBSD71  -  FREEBSD70  -  FREEBSD6  -  FREEBSD64  -  FREEBSD63  -  FREEBSD62  -  FREEBSD61  -  FREEBSD60  -  FREEBSD5  -  FREEBSD55  -  FREEBSD54  -  FREEBSD53  -  FREEBSD52  -  FREEBSD51  -  FREEBSD50  -  FREEBSD4  -  FREEBSD3  -  FREEBSD22  -  cheribsd  -  linux-2.6  -  linux-2.4.22  -  MK83  -  MK84  -  PLAN9  -  DFBSD  -  NETBSD  -  NETBSD5  -  NETBSD4  -  NETBSD3  -  NETBSD20  -  OPENBSD  -  xnu-517  -  xnu-792  -  xnu-792.6.70  -  xnu-1228  -  xnu-1456.1.26  -  xnu-1699.24.8  -  xnu-2050.18.24  -  OPENSOLARIS  -  minix-3-1-1  -  FREEBSD-LIBC  -  FREEBSD8-LIBC  -  FREEBSD7-LIBC  -  FREEBSD6-LIBC  -  GLIBC27 
SearchContext: -  none  -  3  -  10 

    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: stable/8/lib/libc/string/strlcpy.3 190798 2009-04-07 13:42:53Z trasz $
   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 .Sh RETURN VALUES
  107 The
  108 .Fn strlcpy
  109 and
  110 .Fn strlcat
  111 functions return the total length of the string they tried to
  112 create.
  113 For
  114 .Fn strlcpy
  115 that means the length of
  116 .Fa src .
  117 For
  118 .Fn strlcat
  119 that means the initial length of
  120 .Fa dst
  121 plus
  122 the length of
  123 .Fa src .
  124 While this may seem somewhat confusing, it was done to make
  125 truncation detection simple.
  126 .Pp
  127 Note however, that if
  128 .Fn strlcat
  129 traverses
  130 .Fa size
  131 characters without finding a NUL, the length of the string is considered
  132 to be
  133 .Fa size
  134 and the destination string will not be NUL-terminated (since there was
  135 no space for the NUL).
  136 This keeps
  137 .Fn strlcat
  138 from running off the end of a string.
  139 In practice this should not happen (as it means that either
  140 .Fa size
  141 is incorrect or that
  142 .Fa dst
  143 is not a proper
  144 .Dq C
  145 string).
  146 The check exists to prevent potential security problems in incorrect code.
  147 .Sh EXAMPLES
  148 The following code fragment illustrates the simple case:
  149 .Bd -literal -offset indent
  150 char *s, *p, buf[BUFSIZ];
  151 
  152 \&...
  153 
  154 (void)strlcpy(buf, s, sizeof(buf));
  155 (void)strlcat(buf, p, sizeof(buf));
  156 .Ed
  157 .Pp
  158 To detect truncation, perhaps while building a pathname, something
  159 like the following might be used:
  160 .Bd -literal -offset indent
  161 char *dir, *file, pname[MAXPATHLEN];
  162 
  163 \&...
  164 
  165 if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
  166         goto toolong;
  167 if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
  168         goto toolong;
  169 .Ed
  170 .Pp
  171 Since it is known how many characters were copied the first time, things
  172 can be sped up a bit by using a copy instead of an append
  173 .Bd -literal -offset indent
  174 char *dir, *file, pname[MAXPATHLEN];
  175 size_t n;
  176 
  177 \&...
  178 
  179 n = strlcpy(pname, dir, sizeof(pname));
  180 if (n >= sizeof(pname))
  181         goto toolong;
  182 if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
  183         goto toolong;
  184 .Ed
  185 .Pp
  186 However, one may question the validity of such optimizations, as they
  187 defeat the whole purpose of
  188 .Fn strlcpy
  189 and
  190 .Fn strlcat .
  191 As a matter of fact, the first version of this manual page got it wrong.
  192 .Sh SEE ALSO
  193 .Xr snprintf 3 ,
  194 .Xr strncat 3 ,
  195 .Xr strncpy 3 ,
  196 .Xr wcslcpy 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 .

Cache object: 9c878f7e7943bd59d19014a7a6bd7826


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.