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