1.\" $OpenBSD: strlcpy.3,v 1.5 1999/06/06 15:17:32 aaron Exp $ 2.\" 3.\" Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 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: src/lib/libc/string/strlcpy.3,v 1.4.2.8 2002/01/19 12:29:40 yar Exp $ 29.\" $DragonFly: src/lib/libc/string/strlcpy.3,v 1.2 2003/06/17 04:26:46 dillon Exp $ 30.\" 31.Dd June 22, 1998 32.Dt STRLCPY 3 33.Os 34.Sh NAME 35.Nm strlcpy , 36.Nm strlcat 37.Nd size-bounded string copying and concatenation 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In string.h 42.Ft size_t 43.Fn strlcpy "char *dst" "const char *src" "size_t size" 44.Ft size_t 45.Fn strlcat "char *dst" "const char *src" "size_t size" 46.Sh DESCRIPTION 47The 48.Fn strlcpy 49and 50.Fn strlcat 51functions copy and concatenate strings respectively. They are designed 52to be safer, more consistent, and less error prone replacements for 53.Xr strncpy 3 54and 55.Xr strncat 3 . 56Unlike those functions, 57.Fn strlcpy 58and 59.Fn strlcat 60take the full size of the buffer (not just the length) and guarantee to 61NUL-terminate the result (as long as 62.Fa size 63is larger than 0 or, in the case of 64.Fn strlcat , 65as long as there is at least one byte free in 66.Fa dst ) . 67Note that you should include a byte for the NUL in 68.Fa size . 69Also note that 70.Fn strlcpy 71and 72.Fn strlcat 73only operate on true 74.Dq C 75strings. 76This means that for 77.Fn strlcpy 78.Fa src 79must be NUL-terminated and for 80.Fn strlcat 81both 82.Fa src 83and 84.Fa dst 85must be NUL-terminated. 86.Pp 87The 88.Fn strlcpy 89function copies up to 90.Fa size 91- 1 characters from the NUL-terminated string 92.Fa src 93to 94.Fa dst , 95NUL-terminating the result. 96.Pp 97The 98.Fn strlcat 99function appends the NUL-terminated string 100.Fa src 101to the end of 102.Fa dst . 103It will append at most 104.Fa size 105- strlen(dst) - 1 bytes, NUL-terminating the result. 106.Sh RETURN VALUES 107The 108.Fn strlcpy 109and 110.Fn strlcat 111functions return the total length of the string they tried to 112create. For 113.Fn strlcpy 114that means the length of 115.Fa src . 116For 117.Fn strlcat 118that means the initial length of 119.Fa dst 120plus 121the length of 122.Fa src . 123While this may seem somewhat confusing it was done to make 124truncation detection simple. 125.Pp 126Note however, that if 127.Fn strlcat 128traverses 129.Fa size 130characters without finding a NUL, the length of the string is considered 131to be 132.Fa size 133and the destination string will not be NUL-terminated (since there was 134no space for the NUL). 135This keeps 136.Fn strlcat 137from running off the end of a string. 138In practice this should not happen (as it means that either 139.Fa size 140is incorrect or that 141.Fa dst 142is not a proper 143.Dq C 144string). 145The check exists to prevent potential security problems in incorrect code. 146.Sh EXAMPLES 147The following code fragment illustrates the simple case: 148.Bd -literal -offset indent 149char *s, *p, buf[BUFSIZ]; 150 151\&... 152 153(void)strlcpy(buf, s, sizeof(buf)); 154(void)strlcat(buf, p, sizeof(buf)); 155.Ed 156.Pp 157To detect truncation, perhaps while building a pathname, something 158like the following might be used: 159.Bd -literal -offset indent 160char *dir, *file, pname[MAXPATHLEN]; 161 162\&... 163 164if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) 165 goto toolong; 166if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) 167 goto toolong; 168.Ed 169.Pp 170Since we know how many characters we copied the first time, we can 171speed things up a bit by using a copy instead of an append: 172.Bd -literal -offset indent 173char *dir, *file, pname[MAXPATHLEN]; 174size_t n; 175 176\&... 177 178n = strlcpy(pname, dir, sizeof(pname)); 179if (n >= sizeof(pname)) 180 goto toolong; 181if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) 182 goto toolong; 183.Ed 184.Pp 185However, one may question the validity of such optimizations, as they 186defeat the whole purpose of 187.Fn strlcpy 188and 189.Fn strlcat . 190As a matter of fact, the first version of this manual page got it wrong. 191.Sh SEE ALSO 192.Xr snprintf 3 , 193.Xr strncat 3 , 194.Xr strncpy 3 195.Sh HISTORY 196.Fn strlcpy 197and 198.Fn strlcat 199functions first appeared in 200.Ox 2.4 , 201and made their appearance in 202.Fx 3.3 . 203