NAME
mbrlen —
get number of bytes in a
multibyte character (restartable)
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <wchar.h>
size_t
mbrlen(
const char
* restrict s,
size_t
n,
mbstate_t * restrict
ps);
DESCRIPTION
The
mbrlen() function usually determines the number of bytes
in a multibyte character pointed to by
s and returns it.
This function shall only examine max n bytes of the array beginning from
s.
mbrlen() is equivalent to the following call (except
ps is evaluated only once):
mbrtowc(NULL, s, n, (ps != NULL) ? ps : &internal);
Here,
internal is an internal state object.
In state-dependent encodings,
s may point to the special
sequence bytes to change the shift-state. Although such sequence bytes
corresponds to no individual wide-character code, these affect the conversion
state object pointed to by
ps, and the
mbrlen() treats the special sequence bytes as if these are a
part of the subsequent multibyte character.
Unlike
mblen(3),
mbrlen() may accept the byte sequence when it is not a
complete character but possibly contains part of a valid character. In this
case, this function will accept all such bytes and save them into the
conversion state object pointed to by
ps. They will be
used on subsequent calls of this function to restart the conversion suspended.
The behaviour of
mbrlen() is affected by the
LC_CTYPE
category of the current locale.
These are the special cases:
-
-
- s == NULL
- mbrlen() sets the conversion state object
pointed to by ps to an initial state and always
returns 0. Unlike mblen(3),
the value returned does not indicate whether the current encoding of the
locale is state-dependent.
In this case, mbrlen() ignores
n.
-
-
- n == 0
- In this case, the first n bytes of
the array pointed to by s never form a complete
character. Thus, mbrlen() always returns
(size_t)-2.
-
-
- ps == NULL
- mbrlen() uses its own internal state
object to keep the conversion state, instead of ps
mentioned in this manual page.
Calling any other functions in Standard C Library (libc,
-lc) never changes the internal state of
mbrlen(), except for calling
setlocale(3) with a
changing
LC_CTYPE
category of the current locale.
Such setlocale(3) calls
cause the internal state of this function to be indeterminate. This
internal state is initialized at startup time of the program.
RETURN VALUES
The
mbrlen() returns:
-
-
- 0
- s points to a nul byte
(‘\0’).
-
-
- positive
- The value returned is a number of bytes for the valid
multibyte character pointed to by s. There are no
cases that this value is greater than n or the value
of the
MB_CUR_MAX
macro.
-
-
- (size_t)-2
- s points to the byte sequence which
possibly contains part of a valid multibyte character, but which is
incomplete. When n is at least
MB_CUR_MAX
, this case can only occur if the array
pointed to by s contains a redundant shift
sequence.
-
-
- (size_t)-1
- s points to an illegal byte sequence
which does not form a valid multibyte character. In this case,
mbrtowc() sets errno to indicate
the error.
ERRORS
mbrlen() may cause an error in the following case:
-
-
- [
EILSEQ
]
- s points to an invalid multibyte
character.
-
-
- [
EINVAL
]
- ps points to an invalid or
uninitialized mbstate_t object.
SEE ALSO
mblen(3),
mbrtowc(3),
setlocale(3)
STANDARDS
The
mbrlen() function conforms to
ISO/IEC
9899/AMD1:1995 (“ISO C90, Amendment 1”). The restrict
qualifier is added at
ISO/IEC 9899:1999
(“ISO C99”).