mbtowc()

Convert a multibyte character into a wide character

Synopsis:

#include <stdlib.h>

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

Since:

BlackBerry 10.0.0

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

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

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus