xref: /dragonfly/lib/libc/string/strlcpy.3 (revision 91dc43dd) 
1.\"	$OpenBSD: strlcpy.3,v 1.26 2013/09/30 12:02:35 millert 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: head/lib/libc/string/strlcpy.3 235286 2012-05-11 20:06:46Z gjb $
29.\"
30.Dd November 4, 2013
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 dstsize"
43.Ft size_t
44.Fn strlcat "char * restrict dst" "const char * restrict src" "size_t dstsize"
45.Sh DESCRIPTION
46The
47.Fn strlcpy
48and
49.Fn strlcat
50functions copy and concatenate strings with the
51same input parameters and output result as
52.Xr snprintf 3 .
53They are designed to be safer, more consistent, and less error
54prone replacements for the easily misused functions
55.Xr strncpy 3
56and
57.Xr strncat 3 .
58.Pp
59.Fn strlcpy
60and
61.Fn strlcat
62take the full size of the destination buffer and guarantee
63NUL-termination if there is room.
64Note that room for the NUL should be included in
65.Fa dstsize .
66.Pp
67.Fn strlcpy
68copies up to
69.Fa dstsize
70\- 1 characters from the string
71.Fa src
72to
73.Fa dst ,
74NUL-terminating the result if
75.Fa dstsize
76is not 0.
77.Pp
78.Fn strlcat
79appends string
80.Fa src
81to the end of
82.Fa dst .
83It will append at most
84.Fa dstsize
85\- strlen(dst) \- 1 characters.
86It will then NUL-terminate, unless
87.Fa dstsize
88is 0 or the original
89.Fa dst
90string was longer than
91.Fa dstsize
92(in practice this should not happen
93as it means that either
94.Fa dstsize
95is incorrect or that
96.Fa dst
97is not a proper string).
98.Pp
99If the
100.Fa src
101and
102.Fa dst
103strings overlap, the behavior is undefined.
104.Sh RETURN VALUES
105Besides quibbles over the return type
106.Pf ( Va size_t
107versus
108.Va int )
109and signal handler safety
110.Pf ( Xr snprintf 3
111is not entirely safe on some systems), the
112following two are equivalent:
113.Bd -literal -offset indent
114n = strlcpy(dst, src, len);
115n = snprintf(dst, len, "%s", src);
116.Ed
117.Pp
118Like
119.Xr snprintf 3 ,
120the
121.Fn strlcpy
122and
123.Fn strlcat
124functions return the total length of the string they tried to create.
125For
126.Fn strlcpy
127that means the length of
128.Fa src .
129For
130.Fn strlcat
131that means the initial length of
132.Fa dst
133plus
134the length of
135.Fa src .
136.Pp
137If the return value is
138.Cm >=
139.Va dstsize ,
140the output string has been truncated.
141It is the caller's responsibility to handle this.
142.Sh EXAMPLES
143The following code fragment illustrates the simple case:
144.Bd -literal -offset indent
145char *s, *p, buf[BUFSIZ];
146
147\&...
148
149(void)strlcpy(buf, s, sizeof(buf));
150(void)strlcat(buf, p, sizeof(buf));
151.Ed
152.Pp
153To detect truncation, perhaps while building a pathname, something
154like the following might be used:
155.Bd -literal -offset indent
156char *dir, *file, pname[MAXPATHLEN];
157
158\&...
159
160if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
161	goto toolong;
162if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
163	goto toolong;
164.Ed
165.Pp
166Since it is known how many characters were copied the first time, things
167can be sped up a bit by using a copy instead of an append:
168.Bd -literal -offset indent
169char *dir, *file, pname[MAXPATHLEN];
170size_t n;
171
172\&...
173
174n = strlcpy(pname, dir, sizeof(pname));
175if (n >= sizeof(pname))
176	goto toolong;
177if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n)
178	goto toolong;
179.Ed
180.Pp
181However, one may question the validity of such optimizations, as they
182defeat the whole purpose of
183.Fn strlcpy
184and
185.Fn strlcat .
186As a matter of fact, the first version of this manual page got it wrong.
187.Sh SEE ALSO
188.Xr snprintf 3 ,
189.Xr strncat 3 ,
190.Xr strncpy 3 ,
191.Xr wcslcpy 3
192.Sh HISTORY
193The
194.Fn strlcpy
195and
196.Fn strlcat
197functions first appeared in
198.Ox 2.4 ,
199and
200.Fx 3.3 .
201