Converts a multibyte character string to a wide character string.
#include <stdlib.h>
size_t mbstowcs( WcString, String, Number)
wchar_t *WcString;
const char *String;
size_t Number;
The mbstowcs subroutine converts the sequence of multibyte characters pointed to by the String parameter to wide characters and places the results in the buffer pointed to by the WcString parameter. The multibyte characters are converted until a null character is reached or until the number of wide characters specified by the Number parameter have been processed.
| WcString | Points to the area where the result of the conversion is stored. |
| String | Points to a multibyte character string. |
| Number | Specifies the maximum number of wide characters to be converted. |
The mbstowcs subroutine returns the number of wide characters converted, not including a null terminator, if any. If an invalid multibyte character is encountered, a value of -1 is returned. The WcString parameter does not include a null terminator if the value Number is returned.
If WcString is a null wide character pointer, the mbstowcs subroutine returns the number of elements required to store the wide character codes in an array.
The mbstowcs
subroutine fails if the following occurs:
| EILSEQ | Invalid byte sequence is detected. |
This subroutine is part of Base Operating System (BOS) Runtime.
The mblen (mblen Subroutine) subroutine, mbslen (mbslen Subroutine) subroutine, mbtowc (mbtowc Subroutine) subroutine, wcstombs subroutine, wctomb subroutine.
National Language Support Overview for Programming, Subroutines Overview, Understanding Multibyte Code and Wide Character Code Conversion Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.