mbstowcs(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
MBSTOWCS(3)             NetBSD Library Functions Manual            MBSTOWCS(3)


NAME

     mbstowcs -- converts a multibyte character string to a wide character
     string


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <stdlib.h>

     size_t
     mbstowcs(wchar_t * restrict pwcs, const char * restrict s, size_t n);


DESCRIPTION

     mbstowcs() converts a nul-terminated multibyte character string pointed
     to by s to the corresponding wide character string and stores it in the
     array pointed to by pwcs.  This function may modify the first at most n
     elements of the array pointed to by pwcs.  Each character will be con-
     verted as if mbtowc(3) is continuously called, except the internal state
     of mbtowc(3) will not be affected.

     For state-dependent encoding, mbstowcs() implies the multibyte character
     string pointed to by s always begins with an initial state.

     These are the special cases:

     pwcs == NULL  mbstowcs() returns the number of elements to store the
                   whole wide character string corresponding to the multibyte
                   character string pointed to by s.  In this case, n is
                   ignored.

     s == NULL     Undefined (may cause the program to crash).


RETURN VALUES

     mbstowcs() returns:

     0 or positive
                   Number of elements stored in the array pointed to by pwcs.
                   There are no cases that the value returned is greater than
                   n (unless pwcs is a null pointer) or the value of the
                   MB_CUR_MAX macro.  If the return value is equal to n, the
                   string pointed to by pwcs will not be nul-terminated.

     (size_t)-1    s points to a string containing an invalid or incomplete
                   multibyte character.  The mbstowcs() also sets errno to
                   indicate the error.


ERRORS

     mbstowcs() may cause an error in the following case:

     [EILSEQ]           s points to a string containing an invalid or incom-
                        plete multibyte character.


SEE ALSO

     mbtowc(3), setlocale(3)


STANDARDS

     The mbstowcs() function conforms to ANSI X3.159-1989 (``ANSI C89'').  The
     restrict qualifier is added at ISO/IEC 9899:1999 (``ISO C99'').

NetBSD 5.1.2                   February 3, 2002                   NetBSD 5.1.2