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