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