WCSLCAT(3C) Standard C Library Functions WCSLCAT(3C)

NAME

wcslcat - concatenate wide-character strings

LIBRARY

Standard C Library (libc, -lc)

SYNOPSIS

#include <wchar.h>

size_t
wcslcat(wchar_t *restrict dst, wchar_t *restrict src, size_t dstlen);

DESCRIPTION

The wcslcat() function is the wide-character version of strlcat(3C). It
concatenates the wide-character string in src with the wide-character
string in dst, while ensuring that dst is always properly terminated with
the null wide-character (L'\0').

Wide characters in src will be appended to dst starting at the end of an
existing wide-character string in dst, replacing an existing terminating
null wide-character. Put differently, copying will begin at the result of
a call to the equivalent of wcsnlen(dst, dstlen). Characters will be
copied until either a terminating null wide-character is found in src or
the destination buffer would be full, whichever comes first. This may
result in a truncated portion of src, or none at all, appearing in dst.

A terminating null wide-character is inserted unless the initial wide-
character string in dst contained dstlen characters without a terminating
null wide-character. However, if dstlen is zero, then dst will not be
touched.

RETURN VALUES

The wcslcat() function returns the total number of wide characters that
would be required to store the concatenated wide-character string,
excluding the terminating null wide-character.

EXAMPLES

Example 1 Checking for overflow

The following example shows how one would check if string concatenation
with the wcslcat() function resulted in overflow. Note, the use of `>='
down below is required because the wcslcat() function always ensures that
the buffer has a terminating null wide-character.

#include <wchar.h>
#include <err.h>
#include <stdlib.h>

#define BUFLEN 32
wchar_t buf[BUFLEN] = { L'\0' };

...

static void
concat(const wchar_t *src)
{
if (wcslcat(buf, src, BUFLEN) >= BUFLEN) {
errx(EXIT_FAILURE, "overflow detected!");
}
}

...

INTERFACE STABILITY

Committed

MT-LEVEL
MT-Safe

SEE ALSO

strlcat(3C), wcslcpy(3C)

illumos January 5, 2025 illumos