1.\" $NetBSD: wctomb.3,v 1.2 2002/03/18 07:56:30 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.Fd #include \*[Lt]stdlib.h\*[Gt] 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 store it to the array 45pointed by 46.Fa s . 47The 48.Fn wctomb 49may store at most MB_CUR_MAX bytes to the array. 50.Pp 51In state-dependent encoding, 52the 53.Fn wctomb 54may store the special sequence to change the conversion state 55before an actual multibyte character into the array pointed 56.Fa s . 57If 58.Fa wchar 59is null wide character (L\'\\0\'), 60this function places its own internal state to an initial conversion state. 61.Pp 62Calling any other functions in the 63.Lb libc 64never change the internal 65state of the 66.Fn wctomb , 67except for calling 68.Xr setlocale 3 69with changing LC_CTYPE category of the current locale. 70Such 71.Xr setlocale 3 72call causes the internal state of this function to be indeterminate. 73.Pp 74The behaviour of the 75.Fn wctomb 76is affected by LC_CTYPE category of the current locale. 77.Pp 78There is a special case: 79.Bl -tag -width 012345678901 80.It s == NULL 81.Fn wctomb 82initializes its own internal state to an initial state, and 83determines whether the current encoding is state-dependent. 84This function returns 0 if the encoding is state-independent, 85otherwise non-zero. 86In this case, 87.Fa wchar 88is completely ignored. 89.El 90.Sh RETURN VALUES 91In the usual case, the 92.Fn wctomb 93returns: 94.Bl -tag -width 012345678901 95.It positive 96number of bytes for the valid multibyte character pointed by 97.Fa s . 98There is no cases that the value returned is greater than 99.Fa n 100or the value of MB_CUR_MAX macro. 101.It -1 102.Fa wchar 103is an invalid wide character. 104.El 105.Pp 106In the case that 107.Fa s 108is equal to NULL, the 109.Fn mbtowc 110returns: 111.Bl -tag -width 0123456789 112.It 0 113The current encoding is state-independent. 114.It non-zero 115The current encoding is state-dependent. 116.El 117.Sh ERRORS 118No errors are defined. 119.Sh SEE ALSO 120.Xr setlocale 3 121.Sh STANDARDS 122The 123.Fn wctomb 124function conforms to 125.St -ansiC . 126