1 .\" $OpenBSD: strlcpy.3,v 1.19 2007/05/31 19:19:32 jmc Exp $
3 .\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
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.
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.
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.
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 $
37 .Nd size-bounded string copying and concatenation
43 .Fn strlcpy "char *dst" "const char *src" "size_t size"
45 .Fn strlcat "char *dst" "const char *src" "size_t size"
51 functions copy and concatenate strings respectively.
53 to be safer, more consistent, and less error prone replacements for
57 Unlike those functions,
61 take the full size of the buffer (not just the length) and guarantee to
62 NUL-terminate the result (as long as
64 is larger than 0 or, in the case of
66 as long as there is at least one byte free in
68 Note that a byte for the NUL should be included in
80 must be NUL-terminated and for
86 must be NUL-terminated.
92 - 1 characters from the NUL-terminated string
96 NUL-terminating the result.
100 function appends the NUL-terminated string
104 It will append at most
106 - strlen(dst) - 1 bytes, NUL-terminating the result.
112 functions return the total length of the string they tried to
116 that means the length of
120 that means the initial length of
125 While this may seem somewhat confusing, it was done to make
126 truncation detection simple.
128 Note however, that if
132 characters without finding a NUL, the length of the string is considered
135 and the destination string will not be NUL-terminated (since there was
136 no space for the NUL).
139 from running off the end of a string.
140 In practice this should not happen (as it means that either
147 The check exists to prevent potential security problems in incorrect code.
149 The following code fragment illustrates the simple case:
150 .Bd -literal -offset indent
151 char *s, *p, buf[BUFSIZ];
155 (void)strlcpy(buf, s, sizeof(buf));
156 (void)strlcat(buf, p, sizeof(buf));
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];
166 if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
168 if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
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];
180 n = strlcpy(pname, dir, sizeof(pname));
181 if (n >= sizeof(pname))
183 if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
187 However, one may question the validity of such optimizations, as they
188 defeat the whole purpose of
192 As a matter of fact, the first version of this manual page got it wrong.
202 functions first appeared in
204 and made their appearance in