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 October 27, 2023 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 same input parameters and output result as 49.Xr strcpy 3 50and 51.Xr strcat 3 52with proper overflow protection. 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 105The 106.Fn strlcpy 107and 108.Fn strlcat 109functions return the total length of the string they tried to create. 110For 111.Fn strlcpy 112that means the length of 113.Fa src . 114For 115.Fn strlcat 116that means the initial length of 117.Fa dst 118plus 119the length of 120.Fa src . 121.Pp 122If the return value is 123.Cm >= 124.Va dstsize , 125the output string has been truncated. 126It is the caller's responsibility to handle this. 127.Sh EXAMPLES 128The following code fragment illustrates the simple case: 129.Bd -literal -offset indent 130char *s, *p, buf[BUFSIZ]; 131 132\&... 133 134(void)strlcpy(buf, s, sizeof(buf)); 135(void)strlcat(buf, p, sizeof(buf)); 136.Ed 137.Pp 138To detect truncation, perhaps while building a pathname, something 139like the following might be used: 140.Bd -literal -offset indent 141char *dir, *file, pname[MAXPATHLEN]; 142 143\&... 144 145if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) 146 goto toolong; 147if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) 148 goto toolong; 149.Ed 150.Pp 151Since it is known how many characters were copied the first time, things 152can be sped up a bit by using a copy instead of an append: 153.Bd -literal -offset indent 154char *dir, *file, pname[MAXPATHLEN]; 155size_t n; 156 157\&... 158 159n = strlcpy(pname, dir, sizeof(pname)); 160if (n >= sizeof(pname)) 161 goto toolong; 162if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) 163 goto toolong; 164.Ed 165.Pp 166However, one may question the validity of such optimizations, as they 167defeat the whole purpose of 168.Fn strlcpy 169and 170.Fn strlcat . 171As a matter of fact, the first version of this manual page got it wrong. 172.Sh SEE ALSO 173.Xr snprintf 3 , 174.Xr strncat 3 , 175.Xr strncpy 3 , 176.Xr wcslcpy 3 177.Rs 178.%A Todd C. Miller 179.%A Theo de Raadt 180.%T strlcpy and strlcat -- Consistent, Safe, String Copy and Concatenation 181.%I USENIX Association 182.%B Proceedings of the FREENIX Track: 1999 USENIX Annual Technical Conference 183.%D June 6-11, 1999 184.%U http://www.usenix.org/publications/library/proceedings/usenix99/full_papers/millert/millert.pdf 185.Re 186.Sh HISTORY 187The 188.Fn strlcpy 189and 190.Fn strlcat 191functions first appeared in 192.Ox 2.4 , 193and 194.Fx 3.3 . 195