Libc-763.11.tar.gz

[apple/libc.git] / string / strlcpy.3

diff --git a/string/strlcpy.3 b/string/strlcpy.3
index 60bb36b955f26dc712ff9f297102db2bc55f6829..3cf8bc203f0d8b518d650e2b0ed220fbcada0c8e 100644 (file)
--- a/string/strlcpy.3
+++ b/string/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.11 2001/10/01 16:09:00 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,8 +195,10 @@ 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
 and
 .Fn strlcat