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