_mbclen, mblen, _mblen_l

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _mbclen, mblen, _mblen_l.

Gets the length and determines the validity of a multibyte character.

Important

This API cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW.

Syntax

size_t _mbclen(  
   const unsigned char *c   
);  
int mblen(  
   const char *mbstr,  
   size_t count   
);  
int _mblen_l(  
   const char *mbstr,  
   size_t count,  
   _locale_t locale  
);

Parameters

c
Multibyte character.

mbstr
Address of a multibyte-character byte sequence.

count
Number of bytes to check.

locale
Locale to use.

Return Value

_mbclen returns 1 or 2, according to whether the multibyte character c is 1 or 2 bytes long. There is no error return for _mbclen. If mbstr is not NULL, mblen returns the length, in bytes, of the multibyte character. If mbstr is NULL or it points to the wide-character null character, mblen returns 0. If the object that mbstr points to does not form a valid multibyte character within the first count characters, mblen returns –1.

Remarks

The _mbclen function returns the length, in bytes, of the multibyte character c. If c does not point to the lead byte of a multibyte character as determined by an implicit call to _ismbblead, the result of _mbclen is unpredictable.

mblen returns the length in bytes of mbstr if it is a valid multibyte character and determines multibyte-character validity associated with the code page. mblen examines count or fewer bytes contained in mbstr, but not more than MB_CUR_MAX bytes.

The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. For more information, see Locale.

Generic-Text Routine Mappings

Tchar.h routine	_UNICODE and _MBCS not defined	_MBCS defined	_UNICODE defined
`_tclen`	Maps to macro or inline function	`_mbclen`	Maps to macro or inline function

Requirements

Routine	Required header
`_mbclen`	<mbstring.h>
`mblen`	<stdlib.h>
`_mblen_l`	<stdlib.h>

For more compatibility information, see Compatibility.

Example

// crt_mblen.c  
/* illustrates the behavior of the mblen function  
 */  
  
#include <stdlib.h>  
#include <stdio.h>  
  
int main( void )  
{  
    int      i;  
    char    *pmbc = (char *)malloc( sizeof( char ) );  
    wchar_t  wc   = L'a';  
  
    printf( "Convert wide character to multibyte character:\n" );  
    wctomb_s( &i, pmbc, sizeof(char), wc );  
    printf( "  Characters converted: %u\n", i );  
    printf( "  Multibyte character: %x\n\n", *pmbc );  
  
    i = mblen( pmbc, MB_CUR_MAX );  
    printf( "Length in bytes of multibyte character %x: %u\n", *pmbc, i );  
  
    pmbc = NULL;  
    i = mblen( pmbc, MB_CUR_MAX );  
    printf( "Length in bytes of NULL multibyte character %x: %u\n", pmbc, i );  
}

Output

Convert wide character to multibyte character:  
  Characters converted: 1  
  Multibyte character: 61  
  
Length in bytes of multibyte character 61: 1  
Length in bytes of NULL multibyte character 0: 0

.NET Framework Equivalent

Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.

Share via