1.\" $NetBSD: src/lib/libc/locale/wctomb.3,v 1.4 2004/01/24 16:58:54 wiz Exp $ 2.\" $DragonFly: src/lib/libc/locale/wctomb.3,v 1.1 2005/03/12 00:18:01 joerg 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 February 3, 2002 29.Dt WCTOMB 3 30.Os 31.Sh NAME 32.Nm wctomb 33.Nd converts a wide character to a multibyte character 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In stdlib.h 38.Ft int 39.Fn wctomb "char * s" "const wchar_t wchar" 40.Sh DESCRIPTION 41The 42.Fn wctomb 43converts the wide character 44.Fa wchar 45to the corresponding multibyte character, and stores it in the array 46pointed to by 47.Fa s . 48.Fn wctomb 49may store at most 50.Dv MB_CUR_MAX 51bytes in the array. 52.Pp 53In state-dependent encoding, 54.Fn wctomb 55may store the special sequence to change the conversion state 56before an actual multibyte character into the array pointed to by 57.Fa s . 58If 59.Fa wchar 60is a null wide character 61.Pq Sq \e0 , 62this function sets its own internal state to an initial conversion state. 63.Pp 64Calling any other functions in 65.Lb libc 66never changes the internal state of 67.Fn wctomb , 68except changing the 69.Dv LC_CTYPE 70category of the current locale by calling 71.Xr setlocale 3 . 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 the 79.Dv LC_CTYPE 80category of the current locale. 81.Pp 82There is one 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 that the value returned is greater than 103.Fa n 104or the value of the 105.Dv MB_CUR_MAX 106macro. 107.It -1 108.Fa wchar 109is an invalid wide character. 110.El 111.Pp 112If 113.Fa s 114is equal to 115.Dv NULL , 116.Fn mbtowc 117returns: 118.Bl -tag -width 0123456789 119.It 0 120The current encoding is state-independent. 121.It non-zero 122The current encoding is state-dependent. 123.El 124.Sh ERRORS 125No errors are defined. 126.Sh SEE ALSO 127.Xr setlocale 3 128.Sh STANDARDS 129The 130.Fn wctomb 131function conforms to 132.St -ansiC . 133