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