mbrlen() — Calculate length of multibyte character

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment C99 Single UNIX Specification, Version 3	both

Format

Non-XPG4

#include <wchar.h>

size_t mbrlen(const char * __restrict__s, size_t n, mbstate_t * __restrict__ps);

XPG4

#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>

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

General description

Calculates the number of bytes required to return to the initial shift state. This is equivalent to

   mbrtowc((wchar_t *)0, s, n, ps != NULL ? ps : &internal);

where &internal is the address of the internal mbstate_t object for the mbrlen() function.

mbrlen() is a restartable version of mblen(). That is, shift state information is passed as one of the arguments, and is updated on exit. With mbrlen(), you can switch from one multibyte string to another, provided that you have kept the shift-state information.

The behavior of this wide-character function is affected by the LC_CTYPE category of the current locale. If you change the category, undefined results can occur.

Special behavior for XPG4

If you define any feature test macro specifying XPG4 behavior before the statement in your program source file to include the wchar header, then you must also define the _MSE_PROTOS feature test macro to make the declaration of the mbrlen() function in the wchar header available when you compile your program. Please see Table 1 for a list of XPG4 and other feature test macros.

Returned value

If s is a NULL pointer, mbrlen() resets the shift state to the initial shift state and returns 0.

If s is not a NULL pointer, mbrlen() returns the first of the following that applies.

0: If the next n or fewer bytes complete the valid multibyte character that corresponds to the NULL wide character.
positive: If the next n or fewer bytes complete the valid multibyte character; the value returned is the number of bytes that complete the multibyte character.
-2: If the next n bytes form an incomplete (but potentially valid) multibyte character, and all n bytes have been processed; it is unspecified whether this can occur when the value of n is less than that of the MB_CUR_MAX macro.
Note: When a -2 value is returned, and n is at least MB_CUR_MAX, the string would contain redundant shift-out and shift-in characters. To continue processing the multibyte string, increment the pointer by the value n, and call the mbrtowc() function.
-1: If an encoding error occurs (when the next n or fewer bytes do not contribute to the complete and valid multibyte character), the value of the macro EILSEQ is stored in errno, but the conversion state remains unchanged.

Example

CELEBM03

⁄* CELEBM03 *⁄                                   
#include <stdio.h>                                                              
#include <stdlib.h>                                                             
#include <wchar.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   char      mbs[5] = "a";    ⁄* string containing the multibyte char *⁄        
   mbstate_t ss     = 0;      ⁄* set shift state to the initial state *⁄        
   int       length;                                                            
                                                                                
   ⁄* Determine the length in bytes of a multibyte character pointed  *⁄        
   ⁄* to by mbs.                                                      *⁄        
                                                                                
   length = mbrlen(mbs, MB_CUR_MAX, &ss);                                       
                                                                                
   printf("    length: %d \n", length);                                         
   printf("       mbs:\"%s\"\n", mbs);                                          
   printf("MB_CUR_MAX: %d \n", MB_CUR_MAX);                                     
   printf("        ss: %d \n", ss);                                             
}

Output

    length: 1
       mbs:"a"
MB_CUR_MAX: 4
        ss: 0