1.\" $NetBSD: src/lib/libc/locale/wcrtomb.3,v 1.6 2004/09/27 07:07:04 yamt Exp $ 2.\" $DragonFly: src/lib/libc/locale/wcrtomb.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 4, 2002 29.Dt WCRTOMB 3 30.Os 31.\" ---------------------------------------------------------------------- 32.Sh NAME 33.Nm wcrtomb 34.Nd converts a wide character to a multibyte character (restartable) 35.\" ---------------------------------------------------------------------- 36.Sh LIBRARY 37.Lb libc 38.\" ---------------------------------------------------------------------- 39.Sh SYNOPSIS 40.In wchar.h 41.Ft size_t 42.Fn wcrtomb "char * restrict s" "wchar_t wc" "mbstate_t * restrict ps" 43.\" ---------------------------------------------------------------------- 44.Sh DESCRIPTION 45.Fn wcrtomb 46converts the wide character given by 47.Fa wc 48to the corresponding multibyte character, and stores it in the array 49pointed to by 50.Fa s 51unless 52.Fa s 53is a null pointer. 54This function will modify the first at most 55.Dv MB_CUR_MAX 56bytes of the array pointed to by 57.Fa s . 58.Pp 59The behaviour of 60.Fn wcrtomb 61is affected by the 62.Dv LC_CTYPE 63category of the current locale. 64.Pp 65These are the special cases: 66.Bl -tag -width 012345678901 67.It "wc == 0" 68For state-dependent encodings, 69.Fn wcrtomb 70stores a null byte preceded by special byte sequence (if any) 71to return to an initial state in the array pointed to by 72.Fa s , 73and the state object pointed to by 74.Fa ps 75also returns to an initial state. 76.It "s == NULL" 77.Fn wcrtomb 78just places 79.Fa ps 80into a initial state. 81It is equivalent to the following call: 82.Bd -literal -offset indent 83wcrtomb(buf, L'\\0', ps); 84.Ed 85.Pp 86Here, 87.Fa buf 88is a dummy buffer. 89In this case, 90.Fa wc 91is ignored. 92.It "ps == NULL" 93.Fn mbrtowc 94uses its own internal state object to keep the conversion state, 95instead of 96.Fa ps 97mentioned in this manual page. 98.Pp 99Calling any other functions in 100.Lb libc 101never changes the internal 102state of 103.Fn mbrtowc , 104which is initialized at startup time of the program. 105.El 106.\" ---------------------------------------------------------------------- 107.Sh RETURN VALUES 108.Fn wcrtomb 109returns: 110.Bl -tag -width 012345678901 111.It "positive" 112The number of bytes (including any shift sequences) 113which are stored in the array. 114.It "(size_t)-1" 115.Fa wc 116is not a valid wide character. 117In this case, 118.Fn wcrtomb 119also sets 120.Va errno 121to indicate the error. 122.El 123.\" ---------------------------------------------------------------------- 124.Sh ERRORS 125.Fn wcrtomb 126may cause an error in the following case: 127.Bl -tag -width Er 128.It Bq Er EILSEQ 129.Fa wc 130is not a valid wide character. 131.It Bq Er EINVAL 132.Fa ps 133points to an invalid or uninitialized mbstate_t object. 134.El 135.\" ---------------------------------------------------------------------- 136.Sh SEE ALSO 137.Xr setlocale 3 , 138.Xr wctomb 3 139.\" ---------------------------------------------------------------------- 140.Sh STANDARDS 141The 142.Fn wcrtomb 143function conforms to 144.St -isoC-amd1 . 145The restrict qualifier is added at 146.St -isoC-99 . 147