NAME
wcslcpy, wcslcat
— size-bounded wide string
copying and concatenation
SYNOPSIS
#include
<wchar.h>
size_t
wcslcpy(wchar_t
* restrict dst, const
wchar_t * restrict src,
size_t size);
size_t
wcslcat(wchar_t
* restrict dst, const
wchar_t * restrict src,
size_t size);
DESCRIPTION
The
wcslcpy()
and wcslcat() functions copy and concatenate wide
strings respectively. They are designed to be safer, more consistent, and
less error prone replacements for
wcsncpy(3) and
wcsncat(3). Unlike those functions, wcslcpy()
and 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 size is larger than 0 or, in the
case of wcslcat(), as long as there is at least one
wide character free in dst). Note that a wide
character for the null wide character should be included in
size. Also note that wcslcpy()
and wcslcat() only operate on wide strings that are
terminated with a null wide character (L'\0'). This means that for
wcslcpy() src must be
terminated with a null wide character and for
wcslcat() both src and
dst must be terminated with a null wide character.
The
wcslcpy()
function copies up to size − 1 wide characters
from the wide string src to dst,
terminating the result with a null wide character.
The
wcslcat()
function appends the wide string src to the end of
dst. It will append at most size
− wcslen(dst) − 1 wide characters, terminating the result with
a null wide character.
If the src and dst strings overlap, the behavior is undefined.
RETURN VALUES
The wcslcpy() and
wcslcat() functions return the total length of the
wide string they tried to create. For wcslcpy() that
means the length of src. For
wcslcat() that means the initial length of
dst plus the length of src.
While this may seem somewhat confusing, it was done to make truncation
detection simple.
Note, however, that if wcslcat() traverses
size wide characters without finding a null wide
character, the length of the string is considered to be
size and the destination wide string will not be
terminated with a null wide character (since there was no space for it).
This keeps wcslcat() from running off the end of a
wide string. In practice this should not happen (as it means that either
size is incorrect or that dst is
not terminated with a null wide character). The check exists to prevent
potential security problems in incorrect code.
SEE ALSO
STANDARDS
The wcslcpy() and
wcslcat() functions conform to.
HISTORY
The wcslcpy() and
wcslcat() functions first appeared in
OpenBSD 3.8.
AUTHORS
The wcslcpy() and
wcslcat() functions are based on code by
Todd C. Miller
<millert@openbsd.org>.