mblen() — Determine Length of a Multibyte Character

Format

#include <stdlib.h>
int mblen(const char *string, size_t n);

Language Level

ANSI

Threadsafe

Use mbrlen() instead.

Locale Sensitive

The behavior of this function might be affected by the LC_CTYPE category of the current locale. This function might be affected by the LC_UNI_CTYPE category of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.

Description

The mblen() function determines the length in bytes of the multibyte character pointed to by string. n represents the maximum number of bytes examined.

Return Value

If string is NULL, the mblen() function returns:

Non-zero if the active locale allows mixed-byte strings. The function initializes the state variable.
Zero otherwise.

If string is not NULL, mblen() returns:

Zero if string points to the null character.
The number of bytes comprising the multibyte character.
-1 if string does not point to a valid multibyte character.

Note: The mblen(), mbtowc(), and wctomb() functions use their own statically allocated storage and are therefore not restartable. However, mbrlen(), mbrtowc(), and wcrtomb() are restartable.

Example

This example uses mblen() and mbtowc() to convert a multibyte character into a single wide character.

#include <stdio.h>
#include <stdlib.h>
 
int length, temp;
char string [6] = "w";
wchar_t arr[6];
 
int main(void)
 
{
   /* Initialize internal state variable */
   length = mblen(NULL, MB_CUR_MAX);       
 
   /* Set string to point to a multibyte character  */
   length = mblen(string, MB_CUR_MAX);
   temp = mbtowc(arr,string,length);
   arr[1] = L'\0';
   printf("wide character string: %ls\n", arr);
}