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:

A sequence of bytes is encountered that does not form a valid multibyte character.
If dst is not a NULL pointer, when len codes have been stored into the array pointed to by dst.

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

n 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

n	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.