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 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