WCSLCPY(3) FreeBSD Library Functions Manual WCSLCPY(3)
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
strlcpy(3), swprintf(3), wcsncat(3), wcsncpy(3)
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
<
[email protected]>.
FreeBSD 14.1-RELEASE-p8 August 7, 2024 FreeBSD 14.1-RELEASE-p8