1.\" $OpenBSD: MB_CUR_MAX.3,v 1.1 2023/08/25 12:45:45 schwarze Exp $ 2.\" 3.\" Copyright (c) 2023 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: August 25 2023 $ 18.Dt MB_CUR_MAX 3 19.Os 20.Sh NAME 21.Nm MB_CUR_MAX 22.Nd maximum number of bytes in a multibyte character 23.Sh SYNOPSIS 24.In stdlib.h 25.Ft size_t 26.Sy MB_CUR_MAX 27.Pp 28.In limits.h 29.Fd #define MB_LEN_MAX 4 30.Sh DESCRIPTION 31.Nm 32is a macro that returns the maximum number of bytes needed to 33represent any multibyte character in the current character encoding. 34Usually, the character encoding is selected for the whole program using 35.Xr setlocale 3 36with a 37.Fa category 38argument of 39.Dv LC_CTYPE , 40but it can be overridden on a per-thread basis using 41.Xr uselocale 3 . 42.Pp 43By default and in the 44.Qq C 45locale, 46.Nm MB_CUR_MAX 47returns 1. 48On 49.Ox , 50the only other possible return value is 4; 51it occurs when using a UTF-8 locale. 52On other systems, 53.Nm 54may return positive values other than 1 or 4. 55.Pp 56.Dv MB_LEN_MAX 57is a constant specifying the maximum number of bytes needed to 58represent any multibyte character in any supported character encoding. 59On 60.Ox , 61it is always 4. 62On other systems, it may have a different value greater than or equal to 1. 63.Sh RETURN VALUES 64On any system, 65.Nm 66returns an integral value in the range from 1 to 67.Dv MB_LEN_MAX , 68inclusive. 69.Sh EXAMPLES 70Size a buffer in a portable way to hold one single multibyte character: 71.Bd -literal -offset indent 72char buf[MB_LEN_MAX]; 73wchar_t wchar; /* input value */ 74 75if (wctomb(buf, wchar) == -1) 76 /* error */ 77.Ed 78.Pp 79Switch between code handling the 80.Xr ascii 7 81and 82UTF-8 character encodings in an 83.Ox Ns -specific 84way 85.Pq not portable : 86.Bd -literal -offset indent 87if (MB_CUR_MAX == 1) { 88 /* Code to handle ASCII-encoded single-byte strings. */ 89} else { 90 /* Code to handle UTF-8-encoded multibyte strings. */ 91} 92.Ed 93.Sh SEE ALSO 94.Xr mblen 3 , 95.Xr setlocale 3 , 96.Xr uselocale 3 , 97.Xr wctomb 3 98.Sh STANDARDS 99.Nm MB_CUR_MAX 100and 101.Dv MB_LEN_MAX 102conform to 103.St -ansiC . 104.Sh HISTORY 105.Nm MB_CUR_MAX 106has been non-constant and thread-dependent since 107.Ox 6.2 . 108.Sh CAVEATS 109Since 110.Nm 111is thread-dependent, calling it in a loop that processes individual 112bytes or characters is likely to slow down the loop considerably. 113If possible, consider calling it once before the loop and caching 114the return value in a local variable to improve performance. 115The value remains valid as long as the thread does not call 116.Xr setlocale 3 117or 118.Xr uselocale 3 . 119