X-Git-Url: https://git.saurik.com/apple/libc.git/blobdiff_plain/9385eb3d10ebe5eb398c52040ec3dbfba9b0cdcf..2be56ee90c5c5bee77895b8787a43e894249002b:/string/FreeBSD/strlcpy.3?ds=inline diff --git a/string/FreeBSD/strlcpy.3 b/string/FreeBSD/strlcpy.3 index 974cd95..3cf8bc2 100644 --- a/string/FreeBSD/strlcpy.3 +++ b/string/FreeBSD/strlcpy.3 @@ -1,18 +1,18 @@ -.\" $OpenBSD: strlcpy.3,v 1.5 1999/06/06 15:17:32 aaron Exp $ +.\" $OpenBSD: strlcpy.3,v 1.19 2007/05/31 19:19:32 jmc Exp $ .\" -.\" Copyright (c) 1998 Todd C. Miller <Todd.Miller@courtesan.com> -.\" All rights reserved. +.\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com> .\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY @@ -25,7 +25,7 @@ .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.\" $FreeBSD: src/lib/libc/string/strlcpy.3,v 1.12 2002/12/18 12:45:11 ru Exp $ +.\" $FreeBSD: src/lib/libc/string/strlcpy.3,v 1.16 2009/04/07 13:42:53 trasz Exp $ .\" .Dd June 22, 1998 .Dt STRLCPY 3 @@ -39,15 +39,16 @@ .Sh SYNOPSIS .In string.h .Ft size_t -.Fn strlcpy "char *dst" "const char *src" "size_t size" +.Fn strlcpy "char * restrict dst" "const char * restrict src" "size_t size" .Ft size_t -.Fn strlcat "char *dst" "const char *src" "size_t size" +.Fn strlcat "char * restrict dst" "const char * restrict src" "size_t size" .Sh DESCRIPTION The .Fn strlcpy and .Fn strlcat -functions copy and concatenate strings respectively. They are designed +functions copy and concatenate strings respectively. +They are designed to be safer, more consistent, and less error prone replacements for .Xr strncpy 3 and @@ -63,7 +64,7 @@ is larger than 0 or, in the case of .Fn strlcat , as long as there is at least one byte free in .Fa dst ) . -Note that you should include a byte for the NUL in +Note that a byte for the NUL should be included in .Fa size . Also note that .Fn strlcpy @@ -102,13 +103,17 @@ to the end of It will append at most .Fa size - strlen(dst) - 1 bytes, NUL-terminating the result. +.Pp +The source and destination strings should not overlap, as the +behavior is undefined. .Sh RETURN VALUES The .Fn strlcpy and .Fn strlcat functions return the total length of the string they tried to -create. For +create. +For .Fn strlcpy that means the length of .Fa src . @@ -119,7 +124,7 @@ that means the initial length of plus the length of .Fa src . -While this may seem somewhat confusing it was done to make +While this may seem somewhat confusing, it was done to make truncation detection simple. .Pp Note however, that if @@ -166,8 +171,8 @@ if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname)) goto toolong; .Ed .Pp -Since we know how many characters we copied the first time, we can -speed things up a bit by using a copy instead of an append: +Since it is known how many characters were copied the first time, things +can be sped up a bit by using a copy instead of an append .Bd -literal -offset indent char *dir, *file, pname[MAXPATHLEN]; size_t n; @@ -190,7 +195,8 @@ As a matter of fact, the first version of this manual page got it wrong. .Sh SEE ALSO .Xr snprintf 3 , .Xr strncat 3 , -.Xr strncpy 3 +.Xr strncpy 3 , +.Xr wcslcpy 3 .Sh HISTORY The .Fn strlcpy