# mbstowcs, mbstowcs_s

> C++ Atlas: `cppatlas.com/w/c/string/multibyte/mbstowcs` | Source: https://en.cppreference.com/w/c/string/multibyte/mbstowcs | Domain: Strings | Standards: C95, C99, C11

In most implementations, mbstowcs 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.

## Official Specification Summary (cppreference)

```cpp
// Defined in header <stdlib.h>

size_t mbstowcs( wchar_t          *dst, const char          *src, size_t len) // (1) (until C99)

size_t mbstowcs( wchar_t *restrict dst, const char *restrict src, size_t len) // (1) (since C99)

errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst,
                  rsize_t dstsz, const char *restrict src, rsize_t len); // (2) (since C11)
```

1) 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`.

If `src` and `dst` overlap, the behavior is undefined

2) Same as (1), except that

* conversion is as-if by `mbrtowc`, not `mbtowc`

* the function returns its result as an out-parameter `retval`

* if no null character was written to `dst` after `len` wide characters were written, then `L'\0'` is stored in `dst[len]`, which means len+1 total wide characters are written

* if `dst` is a null pointer, the number of wide characters that would be produced is stored in `*retval`

* the function clobbers the destination array from the terminating null and until `dstsz`

* If `src` and `dst` overlap, the behavior is unspecified.

* the following errors are detected at runtime and call the currently installed constraint handler function:

     - `retval` or `src` is a null pointer
     - `dstsz` or `len` is greater than `RSIZE_MAX/sizeof(wchar_t)` (unless `dst` is null)
     - `dstsz` is not zero (unless `dst` is null)
     - There is no null character in the first `dstsz` multibyte characters in the `src` array and `len` is greater than `dstsz` (unless `dst` is null)

     As with all bounds-checked functions, `mbstowcs_s` is only guaranteed to be available if `__STDC_LIB_EXT1__` is defined by the implementation and if the user defines `__STDC_WANT_LIB_EXT1__` to the integer constant `1` before including `<stdlib.h>`.

### Notes

In most implementations, `mbstowcs` 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 `mbstowcs_s` and for `mbsrtowcs`.

### 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
- `dstsz` - max number of wide characters that will be written (size of the `dst` array)
- `retval` - pointer to a size_t object where the result will be stored

### Return value

1) 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`.

2) zero on success (in which case the number of wide characters excluding terminating zero that were, or would be written to `dst`, is stored in `*retval`), non-zero on error. In case of a runtime constraint violation, stores `(size_t)-1` in `*retval` (unless `retval` is null) and sets `dst[0]` to `L'\0'` (unless `dst` is null or `dstmax` is zero or greater than `RSIZE_MAX`)

### Example

```c
#include <stdio.h>
#include <locale.h>
#include <stdlib.h>
#include <wchar.h>

int main(void)
{
    setlocale(LC_ALL, "en_US.utf8");
    const char* mbstr = u8"z\u00df\u6c34\U0001F34C"; // or u8"zß水🍌"
    wchar_t wstr[5];
    mbstowcs(wstr, mbstr, 5);
    wprintf(L"MB string: %s\n", mbstr);
    wprintf(L"Wide string: %ls\n", wstr);
}
```

Output:

```text
MB string: zß水🍌
Wide string: zß水🍌
```

### References

- C11 standard (ISO/IEC 9899:2011):

  - 7.22.8.1 The mbstowcs function (p: 359)

  - K.3.6.5.1 The mbstowcs_s function (p: 611-612)

- C99 standard (ISO/IEC 9899:1999):

  - 7.20.8.1 The mbstowcs function (p: 323)

- C89/C90 standard (ISO/IEC 9899:1990):

  - 4.10.8.1 The mbstowcs function

### See also

- [`mbsrtowcs`](https://en.cppreference.com/w/c/string/multibyte/mbsrtowcs) (C95), [`mbsrtowcs_s`](https://en.cppreference.com/w/c/string/multibyte/mbsrtowcs) (C11): converts a narrow multibyte character string to wide string, given state (function)
- [`wcstombs`](https://en.cppreference.com/w/c/string/multibyte/wcstombs), [`wcstombs_s`](https://en.cppreference.com/w/c/string/multibyte/wcstombs) (C11): converts a wide string to narrow multibyte character string (function)
- [C++ documentation for `mbstowcs`](https://en.cppreference.com/w/cpp/string/multibyte/mbstowcs)

---
Attribution: content from https://en.cppreference.com/w/c/string/multibyte/mbstowcs (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.