NAME

wcslcat, wcslcpy — size-bounded wide string concatenation and copying

SYNOPSIS

[CX] #include <wchar.h>

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(); 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, strlcat, wcslen, wcsncat, wcsncpy

XBD <wchar.h>

CHANGE HISTORY

First released in Issue 8.