mbrlen(), mbrlen_l() -- determine length of multibyte character using conversion states

SYNOPSIS

#include <wchar.h>

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

#include <wchar.h>

#include <locale.h>

size_t mbrlen_l(const char *s, size_t n, mbstate_t *ps, locale_t locale);

DESCRIPTION

If s is not null, the mbrlen() function determines the number of bytes constituting the character pointed to. It is equivalent to:

mbstate_t internal;
mbrtowc(NULL, s, n, ps != NULL ? ps : &internal);

If the specified state pointer is null, the mbrlen() function uses its own internal mbstate_t object, which is initialized at program startup to the initial conversion state. Otherwise, the specified mbstate_t object is used to completely describe the current conversion state of the associated character sequence.

The behavior of this function is affected by the LC_CTYPE category of the current locale.

mbrlen_l() behaves in the same way as mbrlen() without the _l suffix, but uses the specified locale rather than the global or per-thread locale. A locale_t is returned by newlocale().

PARAMETERS

s: Points to the string whose bytes are to be counted.
n: Specifies the maximum number of bytes to examine.
ps: Is the conversion state. If this is null, an internal mbstate_t object is used.
locale: Is a locale_t perhaps returned by newlocale() or LC_GLOBAL_LOCALE or 0 for the current thread locale set with uselocale().

RETURN VALUES

The mbrlen() and mbrlen_l() functions return the first of the following that applies:

0: If the next n or fewer bytes complete the character that corresponds to the null wide character.
positive number: If the next n or fewer bytes complete a valid character; the value returned is the number of bytes that complete the character.
-2: If the next n bytes contribute to an incomplete by potentially valid character, and all n bytes have been processed. When n has at least the value of MB_CUR_MAX (or MB_CUR_MAX_L), this case can only occur if s points at a sequence of redundant shift sequences (for locales with state-dependent encodings).
-1: If an encoding error occurs, in which case the next n or fewer bytes do not contribute to a complete and valid character. In this case, errno is set to EILSEQ, and the conversion state is undefined.

CONFORMANCE

mbrlen() conforms to ANSI/ISO 9899:1999 'ISO C99'

mbrlen_l() conforms to IEEE Std 1003.1-2008 'POSIX.1'

MULTITHREAD SAFETY LEVEL

MT-Safe, with exceptions.

The mbrlen() function is MT-Safe as long as no thread calls setlocale() while this function is executing.

The function mbrlen_l() is MT-Safe as long as no thread calls freelocale() on locale while this function is executing.

PORTING ISSUES

None.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

mbrlen(), mbrlen_l()
determine length of multibyte character using conversion states

Function