Libc-1082.20.4.tar.gz

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

diff --git a/string/FreeBSD/strlcpy.3 b/string/FreeBSD/strlcpy.3
index 974cd958e57b923dafb4480b9ff964070bc374fe..3cf8bc203f0d8b518d650e2b0ed220fbcada0c8e 100644 (file)
--- 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
 .\"
 .\" 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.
 .\"
 .\" 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
 .\"
 .Dd June 22, 1998
 .Dt STRLCPY 3


@@ -39,15 +39,16 @@
 .Sh SYNOPSIS
 .In string.h
 .Ft size_t
 .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
 .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
 .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
 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 ) .
 .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
 .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.
 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
 .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 .
 .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 .
 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
 truncation detection simple.
 .Pp
 Note however, that if


@@ -166,8 +171,8 @@ if (strlcat(pname, file, sizeof(pname)) >= sizeof(pname))
        goto toolong;
 .Ed
 .Pp
        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;
 .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 ,
 .Sh SEE ALSO
 .Xr snprintf 3 ,
 .Xr strncat 3 ,

-.Xr strncpy 3
+.Xr strncpy 3 ,
+.Xr wcslcpy 3

 .Sh HISTORY
 The
 .Fn strlcpy
 .Sh HISTORY
 The
 .Fn strlcpy