1.\" $NetBSD: c32rtomb.3,v 1.11 2024/08/20 20:36:30 riastradh Exp $ 2.\" 3.\" Copyright (c) 2024 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 16.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 17.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 18.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd August 14, 2024 28.Dt C32RTOMB 3 29.Os 30.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 31.Sh NAME 32.Nm c32rtomb 33.Nd Restartable UTF-32 to multibyte conversion 34.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 35.Sh LIBRARY 36.Lb libc 37.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 38.Sh SYNOPSIS 39. 40.In uchar.h 41. 42.Ft size_t 43.Fo c32rtomb 44.Fa "char * restrict s" 45.Fa "char32_t c32" 46.Fa "mbstate_t * restrict ps" 47.Fc 48.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 49.Sh DESCRIPTION 50The 51.Nm 52function converts Unicode scalar values to multibyte characters in the 53current locale, keeping state to remember incremental progress if 54restarted. 55.Pp 56Each call to 57.Nm 58updates the conversion state 59.Fa ps 60with a UTF-32 code unit 61.Fa c32 , 62writes up to 63.Dv MB_CUR_MAX 64bytes to 65.Fa s , 66and returns either the number of bytes written to 67.Fa s 68or 69.Li (size_t)-1 70to denote error. 71.Pp 72The input 73.Fa c32 74is a UTF-32 code unit, representing a Unicode scalar value, i.e., a 75Unicode code point that is not a surrogate code point \(em in other 76words, 77.Fa c32 78is an integer either in [0,0xd7ff] or in [0xe000,0x10ffff]. 79.Pp 80If 81.Fa s 82is a null pointer, 83no output is produced and 84.Fa ps 85is reset to the initial conversion state, as if the call had been 86.Fo c8rtomb 87.Va buf , 88.Li 0 , 89.Fa ps 90.Fc 91for some internal buffer 92.Va buf . 93.Pp 94If 95.Fa c32 96is zero, 97.Nm 98outputs a (possibly empty) shift sequence to restore the initial state 99followed by a NUL byte and resets 100.Fa ps 101to the initial conversion state. 102.Pp 103If 104.Fa ps 105is a null pointer, 106.Nm 107uses an internal 108.Vt mbstate_t 109object with static storage duration, distinct from all other 110.Vt mbstate_t 111objects 112.Po 113including those used by other functions such as 114.Xr mbrtoc32 3 115.Pc , 116which is initialized at program startup to the initial conversion 117state. 118.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 119.Sh RETURN VALUES 120The 121.Nm 122function returns the number of bytes written to 123.Fa s 124on success, or sets 125.Xr errno 2 126and returns 127.Li "(size_t)-1" 128on failure. 129.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 130.Sh EXAMPLES 131Convert a sequence of Unicode scalar values to a multibyte sequence, 132NUL-terminate it (with any shift sequence needed to restore the initial 133state), and print it: 134.Bd -literal -offset indent 135char32_t c32[] = { 0x1f4a9, 0x20ac, 0x21 }; 136char buf[(__arraycount(c32) + 1)*MB_LEN_MAX], *s = buf; 137size_t i; 138mbstate_t mbs = {0}; /* initial conversion state */ 139 140for (i = 0; i < __arraycount(c32); i++) { 141 size_t len; 142 143 len = c32rtomb(s, c32[i], &mbs); 144 if (len == (size_t)-1) 145 err(1, "c32rtomb"); 146 assert(len < sizeof(buf) - (s - buf)); 147 s += len; 148} 149len = c32rtomb(s, 0, &mbs); /* NUL-terminate */ 150if (len == (size_t)-1) 151 err(1, "c32rtomb"); 152assert(len <= sizeof(buf) - (s - buf)); 153printf("%s\en", buf); 154.Ed 155.Pp 156To avoid a variable-length array, this code uses 157.Dv MB_LEN_MAX , 158which is a constant upper bound on the locale-dependent 159.Dv MB_CUR_MAX . 160.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 161.Sh ERRORS 162.Bl -tag -width Bq 163.It Bq Er EILSEQ 164.Fa c32 165is not a Unicode scalar value, i.e., it is a surrogate code point in 166the interval [0xd800,0xdfff] or it lies outside the Unicode codespace 167[0,0x10ffff] altogether. 168.It Bq Er EILSEQ 169The input cannot be encoded as a multibyte sequence in the current 170locale. 171.It Bq Er EIO 172An error occurred in loading the locale's character conversions. 173.El 174.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 175.Sh SEE ALSO 176.Xr c16rtomb 3 , 177.Xr c8rtomb 3 , 178.Xr mbrtoc16 3 , 179.Xr mbrtoc32 3 , 180.Xr mbrtoc8 3 , 181.Xr uchar 3 182.Rs 183.%B The Unicode Standard 184.%O Version 15.0 \(em Core Specification 185.%Q The Unicode Consortium 186.%D September 2022 187.%U https://www.unicode.org/versions/Unicode15.0.0/UnicodeStandard-15.0.pdf 188.Re 189.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 190.Sh STANDARDS 191The 192.Nm 193function conforms to 194.St -isoC-2011 . 195.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 196.Sh HISTORY 197The 198.Nm 199function first appeared in 200.Nx 11.0 . 201