_mbclen, mblen, _mblen_l
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.
This API cannot be used in applications that execute in the Windows Runtime. For more information, see CRT functions not supported with /ZW. |
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.
_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.
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 |
| Routine | Required header |
|---|---|
_mbclen | <mbstring.h> |
mblen | <stdlib.h> |
_mblen_l | <stdlib.h> |
For more compatibility information, see Compatibility.
// 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 );
}
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
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
Character Classification
Locale
Interpretation of Multibyte-Character Sequences
_mbccpy, _mbccpy_l
strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l