16fdae1bdSYuri Pankov.\" 26fdae1bdSYuri Pankov.\" This file and its contents are supplied under the terms of the 36fdae1bdSYuri Pankov.\" Common Development and Distribution License ("CDDL"), version 1.0. 46fdae1bdSYuri Pankov.\" You may only use this file in accordance with the terms of version 56fdae1bdSYuri Pankov.\" 1.0 of the CDDL. 66fdae1bdSYuri Pankov.\" 76fdae1bdSYuri Pankov.\" A full copy of the text of the CDDL should have accompanied this 86fdae1bdSYuri Pankov.\" source. A copy of the CDDL is also available via the Internet at 96fdae1bdSYuri Pankov.\" http://www.illumos.org/license/CDDL. 106fdae1bdSYuri Pankov.\" 116fdae1bdSYuri Pankov.\" 126fdae1bdSYuri Pankov.\" Copyright 2017 Nexenta Systems, Inc. 136fdae1bdSYuri Pankov.\" 146fdae1bdSYuri Pankov.Dd March 28, 2017 156fdae1bdSYuri Pankov.Dt MBSTOWCS 3C 166fdae1bdSYuri Pankov.Os 176fdae1bdSYuri Pankov.Sh NAME 186fdae1bdSYuri Pankov.Nm mbstowcs , 196fdae1bdSYuri Pankov.Nm mbstowcs_l 206fdae1bdSYuri Pankov.Nd convert a multibyte character string to a wide-character string 216fdae1bdSYuri Pankov.Sh LIBRARY 226fdae1bdSYuri Pankov.Lb libc 236fdae1bdSYuri Pankov.Sh SYNOPSIS 246fdae1bdSYuri Pankov.In stdlib.h 256fdae1bdSYuri Pankov.Ft size_t 266fdae1bdSYuri Pankov.Fo mbstowcs 276fdae1bdSYuri Pankov.Fa "wchar_t *restrict pwcs" 286fdae1bdSYuri Pankov.Fa "const char *restrict s" 296fdae1bdSYuri Pankov.Fa "size_t n" 306fdae1bdSYuri Pankov.Fc 316fdae1bdSYuri Pankov.In stdlib.h 326fdae1bdSYuri Pankov.In xlocale.h 336fdae1bdSYuri Pankov.Ft size_t 346fdae1bdSYuri Pankov.Fo mbstowcs_l 356fdae1bdSYuri Pankov.Fa "wchar_t *restrict pwcs" 366fdae1bdSYuri Pankov.Fa "const char *restrict s" 376fdae1bdSYuri Pankov.Fa "size_t n" 386fdae1bdSYuri Pankov.Fa "locale_t loc" 396fdae1bdSYuri Pankov.Fc 406fdae1bdSYuri Pankov.Sh DESCRIPTION 416fdae1bdSYuri PankovThe 426fdae1bdSYuri Pankov.Fn mbstowcs 436fdae1bdSYuri Pankovfunction converts a multibyte character string 446fdae1bdSYuri Pankov.Fa s 456fdae1bdSYuri Pankovbeginning in the initial conversion state into a wide-character string. 466fdae1bdSYuri PankovIf 476fdae1bdSYuri Pankov.Fa pwcs 486fdae1bdSYuri Pankovis not 496fdae1bdSYuri Pankov.Dv NULL , 506fdae1bdSYuri Pankovthe converted characters are stored into array pointed to by 516fdae1bdSYuri Pankov.Fa pwcs . 526fdae1bdSYuri Pankov.Pp 536fdae1bdSYuri PankovConversion continues up to and including a terminating null character, which is 546fdae1bdSYuri Pankovalso stored, or until 556fdae1bdSYuri Pankov.Fa n 566fdae1bdSYuri Pankovwide-characters have been stored into the array pointed to by 576fdae1bdSYuri Pankov.Fa pwcs . 586fdae1bdSYuri Pankov.Pp 596fdae1bdSYuri PankovThe behavior of 606fdae1bdSYuri Pankov.Fn mbstowcs 616fdae1bdSYuri Pankovfunction is affected by the 626fdae1bdSYuri Pankov.Ev LC_CTYPE 636fdae1bdSYuri Pankovcategory of the current locale. 646fdae1bdSYuri Pankov.Pp 656fdae1bdSYuri PankovThe 666fdae1bdSYuri Pankov.Fn mbstowcs_l 676fdae1bdSYuri Pankovfunction behaves identically to 686fdae1bdSYuri Pankov.Fn mbstowcs , 696fdae1bdSYuri Pankovexcept instead of using the current locale, it uses the locale as specified by 706fdae1bdSYuri Pankov.Fa loc . 716fdae1bdSYuri Pankov.Sh RETURN VALUES 726fdae1bdSYuri PankovThe 736fdae1bdSYuri Pankov.Fn mbstowcs 746fdae1bdSYuri Pankovand 756fdae1bdSYuri Pankov.Fn mbstowcs_l 766fdae1bdSYuri Pankovfunctions return the number of wide-characters successfully converted, not 776fdae1bdSYuri Pankovincluding the terminating null 786fdae1bdSYuri Pankov.Pq if any , 796fdae1bdSYuri Pankovor 806fdae1bdSYuri Pankov.Li \-1 816fdae1bdSYuri Pankovif conversion encounters a sequence of bytes that does not form a valid 826fdae1bdSYuri Pankovcharacter. 836fdae1bdSYuri Pankov.Sh ERRORS 846fdae1bdSYuri PankovThe 856fdae1bdSYuri Pankov.Fn mbstowcs 866fdae1bdSYuri Pankovand 876fdae1bdSYuri Pankov.Fn mbstowcs_l 886fdae1bdSYuri Pankovfunctions will fail if: 896fdae1bdSYuri Pankov.Bl -tag -width Er 906fdae1bdSYuri Pankov.It Er EILSEQ 916fdae1bdSYuri PankovAn invalid multibyte sequence was detected. 926fdae1bdSYuri Pankov.It Er EINVAL 936fdae1bdSYuri PankovThe conversion state is invalid. 946fdae1bdSYuri Pankov.El 956fdae1bdSYuri Pankov.Sh INTERFACE STABILITY 966fdae1bdSYuri PankovThe 976fdae1bdSYuri Pankov.Fn mbstowcs 986fdae1bdSYuri Pankovfunction is 996fdae1bdSYuri Pankov.Sy Standard . 1006fdae1bdSYuri PankovThe 1016fdae1bdSYuri Pankov.Fn mbstowcs_l 1026fdae1bdSYuri Pankovfunction is 103bccbd30bSPeter Tribble.Sy Uncommitted . 1046fdae1bdSYuri Pankov.Sh MT-LEVEL 1056fdae1bdSYuri Pankov.Sy MT-Safe 1066fdae1bdSYuri Pankov.Sh SEE ALSO 1076fdae1bdSYuri Pankov.Xr mbsnrtowcs 3C , 1086fdae1bdSYuri Pankov.Xr mbtowc 3C , 1096fdae1bdSYuri Pankov.Xr newlocale 3C , 1106fdae1bdSYuri Pankov.Xr setlocale 3C , 1116fdae1bdSYuri Pankov.Xr uselocale 3C , 1126fdae1bdSYuri Pankov.Xr wcstombs 3C , 113*bbf21555SRichard Lowe.Xr attributes 7 , 114*bbf21555SRichard Lowe.Xr environ 7 , 115*bbf21555SRichard Lowe.Xr standards 7 116