libc/string/strlcpy.3

.\"     $OpenBSD: strlcpy.3,v 1.26 2013/09/30 12:02:35 millert Exp $
.\"
.\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd November 4, 2013
.Dt STRLCPY 3
.Os
.Sh NAME
.Nm strlcpy ,
.Nm strlcat
.Nd size-bounded string copying and concatenation
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In string.h
.Ft size_t
.Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t size"
.Ft size_t
.Fn strlcat "char * restrict dst" "const char * restrict src" "size_t size"
.Sh DESCRIPTION
The
.Fn strlcpy
and
.Fn strlcat
functions copy and concatenate strings with the
same input parameters and output result as
.Xr snprintf 3 .
They are designed to be safer, more consistent, and less error
prone replacements for the easily misused functions
.Xr strncpy 3
and
.Xr strncat 3 .
.Pp
.Fn strlcpy
and
.Fn strlcat
take the full size of the destination buffer and guarantee
NUL-termination if there is room.
Note that room for the NUL should be included in
.Fa dstsize .
.Pp
.Fn strlcpy
copies up to
.Fa dstsize
\- 1 characters from the string
.Fa src
to
.Fa dst ,
NUL-terminating the result if
.Fa dstsize
is not 0.
.Pp
.Fn strlcat
appends string
.Fa src
to the end of
.Fa dst .
It will append at most
.Fa dstsize
\- strlen(dst) \- 1 characters.
It will then NUL-terminate, unless
.Fa dstsize
is 0 or the original
.Fa dst
string was longer than
.Fa dstsize
(in practice this should not happen
as it means that either
.Fa dstsize
is incorrect or that
.Fa dst
is not a proper string).
.Pp
If the
.Fa src
and
.Fa dst
strings overlap, the behavior is undefined.
.Sh RETURN VALUES
Besides quibbles over the return type
.Pf ( Va size_t
versus
.Va int )
and signal handler safety
.Pf ( Xr snprintf 3
is not entirely safe on some systems), the
following two are equivalent:
.Bd -literal -offset indent
n = strlcpy(dst, src, len);
n = snprintf(dst, len, "%s", src);
.Ed
.Pp
Like
.Xr snprintf 3 ,
the
.Fn strlcpy
and
.Fn strlcat
functions return the total length of the string they tried to create.
For
.Fn strlcpy
that means the length of
.Fa src .
For
.Fn strlcat
that means the initial length of
.Fa dst
plus
the length of
.Fa src .
.Pp
If the return value is
.Cm >=
.Va dstsize ,
the output string has been truncated.
It is the caller's responsibility to handle this.
.Sh EXAMPLES
The following code fragment illustrates the simple case:
.Bd -literal -offset indent
char *s, *p, buf[BUFSIZ];

\&...

(void)strlcpy(buf, s, sizeof(buf));
(void)strlcat(buf, p, sizeof(buf));
.Ed
.Pp
To detect truncation, perhaps while building a pathname, something
like the following might be used:
.Bd -literal -offset indent
char *dir, *file, pname[MAXPATHLEN];

\&...

if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname))
        goto toolong;
if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
        goto toolong;
.Ed
.Pp
Since it is known how many characters were copied the first time, things
can be sped up a bit by using a copy instead of an append:
.Bd -literal -offset indent
char *dir, *file, pname[MAXPATHLEN];
size_t n;

\&...

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