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