%PAGEREF%(MinGW)

NAME
mbrlen - determine the number of bytes in a multibyte character

SYNOPSIS
#include <wchar.h>

size_t mbrlen( const char *s, size_t n, mbstate_t *ps );

    Feature Test Macro Requirements for libmingwex:

__MSVCRT_VERSION__: since mingwrt-5.3, if this feature test macro is defined, with a value of at least 0x0800, (corresponding to the symbolic constant, __MSCVR80_DLL, and thus declaring intent to link with MSVCR80.DLL, or any later version of Microsoft's non-free runtime library, instead of with MSVCRT.DLL), calls to mbrlen() will be directed to the implementation thereof, within Microsoft's runtime DLL.

_ISOC99_SOURCE, _ISOC11_SOURCE: since mingwrt-5.3.1, when linking with MSVCRT.DLL, or when __MSVCRT_VERSION__ is either undefined, or is defined with any value which is less than 0x0800, (thus denying intent to link with MSVCR80.DLL, or any later non-free version of Microsoft's runtime library), explicitly defining either of these feature test macros will cause any call to mbrlen() to be directed to the libmingwex implementation; if neither macro is defined, calls to mbrlen() will be directed to Microsoft's runtime implementation, if it is available, otherwise falling back to the libmingwex implementation.

Prior to mingwrt-5.3, none of the above feature test macros have any effect on mbrlen(); all calls will be directed to the libmingwex implementation.

DESCRIPTION
The mbrlen() function inspects the sequence of bytes, starting at s, up to a maximum of n bytes, to determine the number of bytes required to complete the next multibyte code point, commencing from the conversion state specified in *ps, (which is then updated).

The sequence of bytes, pointed to by s, is interpreted as a multibyte character sequence in the codeset which is associated with the LC_CTYPE category of the active process locale.

If ps is specified as a NULL pointer, mbrlen() will track conversion state using an internal mbstate_t object reference, which is private within the mbrlen() process address space; at process start-up, this internal mbstate_t object is initialized to represent the initial conversion state.

RETURN VALUE
If the multibyte sequence, completed by n or fewer bytes, does not represent the NUL code point, then mbrlen() returns the number of bytes which are actually required to complete the sequence, (a number between 1 and n, inclusive), and the conversion state, as specified in *ps, is reset to the initial state.

On the other hand, if the completed multibyte sequence does represent the NUL code point, then mbrlen() returns zero, and the conversion state, as specified in *ps, is reset to the initial state.

If n is less than the effective MB_CUR_MAX for the active process locale, and n bytes is insufficient to complete a multibyte character, then *ps is updated to represent a new partially completed encoding state, and mbrlen() returns (size_t)(-2). Conversely, if n is equal to, or greater than MB_CUR_MAX, this return condition can arise, only if the multibyte encoding sequence includes redundant shift states; since shift states are not used, this cannot occur in any MS-Windows multibyte character set.

ERROR CONDITIONS
If the sequence of n or fewer bytes, pointed to by s, extends any pending encoding state recorded within *ps, to at least MB_CUR_MAX bytes, and the resulting sequence does not represent a valid multibyte character, then errno is set to EILSEQ, and mbrlen() returns (size_t)(-1).

If, on entry to mbrlen(), the conversion state represented by *ps is deemed to be invalid, errno is set to EINVAL, and mbrlen() returns (size_t)(-1); the conversion state may be deemed to be invalid if it contains any sequence of bytes which does not match a valid initial sequence from a multibyte character representation within the currently active codeset, if it can be interpreted as a complete multibyte character, without the addition of any further bytes from s, or if it represents a surrogate pair conversion, resulting from a preceding call to the mbrtowc(3) function, and from which the low surrogate has yet to be retrieved.

STANDARDS CONFORMANCE
Except to the extent that it may be affected by limitations of the underlying MS-Windows API, the libmingwex implementation of mbrlen() conforms generally to ISO-C99, POSIX.1-2001, and POSIX.1-2008; (prior to mingwrt-5.3 , and in those cases where calls may be delegated to a Microsoft runtime DLL implementation, this level of conformity may not be achieved).

The feature whereby errno is set to EINVAL, when *ps is found to be invalid, is a POSIX.1 conforming extension to ISO-C99.

CAVEATS AND BUGS
If mbrlen() is called with a NULL pointer for s, the behaviour is undefined.

Due to a documented limitation of Microsoft's setlocale() function implementation, it is not possible to directly select an active locale, in which the codeset is represented by any multibyte character sequence with an effective MB_CUR_MAX of more than two bytes. Prior to mingwrt-5.3, this limitation precludes the use of mbrlen() to interpret any codeset with MB_CUR_MAX greater than two bytes, (such as UTF-8). From mingwrt-5.3 onward, the MinGW.org implementation of mbrlen() mitigates this limitation by assignment of the codeset from the LC_CTYPE environment variable, provided the system default has been previously activated for the LC_CTYPE locale category; e.g. execution of:

        #define _ISOC99_SOURCE
        #include <stdio.h>
        #include <stdlib.h>
        #include <locale.h>
        #include <limits.h>
        #include <wchar.h>
        int main()
        {
          setlocale( LC_CTYPE, "" );
          putenv( "LC_CTYPE=en_GB.65001" );
          printf( "%u bytes\n",
              mbrlen( "\U0001d10b", MB_LEN_MAX, NULL )
            );
          return 0;
        }

will interpret the string "\U0001d10b" as a four-byte UTF-8 encoding sequence, (which represents a single code point), and print the result as 4 bytes.

Please be aware that the underlying MS-Windows API, which is used to interpret the multibyte sequence, offers no readily accessible mechanism to discriminate between incomplete and invalid sequences; thus, if n is less than the effective MB_CUR_MAX for the active codeset, this mbrlen() implementation may return (size_t)(-2), indicating an incomplete sequence, even in cases where there are no additional bytes which could be appended, to complete a valid encoding sequence.

SEE ALSO
mbrtowc(3)

AUTHOR
This manpage was written by Keith Marshall, <keith@users.osdn.me>, to document the mbrlen() function as it has been implemented for the MinGW.org Project. It may be copied, modified and redistributed, without restriction of copyright, provided this acknowledgement of contribution by the original author remains in place.