Instead of documenting all the wide string functions in wmemchr(3), add

individual pages (based on the existing string man pages). By Tim van
der Molen (tbvdm at xs4all dot nl) after a suggestion by millert@.

ok deraadt

1 files changed, 139 insertions, 0 deletions

diff --git a/src/lib/libc/string/wcslcpy.3 b/src/lib/libc/string/wcslcpy.3
new file mode 100644
index 0000000000..6f068dc9df
--- /dev/null
+++ b/src/lib/libc/string/wcslcpy.3
@@ -0,0 +1,139 @@
+.\" $OpenBSD: wcslcpy.3,v 1.1 2011/07/09 16:32:11 nicm Exp $
+.\"
+.\" Copyright (c) 1998, 2000 Todd C. Miller <Todd.Miller@courtesan.com>
+.\"
+.\" 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.
+.\"
+.Dd $Mdocdate: July 9 2011 $
+.Dt WCSLCPY 3
+.Os
+.Sh NAME
+.Nm wcslcpy ,
+.Nm wcslcat
+.Nd size-bounded wide string copying and concatenation
+.Sh SYNOPSIS
+.Fd #include <wchar.h>
+.Ft size_t
+.Fn wcslcpy "wchar_t *dst" "const wchar_t *src" "size_t size"
+.Ft size_t
+.Fn wcslcat "wchar_t *dst" "const wchar_t *src" "size_t size"
+.Sh DESCRIPTION
+The
+.Fn wcslcpy
+and
+.Fn wcslcat
+functions copy and concatenate wide strings respectively.
+They are designed to be safer, more consistent, and less error prone
+replacements for
+.Xr wcsncpy 3
+and
+.Xr wcsncat 3 .
+Unlike those functions,
+.Fn wcslcpy
+and
+.Fn wcslcat
+take the full size of the buffer (not just the length) and guarantee to
+terminate the result with a null wide character (as long as
+.Fa size
+is larger than 0 or, in the case of
+.Fn wcslcat ,
+as long as there is at least one wide character free in
+.Fa dst ) .
+Note that a wide character for the null wide character should be included in
+.Fa size .
+Also note that
+.Fn wcslcpy
+and
+.Fn wcslcat
+only operate on wide strings that are terminated with a null wide character
+(L'\e0').
+This means that for
+.Fn wcslcpy
+.Fa src
+must be terminated with a null wide character and for
+.Fn wcslcat
+both
+.Fa src
+and
+.Fa dst
+must be terminated with a null wide character.
+.Pp
+The
+.Fn wcslcpy
+function copies up to
+.Fa size
+\(mi 1 wide characters from the wide string
+.Fa src
+to
+.Fa dst ,
+terminating the result with a null wide character.
+.Pp
+The
+.Fn wcslcat
+function appends the wide string
+.Fa src
+to the end of
+.Fa dst .
+It will append at most
+.Fa size
+\(mi wcslen(dst) \(mi 1 wide characters, terminating the result with a null
+wide character.
+.Sh RETURN VALUES
+The
+.Fn wcslcpy
+and
+.Fn wcslcat
+functions return the total length of the wide string they tried to create.
+For
+.Fn wcslcpy
+that means the length of
+.Fa src .
+For
+.Fn wcslcat
+that means the initial length of
+.Fa dst
+plus
+the length of
+.Fa src .
+While this may seem somewhat confusing, it was done to make
+truncation detection simple.
+.Pp
+Note, however, that if
+.Fn wcslcat
+traverses
+.Fa size
+wide characters without finding a null wide character, the length of the
+string is considered to be
+.Fa size
+and the destination wide string will not be terminated with a null wide
+character (since there was no space for it).
+This keeps
+.Fn wcslcat
+from running off the end of a wide string.
+In practice this should not happen (as it means that either
+.Fa size
+is incorrect or that
+.Fa dst
+is not terminated with a null wide character).
+The check exists to prevent potential security problems in incorrect code.
+.Sh SEE ALSO
+.Xr swprintf 3 ,
+.Xr wcsncat 3 ,
+.Xr wcsncpy 3
+.Sh HISTORY
+The
+.Fn wcslcpy
+and
+.Fn wcslcat
+functions first appeared in
+.Ox 3.8 .