.\" $OpenBSD: wcrtomb.3,v 1.12 2023/09/12 08:33:37 jsg Exp $
.\" $NetBSD: wcrtomb.3,v 1.4 2003/09/08 17:54:31 wiz Exp $
.\"
.\" Copyright (c)2023 Ingo Schwarze <schwarze@openbsd.org>
.\" Copyright (c)2002 Citrus Project,
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: September 12 2023 $
.Dt WCRTOMB 3
.Os
.Sh NAME
.Nm wcrtomb ,
.Nm c32rtomb
.Nd convert a wide character to a multibyte character
.Sh SYNOPSIS
.In wchar.h
.Ft size_t
.Fo wcrtomb
.Fa "const char * restrict s"
.Fa "wchar_t wc"
.Fa "mbstate_t * restrict mbs"
.Fc
.In uchar.h
.Ft size_t
.Fo c32rtomb
.Fa "char * restrict s"
.Fa "char32_t wc"
.Fa "mbstate_t * restrict mbs"
.Fc
.Sh DESCRIPTION
.Fn wcrtomb
and
.Fn c32rtomb
convert the wide character
.Fa wc
to the corresponding multibyte character, and store up to
.Dv MB_CUR_MAX
bytes in the array pointed to by
.Fa s
if
.Fa s
is not a
.Dv NULL
pointer.
The interpretation of
.Fa wc
is implementation-defined.
On
.Ox ,
.Vt wchar_t
and
.Vt char32_t
are of the same width and both are always interpreted as Unicode codepoints.
.Pp
The output encoding that
.Fn wcrtomb
and
.Fn c32rtomb
use in
.Fa s
is determined by the
.Dv LC_CTYPE
category of the current locale.
.Ox
only supports UTF-8 and ASCII output,
and these functions are only useful for UTF-8.
.Pp
The following arguments cause special processing:
.Bl -tag -width 012345678901
.It Fa wc No == 0
A NUL byte is stored to
.Pf * Fa s
and the state object pointed to by
.Fa mbs
is reset to the initial state.
On operating systems other than
.Ox
that support state-dependent multibyte encodings, a special byte sequence
.Pq Dq shift sequence
is written before the NUL byte to return to the initial state
if that is required by the output encoding
and by the current output encoding state.
.It Fa mbs No == Dv NULL
.Fn mbrtowc
and
.Fn c32rtomb
each use their own internal state object instead of the
.Fa mbs
argument.
Both internal state objects are initialized at startup time of the program,
and no other
.Em libc
function ever changes either of them.
.It Fa s No == Dv NULL
The object pointed to by
.Fa mbs ,
or the internal object if
.Fa mbs
is a
.Dv NULL
pointer, is reset to the initial state,
.Fa wc
is ignored, and 1 is returned.
.El
.Sh RETURN VALUES
.Fn wcrtomb
and
.Fn c32rtomb
return the number of bytes (including any shift sequences)
which are stored in the array pointed to by
.Fa s ,
or 1 if
.Fa s
is
.Dv NULL .
If
.Fa wc
is not a valid wide character
or if it cannot be represented in the multibyte encoding selected with
.Dv LC_CTYPE ,
both functions return
.Po Vt size_t Pc Ns \-1
and set
.Va errno
to indicate the error.
.Sh ERRORS
.Fn wcrtomb
and
.Fn c32rtomb
cause an error in the following cases:
.Bl -tag -width Er
.It Bq Er EILSEQ
.Fa wc
is not a valid wide character or cannot be represented using
.Dv LC_CTYPE .
.It Bq Er EINVAL
.Fa mbs
points to an invalid or uninitialized
.Vt mbstate_t
object.
.El
.Sh SEE ALSO
.Xr mbrtowc 3 ,
.Xr setlocale 3 ,
.Xr wctomb 3
.Sh STANDARDS
.Fn wcrtomb
conforms to
.St -isoC-amd1 .
The restrict qualifier was added at
.St -isoC-99 .
.Pp
.Fn c32rtomb
conforms to
.St -isoC-2011 .
.Sh HISTORY
.Fn wcrtomb
has been available since
.Ox 3.8
and has provided support for UTF-8 since
.Ox 4.8 .
.Pp
.Fn c32rtomb
has been available since
.Ox 7.4 .