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 WCSLCPY 3C 16.Os 17.Sh NAME 18.Nm wcslcpy 19.Nd copy a wide-character string 20.Sh LIBRARY 21.Lb libc 22.Sh SYNOPSIS 23.In wchar.h 24.Ft size_t 25.Fo wcslcpy 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 wcslcpy 33function is the wide-character version of 34.Xr strlcpy 3C . 35It copies wide characters from 36.Fa src 37to 38.Fa dst , 39while ensuring that 40.Fa dst 41is always properly terminated with the null wide-character 42.Pq L'\e0' . 43.Pp 44Characters from 45.Fa src 46are copied until either the null wide-character is found in 47.Fa src 48or 49.Fa dstlen 50- 1 wide characters have been copied, whichever comes first. 51In the latter case, the copy of 52.Fa src 53in 54.Fa dst 55will be truncated. 56If 57.Fa dstlen 58is zero, then no characters are copied. 59.Sh RETURN VALUES 60The 61.Fn wcslcpy 62function always returns the total number of wide characters in 63.Fa src , 64excluding the terminating null wide-character. 65.Sh EXAMPLES 66.Sy Example 1 67Checking for overflow 68.Pp 69The following example shows how one would check if a copy using the 70.Fn wcslcpy 71function would have overflowed a fixed size buffer. 72Note, the use of 73.Sq >= 74down below is required because the 75.Fn wcslcpy 76function always ensures that the buffer has a terminating null wide-character. 77.Bd -literal -offset 2 78#include <wchar.h> 79#include <stdio.h> 80 81#define BUFLEN 32 82wchar_t buf[BUFLEN]; 83 84\&... 85 if (wcslcpy(buf, src, BUFLEN) >= BUFLEN) { 86 (void) fprintf(stderr, "overflow detected!"); 87 goto out; 88 } 89\&... 90.Ed 91.Sh INTERFACE STABILITY 92.Sy Committed 93.Sh MT-LEVEL 94.Sy MT-Safe 95.Sh SEE ALSO 96.Xr strlcpy 3C , 97.Xr wcslcat 3C 98