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