mbstowcs - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# mbstowcs

From cppreference.com
< c‎ | string‎ | multibyte

Defined in header `<stdlib.h>` |  |
size_t mbstowcs( wchar_t *dst, const char *src, size_t len) |  | (until C99)
size_t mbstowcs( wchar_t *restrict dst, const char *restrict src, size_t len) |  | (since C99)

Converts a multibyte character string from the array whose first element is pointed to by `src` to its wide character representation. Converted characters are stored in the successive elements of the array pointed to by `dst`. No more than `len` wide characters are written to the destination array.

Each character is converted as if by a call to mbtowc, except that the mbtowc conversion state is unaffected. The conversion stops if:

- The multibyte null character was converted and stored.
- An invalid (in the current C locale) multibyte character was encountered.
- The next wide character to be stored would exceed `len`.

### [edit] Notes

In most implementations, this function updates a global static object of type mbstate_t as it processes through the string, and cannot be called simultaneously by two threads, mbsrtowcs should be used in such cases.

POSIX specifies a common extension: if `dst` is a null pointer, this function returns the number of wide characters that would be written to `dst`, if converted. Similar behavior is standard for mbsrtowcs.

### [edit] Parameters

dst | - | pointer to wide character array where the wide string will be stored
src | - | pointer to the first element of a null-terminated multibyte string to convert
len | - | number of wide characters available in the array pointed to by dst

### [edit] Return value

On success, returns the number of wide characters, excluding the terminating L'\0', written to the destination array.

On conversion error (if invalid multibyte character was encountered), returns (size_t)-1.

### [edit] Example

| This section is incomplete Reason: no example

### [edit] See also

mbsrtowcs | converts a narrow multibyte character string to wide string, given state (function) [edit]
wcstombs | converts a wide string to narrow multibyte character string (function) [edit]
C++ documentation for mbstowcs

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=c/string/multibyte/mbstowcs&oldid=62627"
Category:

- Todo no example