mbsrtowcs

Converts a sequence of multibyte characters into their corresponding wide-character codes and stores them in an array.

Library:LibC
Classification:ANSI
Service:Characters and Strings

Syntax

  #include <wchar.h> 
   
  size_t   mbsrtowcs (
     wchar_t       *dst,
     const char   **src,
     size_t         len,
     mbstate_t     *ps);

Parameters

dst

(OUT) Points to the array of wide-character codes.

src

(IN) Points to the array of multibyte characters to be converted.

len

(IN) Specifies the number of codes to be stored in the array pointed to by dst.

ps

(IN) Points to the conversion state of the character sequence. If ps is a NULL pointer, mbsrtowcs uses its own state, which is initialized at startup. A thread-safe application must not pass a NULL pointer.

Return Values

If successful, returns the actual number of characters converted, not including the null-terminating character (if any).

If an error occurs, returns -1 and sets errno to the following:

Decimal

Constant

Description

9

EINVAL

The ps parameter points to an object that contains an invalid conversion state.

101

EILSEQ

The src string contains an invalid character sequence.

Remarks

The mbsrtowcs function converts a sequence of multibyte characters pointed to by src into their corresponding wide-character codes and stores not more than len codes into the array pointed to by dst.

The mbsrtowcs function does not convert any multibyte characters beyond the null-terminating character. Conversion continues up to and including a null-terminating character, which is also stored. At most, len elements of the array pointed to by src are modified. If a null-terminating character is not encountered in the len elements, the dst string is not null terminated.

The behavior of this function is affected by the LC_CTYPE category of the current locale.

See Also