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