This documentation is archived and is not being maintained.


Determine the number of bytes in a string, with the capability of restarting in the middle of a multibyte character if need be, while using the current locale.

size_t mbrlen(
   const char *str,
   size_t maxSize,
   mbstate_t mbstate



Null-terminated string.


The maximum size of the string, excluding the terminating null character.


The shift state of conversion.

If the string is less than maxSize characters in length, each of these functions returns the number of characters in str, excluding the terminal NULL. If the string is greater than maxSize characters in length, then maxSize is returned.


If the next count or fewer bytes complete the multibyte character that represents the NULL wide character.

> 0

If the next count or fewer bytes complete a valid multibyte character, the value returned is the number of bytes that complete the multibyte character.


If the next count bytes contribute to an incomplete multibyte and all count bytes have been processed.


If an encoding error occurs, in which case the next count or fewer bytes do not contribute to the complete and valid multibyte character, the value errno value will be EILSEQ and the conversion state ambiguous.

The mbrlen function determines the number of bytes constituting the multibyte character sequence of str, with the capability of restarting in the middle of a multi-byte character if need be, examining at most maxSize bytes. The mbstate_t argument mbstate is used to keep track of the shift state. If it is NULL, mbrlen uses an internal, static mbstate_t object. It is equivalent to:

mbrtowc(NULL, str, maxSize, mbstate)

Except when the case of mbstate is NULL, mbrlen relies upon its own static, internal mbstate_t object to keep track of the shift state.

The mbrlen function differs from _mbclen, mblen, _mblen_l by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use wcsrlen rather than wcslen, if a subsequent call to wcsrtombs where used instead of wcstombs.

Generic-Text Routine Mappings
TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined





Routine Required header Compatibility



ANSI, Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

For additional compatibility information, see Compatibility in the Introduction.

// crt_mbrlen.c

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <wchar.h>

size_t Example(const char * pStr)
    size_t      charLen = 0;
    size_t      charCount = 0;
    mbstate_t   mbState;

    memset(&mbState, 0, sizeof(mbState));
    while ((charLen = mbrlen(pStr, MB_CUR_MAX, &mbState)) != 0 &&
            charLen != (size_t)-1 && charLen != (size_t)-2)
        pStr += charLen;

    return (charCount);

int main( void )
    size_t      charCount = 0;
    const char  *pSample = "Every good boy does fine.";

    charCount = Example(pSample);
    printf("%s\nLength: %d\n", pSample, charCount);


Every good boy does fine.
Length: 25