WCSLCPY(3) | 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 <millert@openbsd.org>.

August 7, 2024 | Debian