mbsrtowcs

Converts a sequence of multibyte characters to a sequence of corresponding wide-character codes.

Format

#include  <wchar.h>

size_t mbsrtowcs  (wchar_t *dst, const char **src,
                  size_t len, mbstate_t *ps);
Function Variants This function also has variants named _mbsrtowcs32 and _mbsrtowcs64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.

Arguments

dst
A pointer to the destination array containing the resulting sequence of wide-character codes.
src
An address of the pointer to an array containing a sequence of multibyte characters to be converted.
len
The maximum number of wide character codes that can be stored in the array pointed to by dst.
ps
A pointer to the mbstate_t object. If a NULL pointer is specified, the function uses its internal mbstate_t object.

Description

This function converts a sequence of multibyte characters, beginning in the conversion state described by the object pointed to by ps, from the array indirectly pointed to by src, into a sequence of corresponding wide characters.

If dst is not a NULL pointer, the converted characters are stored into the array pointed to by dst. Conversion continues up to and including a terminating null character, which is also stored.

Conversion stops earlier for one of the following reasons:

If dst is not a NULL pointer, the pointer object pointed to by src is assigned either a NULL pointer, (if the conversion stopped because of reaching a terminating null wide character) or the address just beyond the last multibyte character converted (if any). If conversion stopped because of reaching a terminating null wide character, the resulting state described is the initial conversion state.

Return Values
The number of multibyte characters successfully converted, sequence, not including the terminating null (if any). 
-1  Indicates an error. A sequence of bytes that do not form valid multibyte character was encountered. errno is set to EILSEQ; the conversion state is undefined. 


Previous Page | Next Page | Table of Contents | Index