MB_CUR_MAX(3) | Library Functions Manual | MB_CUR_MAX(3)

# NAME

`MB_CUR_MAX` — maximum number of bytes in a multibyte character

# SYNOPSIS

`#include <stdlib.h>`

size_t MB_CUR_MAX

`#include <limits.h>`

`#define MB_LEN_MAX 4`

# DESCRIPTION

`MB_CUR_MAX` is a macro that returns the maximum number of bytes needed to represent any multibyte character in the current character encoding. Usually, the character encoding is selected for the whole program using setlocale(3) with a category argument of `LC_CTYPE`, but it can be overridden on a per-thread basis using uselocale(3).

By default and in the "C" locale, `MB_CUR_MAX` returns 1. On OpenBSD, the only other possible return value is 4; it occurs when using a UTF-8 locale. On other systems, `MB_CUR_MAX` may return positive values other than 1 or 4.

`MB_LEN_MAX` is a constant specifying the maximum number of bytes needed to represent any multibyte character in any supported character encoding. On OpenBSD, it is always 4. On other systems, it may have a different value greater than or equal to 1.

# RETURN VALUES

On any system, `MB_CUR_MAX` returns an integral value in the range from 1 to `MB_LEN_MAX`, inclusive.

# EXAMPLES

Size a buffer in a portable way to hold one single multibyte character:

    char	 buf[MB_LEN_MAX];
    wchar_t	 wchar;  /* input value */

    if (wctomb(buf, wchar) == -1)
    	/* error */

Switch between code handling the ascii(7) and UTF-8 character encodings in an OpenBSD-specific way (not portable):

    if (MB_CUR_MAX == 1) {
    	/* Code to handle ASCII-encoded single-byte strings. */
    } else {
    	/* Code to handle UTF-8-encoded multibyte strings. */
    }

# SEE ALSO

mblen(3), setlocale(3), uselocale(3), wctomb(3)

# STANDARDS

`MB_CUR_MAX` and `MB_LEN_MAX` conform to ANSI X3.159-1989 (“ANSI C89”).

# HISTORY

`MB_CUR_MAX` has been non-constant and thread-dependent since OpenBSD 6.2.

# CAVEATS

Since `MB_CUR_MAX` is thread-dependent, calling it in a loop that processes individual bytes or characters is likely to slow down the loop considerably. If possible, consider calling it once before the loop and caching the return value in a local variable to improve performance. The value remains valid as long as the thread does not call setlocale(3) or uselocale(3).

August 25, 2023 | Debian