mbsrtowcs
Converts a multibyte character string to a corresponding wide characters string. A more secure version of this function is available; see mbsrtowcs.
size_t mbsrtowcs(
wchar_t *wcstr,
const char **mbstr,
sizeof count,
mbstate_t *mbstate
);
template <size_t size>
size_t mbsrtowcs(
wchar_t (&wcstr)[size],
const char **mbstr,
sizeof count,
mbstate_t *mbstate
); // C++ only
Parameters
[out] wcstr
The resulting converted wide character string's address location.[in] mbstr
Indirectly points to the location of the multibyte character string to be converted.[in] count
The number of character to be converted.[in] mbstate
A pointer to an mbstate_t conversion state object.
Return Value
Returns the number of words successfully converted, not including the null terminating null word (if any), otherwise a -1 if an error occurred.
Remarks
The mbsrtowcs function converts a string of multibyte characters, beginning in the specified conversion state contained in mbstate, from the values indirect pointed to in mbstr, into the address of wcstr. The conversion will continue for each character until: after a null terminating multibyte character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in count. If mbsrtowcs encounters the multibyte null character ('\0') either before or when count occurs, it converts it to a 16-bit null terminating character and stops.
Thus, the wide character string at wcstr is null-terminated only if mbsrtowcs encounters a multibyte null character during conversion. If the sequences pointed to by mbstr and wcstr overlap, the behavior of mbsrtowcs is undefined. mbsrtowcs is affected by the LC_TYPE category of the current locale.
The mbsrtowcs function differs from mbstowcs, _mbstowcs_l by its restartability. The conversion state is stored in mbstate for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use mbsrlen rather than mbslen, if a subsequent call to mbsrtowcs where used instead of mbstowcs.
If the wcstr argument is NULL, mbsrtombs returns the required size in words of the destination string. If mbstate is null, the internal mbstate_t conversion state is used. If the character sequence wchar does not have a corresponding multibyte character representation, a -1 is returned and the errno is set to EILSEQ.
If mbstr is NULL, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, this function sets errno to EINVAL and returns -1.
In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see Secure Template Overloads.
Exceptions
The mbsrtowcs function is multithread safe as long as no function in the current thread calls setlocale while this function is executing and the mbstate is not null.
.NET Framework Equivalent
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
Requirements
Routine |
Required header |
|---|---|
mbsrtowcs |
<wchar.h> |