NAME
wcslcat wcslcpy
— size-bounded wide string concatenation and
copying
SYNOPSIS
size_t wcslcat(wchar_t *restrict dst, const wchar_t *restrict src,
size_t dstsize);
size_t wcslcpy(wchar_t *restrict dst, const wchar_t *restrict src,
size_t dstsize);
DESCRIPTION
The wcslcpy () and
wcslcat () functions copy and concatenate wide
strings, stopping when either a terminating null wide-character code in the
source wide string is encountered or the specified full size (in
wide-character codes) of the destination buffer is reached. They null
terminate the result if there is room. The application should ensure that
room for the terminating null wide-character code is included in
dstsize.
The wcslcpy () function shall copy not more than dstsize - 1 wide-character codes from the wide string pointed to by src to the array pointed to by dst; a terminating null wide-character code in src and wide-character codes that follow it shall not be copied. A terminating null wide-character code shall be appended to the result, unless dstsize is 0. If copying takes place between objects that overlap, the behavior is undefined.
The wcslcat () function shall
append not more than dstsize -
wcslen (
dst) - 1 wide-character codes from the wide string pointed
to by src to the end of the wide string pointed to by
dst; a terminating null wide-character code in
src and wide-character codes that follow it shall not be
appended. The initial wide-character code of src shall
overwrite the null wide-character code at the end of dst.
A terminating null wide-character code shall be appended to the result,
unless its location would be at or beyond dst +
dstsize. If copying takes place between objects that
overlap, the behavior is undefined.
The wcslcpy () and
wcslcat () functions shall not change the setting of
errno on valid
input.
RETURN VALUE
Upon successful completion, the wcslcpy () function shall return the length of the wide string pointed to by src; that is, the number of wide-character codes in the wide string, not including the terminating null wide-character code.
Upon successful completion, the wcslcat ()
function shall return the initial length of the wide string pointed to by
dst plus the length of the wide string pointed to by
src.
No return values are reserved to indicate an error.
ERRORS
No errors are defined.
EXAMPLES
None.
APPLICATION USAGE
The return value of the wcslcpy () and
wcslcat () functions follows the same convention as
snprintf(3); that is, they return the total length (in
wide-character codes) of the wide string they tried to create. If the return
value is greater than or equal to dstsize, the output wide
string has been truncated.
RATIONALE
None.
FUTURE DIRECTIONS
None.
SEE ALSO
fprintf(3), strlcat(3), wcslen(3), wcsncat(3), wcsncpy(3)
XBD <wchar.h>
CHANGE HISTORY
First released in Issue 8.