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$ 29.\" 30.Dd June 22, 1998 31.Dt STRLCPY 3 32.Os 33.Sh NAME 34.Nm strlcpy , 35.Nm strlcat 36.Nd size-bounded string copying and concatenation 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.Fd #include <string.h> 41.Ft size_t 42.Fn strlcpy "char *dst" "const char *src" "size_t size" 43.Ft size_t 44.Fn strlcat "char *dst" "const char *src" "size_t size" 45.Sh DESCRIPTION 46The 47.Fn strlcpy 48and 49.Fn strlcat 50functions copy and concatenate strings respectively. They 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). Note that you should include a byte for the NUL in 63.Fa size . 64.Pp 65The 66.Fn strlcpy 67function copies up to 68.Fa size 69- 1 characters from the NUL-terminated string 70.Fa src 71to 72.Fa dst , 73NUL-terminating the result. 74.Pp 75The 76.Fn strlcat 77function appends the NUL-terminated string 78.Fa src 79to the end of 80.Fa dst . 81It will append at most 82.Fa size 83- strlen(dst) - 1 bytes, NUL-terminating the result. 84.Sh RETURN VALUES 85The 86.Fn strlcpy 87and 88.Fn strlcat 89functions return the total length of the string they tried to 90create. For 91.Fn strlcpy 92that means the length of 93.Fa src . 94For 95.Fn strlcat 96that means the initial length of 97.Fa dst 98plus 99the length of 100.Fa src . 101While this may seem somewhat confusing it was done to make 102truncation detection simple. 103.Sh EXAMPLES 104The following code fragment illustrates the simple case: 105.Bd -literal -offset indent 106char *s, *p, buf[BUFSIZ]; 107 108.Li ... 109 110(void)strlcpy(buf, s, sizeof(buf)); 111(void)strlcat(buf, p, sizeof(buf)); 112.Ed 113.Pp 114To detect truncation, perhaps while building a pathname, something 115like the following might be used: 116.Bd -literal -offset indent 117char *dir, *file, pname[MAXPATHLEN]; 118 119.Li ... 120 121if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) 122 goto toolong; 123if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) 124 goto toolong; 125.Ed 126.Pp 127Since we know how many characters we copied the first time, we can 128speed things up a bit by using a copy instead on an append: 129.Bd -literal -offset indent 130char *dir, *file, pname[MAXPATHNAMELEN]; 131size_t n; 132 133.Li ... 134 135n = strlcpy(pname, dir, sizeof(pname)); 136if (n >= sizeof(pname)) 137 goto toolong; 138if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) 139 goto toolong; 140.Ed 141.Pp 142However, one may question the validity of such optimizations, as they 143defeat the whole purpose of 144.Fn strlcpy 145and 146.Fn strlcat . 147As a matter of fact, the first version of this manual page got it wrong. 148.Sh SEE ALSO 149.Xr snprintf 3 , 150.Xr strncat 3 , 151.Xr strncpy 3 152.Sh HISTORY 153.Fn strlcpy 154and 155.Fn strlcat 156functions first appeared in 157.Ox 2.4 , 158and made their appearance in 159.Fx 3.3 . 160