1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2025 Oxide Computer Company 13.\" 14.Dd January 5, 2025 15.Dt WCSLCAT 3C 16.Os 17.Sh NAME 18.Nm wcslcat 19.Nd concatenate wide-character strings 20.Sh LIBRARY 21.Lb libc 22.Sh SYNOPSIS 23.In wchar.h 24.Ft size_t 25.Fo wcslcat 26.Fa "wchar_t *restrict dst" 27.Fa "wchar_t *restrict src" 28.Fa "size_t dstlen" 29.Fc 30.Sh DESCRIPTION 31The 32.Fn wcslcat 33function is the wide-character version of 34.Xr strlcat 3C . 35It concatenates the wide-character string in 36.Fa src 37with the wide-character string in 38.Fa dst , 39while ensuring that 40.Fa dst 41is always properly terminated with the null wide-character 42.Pq L'\e0' . 43.Pp 44Wide characters in 45.Fa src 46will be appended to 47.Fa dst 48starting at the end of an existing wide-character string in 49.Fa dst , 50replacing an existing terminating null wide-character. 51Put differently, copying will begin at the result of a call to the 52equivalent of 53.Em wcsnlen(dst, dstlen) . 54Characters will be copied until either a terminating null wide-character 55is found in 56.Fa src 57or the destination buffer would be full, whichever comes first. 58This may result in a truncated portion of 59.Fa src , 60or none at all, appearing in 61.Fa dst . 62.Pp 63A terminating null wide-character is inserted unless the initial 64wide-character string in 65.Fa dst 66contained 67.Fa dstlen 68characters without a terminating null wide-character. 69However, if 70.Fa dstlen 71is zero, then 72.Fa dst 73will not be touched. 74.Sh RETURN VALUES 75The 76.Fn wcslcat 77function returns the total number of wide characters that would be required to 78store the concatenated wide-character string, excluding the terminating null 79wide-character. 80.Sh EXAMPLES 81.Sy Example 1 82Checking for overflow 83.Pp 84The following example shows how one would check if string concatenation 85with the 86.Fn wcslcat 87function resulted in overflow. 88Note, the use of 89.Sq >= 90down below is required because the 91.Fn wcslcat 92function always ensures that the buffer has a terminating null wide-character. 93.Bd -literal -offset 2 94#include <wchar.h> 95#include <err.h> 96#include <stdlib.h> 97 98#define BUFLEN 32 99wchar_t buf[BUFLEN] = { L'\e0' }; 100 101\&... 102 103static void 104concat(const wchar_t *src) 105{ 106 if (wcslcat(buf, src, BUFLEN) >= BUFLEN) { 107 errx(EXIT_FAILURE, "overflow detected!"); 108 } 109} 110 111\&... 112.Ed 113.Sh INTERFACE STABILITY 114.Sy Committed 115.Sh MT-LEVEL 116.Sy MT-Safe 117.Sh SEE ALSO 118.Xr strlcat 3C , 119.Xr wcslcpy 3C 120