166492cf0SYuri Pankov.\" 2*4ebabf21SRobert Mustacchi.\" This file and its contents are supplied under the terms of the 3*4ebabf21SRobert Mustacchi.\" Common Development and Distribution License ("CDDL"), version 1.0. 4*4ebabf21SRobert Mustacchi.\" You may only use this file in accordance with the terms of version 5*4ebabf21SRobert Mustacchi.\" 1.0 of the CDDL. 666492cf0SYuri Pankov.\" 7*4ebabf21SRobert Mustacchi.\" A full copy of the text of the CDDL should have accompanied this 8*4ebabf21SRobert Mustacchi.\" source. A copy of the CDDL is also available via the Internet at 9*4ebabf21SRobert Mustacchi.\" http://www.illumos.org/license/CDDL. 1066492cf0SYuri Pankov.\" 1166492cf0SYuri Pankov.\" 12*4ebabf21SRobert Mustacchi.\" Copyright 2020 Oxide Computer Company 1366492cf0SYuri Pankov.\" 14*4ebabf21SRobert Mustacchi.Dd June 17, 2020 15*4ebabf21SRobert Mustacchi.Dt WCSWIDTH 3C 16*4ebabf21SRobert Mustacchi.Os 17*4ebabf21SRobert Mustacchi.Sh NAME 18*4ebabf21SRobert Mustacchi.Nm wcswidth , 19*4ebabf21SRobert Mustacchi.Nm wcswidth_l 20*4ebabf21SRobert Mustacchi.Nd determine number of columns for wide-character string 21*4ebabf21SRobert Mustacchi.Sh SYNOPSIS 22*4ebabf21SRobert Mustacchi.In wchar.h 23*4ebabf21SRobert Mustacchi.Ft int 24*4ebabf21SRobert Mustacchi.Fo wcswidth 25*4ebabf21SRobert Mustacchi.Fa "const wchar_t *str" 26*4ebabf21SRobert Mustacchi.Fa "size_t len" 27*4ebabf21SRobert Mustacchi.Fc 28*4ebabf21SRobert Mustacchi.In wchar.h 29*4ebabf21SRobert Mustacchi.In xlocale.h 30*4ebabf21SRobert Mustacchi.Ft int 31*4ebabf21SRobert Mustacchi.Fo wcswidth_l 32*4ebabf21SRobert Mustacchi.Fa "const wchar_t *str" 33*4ebabf21SRobert Mustacchi.Fa "size_t len" 34*4ebabf21SRobert Mustacchi.Fa "locale_t loc" 35*4ebabf21SRobert Mustacchi.Fc 36*4ebabf21SRobert Mustacchi.Sh DESCRIPTION 37*4ebabf21SRobert MustacchiThe 38*4ebabf21SRobert Mustacchi.Fn wcswidth 39*4ebabf21SRobert Mustacchiand 40*4ebabf21SRobert Mustacchi.Fn wcswidth_l 41*4ebabf21SRobert Mustacchifunctions count the total number of columns that are required 42*4ebabf21SRobert Mustacchito display the contents of the wide-character string 43*4ebabf21SRobert Mustacchi.Fa str . 44*4ebabf21SRobert MustacchiFor each wide-character in the string 45*4ebabf21SRobert Mustacchi.Fa str , 46*4ebabf21SRobert Mustacchithe equivalent of 47*4ebabf21SRobert Mustacchi.Xr wcwidth 3C 48*4ebabf21SRobert Mustacchiis called and the result summed to a running total which is returned. 49*4ebabf21SRobert Mustacchi.Pp 50*4ebabf21SRobert MustacchiUp to 51*4ebabf21SRobert Mustacchi.Fa len 52*4ebabf21SRobert Mustacchiwide-characters from 53*4ebabf21SRobert Mustacchi.Fa str 54*4ebabf21SRobert Mustacchiwill be evaluated; however, the functions will stop iterating if they 55*4ebabf21SRobert Mustacchiencounter the null wide-character 56*4ebabf21SRobert Mustacchi.Pq L'\e0' . 57*4ebabf21SRobert Mustacchi.Pp 58*4ebabf21SRobert MustacchiThe wide-characters in 59*4ebabf21SRobert Mustacchi.Fa str 60*4ebabf21SRobert Mustacchimust be valid characters in the current locale or in the case of the 61*4ebabf21SRobert Mustacchi.Fn wcswidth_l 62*4ebabf21SRobert Mustacchifunction, the locale specified by 63*4ebabf21SRobert Mustacchi.Fa loc . 64*4ebabf21SRobert MustacchiThe functions will fail if any of the wide-characters in 65*4ebabf21SRobert Mustacchi.Fa str 66*4ebabf21SRobert Mustacchiare valid in the current 67*4ebabf21SRobert Mustacchilocale, but considered non-printable 68*4ebabf21SRobert Mustacchi.Po 69*4ebabf21SRobert Mustacchias in 70*4ebabf21SRobert Mustacchi.Xr iswprint 3C 71*4ebabf21SRobert Mustacchiwould fail for the character 72*4ebabf21SRobert Mustacchi.Pc 73*4ebabf21SRobert Mustacchior the wide-character does not represent a valid character in the 74*4ebabf21SRobert Mustacchilocale. 75*4ebabf21SRobert Mustacchi.Sh RETURN VALUES 76*4ebabf21SRobert MustacchiUpon successful completion, the 77*4ebabf21SRobert Mustacchi.Fn wcswidth 78*4ebabf21SRobert Mustacchiand 79*4ebabf21SRobert Mustacchi.Fn wcswidth_l 80*4ebabf21SRobert Mustacchifunctions return the total number of columns that are required to 81*4ebabf21SRobert Mustacchidisplay the wide-character string. 82*4ebabf21SRobert MustacchiOtherwise, 83*4ebabf21SRobert Mustacchi.Sy -1 84*4ebabf21SRobert Mustacchiis returned to indicate that an invalid or non-printable wide-character 85*4ebabf21SRobert Mustacchiwas encountered. 86*4ebabf21SRobert Mustacchi.Sh EXAMPLES 87*4ebabf21SRobert Mustacchi.Sy Example 1 88*4ebabf21SRobert MustacchiUsing the 89*4ebabf21SRobert Mustacchi.Fn wcswidth 90*4ebabf21SRobert Mustacchifunction to count characters in a string. 91*4ebabf21SRobert Mustacchi.Bd -literal 92c10c16deSRichard Lowe#include <wchar.h> 93*4ebabf21SRobert Mustacchi#include <stdio.h> 94c10c16deSRichard Lowe 95*4ebabf21SRobert Mustacchiint 96*4ebabf21SRobert Mustacchimain(void) 97*4ebabf21SRobert Mustacchi{ 98*4ebabf21SRobert Mustacchi wchar_t *str = L"Hello world"; 99*4ebabf21SRobert Mustacchi int ret = wcswidth(str, wcslen(str)); 100*4ebabf21SRobert Mustacchi (void) printf("wcswidth returned: %d\n", ret); 101*4ebabf21SRobert Mustacchi return (0); 102*4ebabf21SRobert Mustacchi} 103*4ebabf21SRobert Mustacchi.Ed 104*4ebabf21SRobert Mustacchi.Pp 105*4ebabf21SRobert MustacchiWhen compiled and run, this program outputs: 106*4ebabf21SRobert Mustacchi.Bd -literal 107*4ebabf21SRobert Mustacchi$ gcc -Wall -Wextra example.c 108*4ebabf21SRobert Mustacchi$ ./a.out 109*4ebabf21SRobert Mustacchiwcswidth returned: 11 110*4ebabf21SRobert Mustacchi.Ed 111*4ebabf21SRobert Mustacchi.Sh MT-LEVEL 112*4ebabf21SRobert MustacchiThe 113*4ebabf21SRobert Mustacchi.Fn wcswidth 114*4ebabf21SRobert Mustacchifunction is 115*4ebabf21SRobert Mustacchi.Sy MT-Safe 116*4ebabf21SRobert Mustacchias long as the thread-specific or global locale is not changed while it 117*4ebabf21SRobert Mustacchiis running. 118*4ebabf21SRobert Mustacchi.Pp 119*4ebabf21SRobert MustacchiThe 120*4ebabf21SRobert Mustacchi.Fn wcswidth_l 121*4ebabf21SRobert Mustacchifunction is 122*4ebabf21SRobert Mustacchi.Sy MT-Safe 123*4ebabf21SRobert Mustacchias long as the locale 124*4ebabf21SRobert Mustacchi.Fa loc 125*4ebabf21SRobert Mustacchiis not freed while the function is running. 126*4ebabf21SRobert Mustacchi.Sh INTERFACE STABILITY 127*4ebabf21SRobert Mustacchi.Sy Committed 128*4ebabf21SRobert Mustacchi.Sh SEE ALSO 129*4ebabf21SRobert Mustacchi.Xr iswprint 3C , 130*4ebabf21SRobert Mustacchi.Xr newlocale 3C , 131*4ebabf21SRobert Mustacchi.Xr setlocale 3C , 132*4ebabf21SRobert Mustacchi.Xr uselocale 3C , 133*4ebabf21SRobert Mustacchi.Xr wcwidth 3C 134