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 2017 Nexenta Systems, Inc. 13.\" 14.Dd March 28, 2017 15.Dt MBSTOWCS 3C 16.Os 17.Sh NAME 18.Nm mbstowcs , 19.Nm mbstowcs_l 20.Nd convert a multibyte character string to a wide-character string 21.Sh LIBRARY 22.Lb libc 23.Sh SYNOPSIS 24.In stdlib.h 25.Ft size_t 26.Fo mbstowcs 27.Fa "wchar_t *restrict pwcs" 28.Fa "const char *restrict s" 29.Fa "size_t n" 30.Fc 31.In stdlib.h 32.In xlocale.h 33.Ft size_t 34.Fo mbstowcs_l 35.Fa "wchar_t *restrict pwcs" 36.Fa "const char *restrict s" 37.Fa "size_t n" 38.Fa "locale_t loc" 39.Fc 40.Sh DESCRIPTION 41The 42.Fn mbstowcs 43function converts a multibyte character string 44.Fa s 45beginning in the initial conversion state into a wide-character string. 46If 47.Fa pwcs 48is not 49.Dv NULL , 50the converted characters are stored into array pointed to by 51.Fa pwcs . 52.Pp 53Conversion continues up to and including a terminating null character, which is 54also stored, or until 55.Fa n 56wide-characters have been stored into the array pointed to by 57.Fa pwcs . 58.Pp 59The behavior of 60.Fn mbstowcs 61function is affected by the 62.Ev LC_CTYPE 63category of the current locale. 64.Pp 65The 66.Fn mbstowcs_l 67function behaves identically to 68.Fn mbstowcs , 69except instead of using the current locale, it uses the locale as specified by 70.Fa loc . 71.Sh RETURN VALUES 72The 73.Fn mbstowcs 74and 75.Fn mbstowcs_l 76functions return the number of wide-characters successfully converted, not 77including the terminating null 78.Pq if any , 79or 80.Li \-1 81if conversion encounters a sequence of bytes that does not form a valid 82character. 83.Sh ERRORS 84The 85.Fn mbstowcs 86and 87.Fn mbstowcs_l 88functions will fail if: 89.Bl -tag -width Er 90.It Er EILSEQ 91An invalid multibyte sequence was detected. 92.It Er EINVAL 93The conversion state is invalid. 94.El 95.Sh INTERFACE STABILITY 96The 97.Fn mbstowcs 98function is 99.Sy Standard . 100The 101.Fn mbstowcs_l 102function is 103.Sy Uncommitted . 104.Sh MT-LEVEL 105.Sy MT-Safe 106.Sh SEE ALSO 107.Xr mbsnrtowcs 3C , 108.Xr mbtowc 3C , 109.Xr newlocale 3C , 110.Xr setlocale 3C , 111.Xr uselocale 3C , 112.Xr wcstombs 3C , 113.Xr attributes 7 , 114.Xr environ 7 , 115.Xr standards 7 116