mbrlen

  • Article

mbrlen

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

The function is equivalent to the call:

mbrtowc(0, s, n, ps != 0 ? ps : &internal)

where internal is an object of type mbstate_t internal to the mbrlen function. At program startup, internal is initialized to the initial conversion state. No other library function alters the value stored in internal.

The function returns:

  • (``size_t``)-2 if, after converting all n characters, the resulting conversion state indicates an incomplete multibyte character.
  • (``size_t``)-1 if the function detects an encoding error before completing the next multibyte character, in which case the function stores the value EILSEQ in errno and leaves the resulting conversion state undefined.
  • Zero, if the next completed character is a null character, in which case the resulting conversion state is the initial conversion state.
  • x, the number of bytes needed to complete the next muitibyte character, in which case the resulting conversion state indicates that x bytes have been converted.

Thus, mbrlen effectively returns the number of bytes that would be consumed in successfully converting a multibyte character to a wide character (without storing the converted wide character), or an error code if the conversion cannot succeed.