1.\" $NetBSD: strlcpy.3,v 1.6 2001/03/02 06:06:08 cgd Exp $ 2.\" from OpenBSD: strlcpy.3,v 1.11 2000/11/16 23:27:41 angelos Exp 3.\" 4.\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote products 16.\" derived from this software without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 19.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 20.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 22.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 23.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 24.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 25.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 26.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 27.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd March 1, 2001 30.Dt STRLCPY 3 31.Os 32.Sh NAME 33.Nm strlcpy , 34.Nm strlcat 35.Nd size-bounded string copying and concatenation 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.Fd #include <string.h> 40.Ft size_t 41.Fn strlcpy "char *dst" "const char *src" "size_t size" 42.Ft size_t 43.Fn strlcat "char *dst" "const char *src" "size_t size" 44.Sh DESCRIPTION 45The 46.Fn strlcpy 47and 48.Fn strlcat 49functions copy and concatenate strings respectively. 50They are designed 51to be safer, more consistent, and less error prone replacements for 52.Xr strncpy 3 53and 54.Xr strncat 3 . 55Unlike those functions, 56.Fn strlcpy 57and 58.Fn strlcat 59take the full size of the buffer (not just the length) and guarantee to 60NUL-terminate the result (as long as 61.Fa size 62is larger than 0 or, in the case of 63.Fn strlcat , 64as long as there is at least one byte free in 65.Fa dst ) . 66Note that you should include a byte for the NUL in 67.Fa size . 68Also note that 69.Fn strlcpy 70and 71.Fn strlcat 72only operate on true 73.Dq C 74strings. 75This means that for 76.Fn strlcpy 77.Fa src 78must be NUL-terminated and for 79.Fn strlcat 80both 81.Fa src 82and 83.Fa dst 84must be NUL-terminated. 85.Pp 86The 87.Fn strlcpy 88function copies up to 89.Fa size 90- 1 characters from the NUL-terminated string 91.Fa src 92to 93.Fa dst , 94NUL-terminating the result. 95.Pp 96The 97.Fn strlcat 98function appends the NUL-terminated string 99.Fa src 100to the end of 101.Fa dst . 102It will append at most 103.Fa size 104- strlen(dst) - 1 bytes, NUL-terminating the result. 105.Sh RETURN VALUES 106The 107.Fn strlcpy 108and 109.Fn strlcat 110functions return the total length of the string they tried to create. 111For 112.Fn strlcpy 113that means the length of 114.Fa src . 115For 116.Fn strlcat 117that means the initial length of 118.Fa dst 119plus 120the length of 121.Fa src . 122While this may seem somewhat confusing it was done to make 123truncation detection simple. 124.Sh EXAMPLES 125The following code fragment illustrates the simple case: 126.Bd -literal -offset indent 127char *s, *p, buf[BUFSIZ]; 128 129\&... 130 131(void)strlcpy(buf, s, sizeof(buf)); 132(void)strlcat(buf, p, sizeof(buf)); 133.Ed 134.Pp 135To detect truncation, perhaps while building a pathname, something 136like the following might be used: 137.Bd -literal -offset indent 138char *dir, *file, pname[MAXPATHLEN]; 139 140\&... 141 142if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) 143 goto toolong; 144if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) 145 goto toolong; 146.Ed 147.Pp 148Since we know how many characters we copied the first time, we can 149speed things up a bit by using a copy instead of an append: 150.Bd -literal -offset indent 151char *dir, *file, pname[MAXPATHLEN]; 152size_t n; 153 154\&... 155 156n = strlcpy(pname, dir, sizeof(pname)); 157if (n >= sizeof(pname)) 158 goto toolong; 159if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) 160 goto toolong; 161.Ed 162.Pp 163However, one may question the validity of such optimizations, as they 164defeat the whole purpose of 165.Fn strlcpy 166and 167.Fn strlcat . 168.Sh SEE ALSO 169.Xr snprintf 3 , 170.Xr strncat 3 , 171.Xr strncpy 3 172.Sh HISTORY 173.Fn strlcpy 174and 175.Fn strlcat 176first appeared in 177.Ox 2.4 , 178then in 179.Nx 1.4.3 180and 181.Fx 3.3.0 . 182