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