1.\" $OpenBSD: wctomb.3,v 1.6 2016/06/28 07:17:59 jmc Exp $ 2.\" $NetBSD: wctomb.3,v 1.3 2003/04/16 13:34:41 wiz Exp $ 3.\" 4.\" Copyright (c)2002 Citrus Project, 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: June 28 2016 $ 29.Dt WCTOMB 3 30.Os 31.Sh NAME 32.Nm wctomb 33.Nd converts a wide character to a multibyte character 34.Sh SYNOPSIS 35.In stdlib.h 36.Ft int 37.Fn wctomb "char * s" "wchar_t wchar" 38.Sh DESCRIPTION 39The 40.Fn wctomb 41converts the wide character 42.Fa wchar 43to the corresponding multibyte character, and stores it in the array 44pointed to by 45.Fa s . 46.Fn wctomb 47may store at most 48.Dv MB_CUR_MAX 49bytes in the array. 50.Pp 51In state-dependent encoding, 52.Fn wctomb 53may store the special sequence to change the conversion state 54before an actual multibyte character into the array pointed to by 55.Fa s . 56If 57.Fa wchar 58is a null wide character 59.Pq Sq \e0 , 60this function places its own internal state to an initial conversion state. 61.Pp 62Calling any other functions in 63.Em libc 64never change the internal 65state of 66.Fn wctomb , 67except for calling 68.Xr setlocale 3 69with the 70.Dv LC_CTYPE 71category changed to that of the current locale. 72Such 73.Xr setlocale 3 74calls cause the internal state of this function to be indeterminate. 75.Pp 76The behaviour of 77.Fn wctomb 78is affected by 79.Dv LC_CTYPE 80category of the current locale. 81.Pp 82There is a special case: 83.Bl -tag -width 012345678901 84.It s == NULL 85.Fn wctomb 86initializes its own internal state to an initial state, and 87determines whether the current encoding is state-dependent. 88This function returns 0 if the encoding is state-independent, 89otherwise non-zero. 90In this case, 91.Fa wchar 92is completely ignored. 93.El 94.Sh RETURN VALUES 95Normally, 96.Fn wctomb 97returns: 98.Bl -tag -width 012345678901 99.It positive 100Number of bytes for the valid multibyte character pointed to by 101.Fa s . 102There are no cases where the value returned is greater than 103the value of the 104.Dv MB_CUR_MAX 105macro. 106.It -1 107.Fa wchar 108is an invalid wide character. 109.El 110.Pp 111If 112.Fa s 113is equal to 114.Dv NULL , 115.Fn wctomb 116returns: 117.Bl -tag -width 0123456789 118.It 0 119The current encoding is state-independent. 120.It non-zero 121The current encoding is state-dependent. 122.El 123.Sh ERRORS 124No errors are defined. 125.Sh SEE ALSO 126.Xr setlocale 3 127.Sh STANDARDS 128The 129.Fn wctomb 130function conforms to 131.St -ansiC . 132