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_CTYPE.

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

Returns:

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

Safety:
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread No

See also:

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