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 2024 Oxide Computer Company 13.\" 14.Dd September 15, 2024 15.Dt WCSWIDTH 3C 16.Os 17.Sh NAME 18.Nm wcswidth , 19.Nm wcswidth_l 20.Nd determine number of columns for wide-character string 21.Sh SYNOPSIS 22.In wchar.h 23.Ft int 24.Fo wcswidth 25.Fa "const wchar_t *str" 26.Fa "size_t len" 27.Fc 28.In wchar.h 29.In xlocale.h 30.Ft int 31.Fo wcswidth_l 32.Fa "const wchar_t *str" 33.Fa "size_t len" 34.Fa "locale_t loc" 35.Fc 36.Sh DESCRIPTION 37The 38.Fn wcswidth 39and 40.Fn wcswidth_l 41functions count the total number of columns that are required 42to display the contents of the wide-character string 43.Fa str . 44For each wide-character in the string 45.Fa str , 46the equivalent of 47.Xr wcwidth 3C 48is called and the result summed to a running total which is returned. 49.Pp 50Up to 51.Fa len 52wide-characters from 53.Fa str 54will be evaluated; however, the functions will stop iterating if they 55encounter the null wide-character 56.Pq L'\e0' . 57.Pp 58The wide-characters in 59.Fa str 60must be valid characters in the current locale or in the case of the 61.Fn wcswidth_l 62function, the locale specified by 63.Fa loc . 64The functions will fail if any of the wide-characters in 65.Fa str 66are valid in the current 67locale, but considered non-printable 68.Po 69as in 70.Xr iswprint 3C 71would fail for the character 72.Pc 73or the wide-character does not represent a valid character in the 74locale. 75.Sh RETURN VALUES 76Upon successful completion, the 77.Fn wcswidth 78and 79.Fn wcswidth_l 80functions return the total number of columns that are required to 81display the wide-character string. 82Otherwise, 83.Sy -1 84is returned to indicate that an invalid or non-printable wide-character 85was encountered. 86.Sh EXAMPLES 87.Sy Example 1 88Using the 89.Fn wcswidth 90function to count characters in a string. 91.Bd -literal 92#include <wchar.h> 93#include <stdio.h> 94 95int 96main(void) 97{ 98 wchar_t *str = L"Hello world"; 99 int ret = wcswidth(str, wcslen(str)); 100 (void) printf("wcswidth returned: %d\en", ret); 101 return (0); 102} 103.Ed 104.Pp 105When compiled and run, this program outputs: 106.Bd -literal 107$ gcc -Wall -Wextra example.c 108$ ./a.out 109wcswidth returned: 11 110.Ed 111.Sh MT-LEVEL 112The 113.Fn wcswidth 114function is 115.Sy MT-Safe 116as long as the thread-specific or global locale is not changed while it 117is running. 118.Pp 119The 120.Fn wcswidth_l 121function is 122.Sy MT-Safe 123as long as the locale 124.Fa loc 125is not freed while the function is running. 126.Sh INTERFACE STABILITY 127.Sy Committed 128.Sh SEE ALSO 129.Xr iswprint 3C , 130.Xr newlocale 3C , 131.Xr setlocale 3C , 132.Xr uselocale 3C , 133.Xr wcwidth 3C 134