Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

MBSTOWCS(3)                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
     converted 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
                        incomplete multibyte character.

SEE ALSO
     mbtowc(3), setlocale(3), wcstombs(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 10.99                    March 16, 2011                    NetBSD 10.99