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.\"
| 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: head/lib/libc/string/strlcpy.3 108037 2002-12-18 12:45:11Z ru $
| 28.\" $FreeBSD: head/lib/libc/string/strlcpy.3 131504 2004-07-02 23:52:20Z ru $
|
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.In 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
| 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.In 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
| 50functions copy and concatenate strings respectively. 51They 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
| 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
|
111create. For
| 112create. 113For
|
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.Pp 125Note however, that if 126.Fn strlcat 127traverses 128.Fa size 129characters without finding a NUL, the length of the string is considered 130to be 131.Fa size 132and the destination string will not be NUL-terminated (since there was 133no space for the NUL). 134This keeps 135.Fn strlcat 136from running off the end of a string. 137In practice this should not happen (as it means that either 138.Fa size 139is incorrect or that 140.Fa dst 141is not a proper 142.Dq C 143string). 144The check exists to prevent potential security problems in incorrect code. 145.Sh EXAMPLES 146The following code fragment illustrates the simple case: 147.Bd -literal -offset indent 148char *s, *p, buf[BUFSIZ]; 149 150\&... 151 152(void)strlcpy(buf, s, sizeof(buf)); 153(void)strlcat(buf, p, sizeof(buf)); 154.Ed 155.Pp 156To detect truncation, perhaps while building a pathname, something 157like the following might be used: 158.Bd -literal -offset indent 159char *dir, *file, pname[MAXPATHLEN]; 160 161\&... 162 163if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) 164 goto toolong; 165if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) 166 goto toolong; 167.Ed 168.Pp 169Since we know how many characters we copied the first time, we can 170speed things up a bit by using a copy instead of an append: 171.Bd -literal -offset indent 172char *dir, *file, pname[MAXPATHLEN]; 173size_t n; 174 175\&... 176 177n = strlcpy(pname, dir, sizeof(pname)); 178if (n >= sizeof(pname)) 179 goto toolong; 180if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) 181 goto toolong; 182.Ed 183.Pp 184However, one may question the validity of such optimizations, as they 185defeat the whole purpose of 186.Fn strlcpy 187and 188.Fn strlcat . 189As a matter of fact, the first version of this manual page got it wrong. 190.Sh SEE ALSO 191.Xr snprintf 3 , 192.Xr strncat 3 , 193.Xr strncpy 3 194.Sh HISTORY 195The 196.Fn strlcpy 197and 198.Fn strlcat 199functions first appeared in 200.Ox 2.4 , 201and made their appearance in 202.Fx 3.3 .
| 114.Fn strlcpy 115that means the length of 116.Fa src . 117For 118.Fn strlcat 119that means the initial length of 120.Fa dst 121plus 122the length of 123.Fa src . 124While this may seem somewhat confusing it was done to make 125truncation detection simple. 126.Pp 127Note however, that if 128.Fn strlcat 129traverses 130.Fa size 131characters without finding a NUL, the length of the string is considered 132to be 133.Fa size 134and the destination string will not be NUL-terminated (since there was 135no space for the NUL). 136This keeps 137.Fn strlcat 138from running off the end of a string. 139In practice this should not happen (as it means that either 140.Fa size 141is incorrect or that 142.Fa dst 143is not a proper 144.Dq C 145string). 146The check exists to prevent potential security problems in incorrect code. 147.Sh EXAMPLES 148The following code fragment illustrates the simple case: 149.Bd -literal -offset indent 150char *s, *p, buf[BUFSIZ]; 151 152\&... 153 154(void)strlcpy(buf, s, sizeof(buf)); 155(void)strlcat(buf, p, sizeof(buf)); 156.Ed 157.Pp 158To detect truncation, perhaps while building a pathname, something 159like the following might be used: 160.Bd -literal -offset indent 161char *dir, *file, pname[MAXPATHLEN]; 162 163\&... 164 165if (strlcpy(pname, dir, sizeof(pname)) >= sizeof(pname)) 166 goto toolong; 167if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) 168 goto toolong; 169.Ed 170.Pp 171Since we know how many characters we copied the first time, we can 172speed things up a bit by using a copy instead of an append: 173.Bd -literal -offset indent 174char *dir, *file, pname[MAXPATHLEN]; 175size_t n; 176 177\&... 178 179n = strlcpy(pname, dir, sizeof(pname)); 180if (n >= sizeof(pname)) 181 goto toolong; 182if (strlcpy(pname + n, file, sizeof(pname) - n) >= sizeof(pname) - n) 183 goto toolong; 184.Ed 185.Pp 186However, one may question the validity of such optimizations, as they 187defeat the whole purpose of 188.Fn strlcpy 189and 190.Fn strlcat . 191As a matter of fact, the first version of this manual page got it wrong. 192.Sh SEE ALSO 193.Xr snprintf 3 , 194.Xr strncat 3 , 195.Xr strncpy 3 196.Sh HISTORY 197The 198.Fn strlcpy 199and 200.Fn strlcat 201functions first appeared in 202.Ox 2.4 , 203and made their appearance in 204.Fx 3.3 .
|