mbtowc()

Convert a multibyte character into a wide character

Synopsis:

#include <stdlib.h>

int mbtowc( wchar_t * pwc,
            const char * s,
            size_t n );

Arguments:

pwc

A pointer to a wchar_t object where the function can store the wide character.

s

NULL (see below), or a pointer to the multibyte character that you want to convert.

n

The maximum number of bytes in the multibyte character to convert.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The mbtowc() function converts a single multibyte character pointed to by s into a wide-character code pointed to by pwc, to a maximum of n bytes. The function stops early if it encounters the NULL character.

This function is affected by LC_TYPE.

The mbrtowc() function is a restartable version of mbtowc().

Returns:

• If s is NULL:

  0

  The mbtowc() function uses UTF-8 multibyte character encoding that's not state-dependent.

  ≠ 0

  Everything else.

• If s isn't NULL:

  0

  The s argument points to the NUL character.

  > 0

  The number of bytes that comprise the multibyte character, to a maximum of MB_CUR_MAX (if the next n or fewer bytes form a valid multibyte character).

  -1

  The next n bytes don't form a valid multibyte character; errno is set.

Errors:

EILSEQ

Invalid character sequence.

Examples:

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

int main( void )
{
    char *wc = "string";
    wchar_t wbuffer[10];
    int i, len;

    printf( "State-dependent encoding? " );
    if( mbtowc( wbuffer, NULL, 0 ) ) {
        printf( "Yes\n" );
    } else {
        printf( "No\n" );
    }

    len = mbtowc( wbuffer, wc, 2 );
    wbuffer[len] = '\0';
    printf( "%s(%d)\n", wc, len );

    for( i = 0; i < len; i++ ) {
        printf( "/%4.4x", wbuffer[i] );
    }

    printf( "\n" );
    
    return EXIT_SUCCESS;
}

This produces the output:

State-dependent encoding? No
string(1)
/0073

Classification:

ANSI, POSIX 1003.1

See also:

btowc(), errno, mblen(), mbrlen(), mbrtowc(), mbsinit(), mbsrtowcs(), mbstowcs()