wcsrtombs
Convert a wide character string to its multibyte character string representation. A more secure version of this function is available; see wcsrtombs_s.
size_t wcsrtombs(
char *mbstr,
const wchar_t **wcstr,
sizeof count,
mbstate_t *mbstate
);
template <size_t size>
size_t wcsrtombs(
char (&mbstr)[size],
const wchar_t **wcstr,
sizeof count,
mbstate_t *mbstate
); // C++ only
Parameters
[out] mbstr
The resulting converted multibyte character string's address location.[in] wcstr
Indirectly points to the location of the wide 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 bytes successfully converted, not including the null terminating null byte (if any), otherwise a -1 if an error occurred.
Remarks
The wcsrtombs function converts a string of wide characters, beginning in the specified conversion state contained in mbstate, from the values indirect pointed to in wcstr, into the address of mbstr. The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in count. If wcsrtombs encounters the wide-character null character (L'\0') either before or when count occurs, it converts it to an 8-bit 0 and stops.
Thus, the multibyte character string at mbstr is null-terminated only if wcsrtombs encounters a wide character null character during conversion. If the sequences pointed to by wcstr and mbstr overlap, the behavior of wcsrtombs is undefined. wcsrtombs is affected by the LC_TYPE category of the current locale.
The wcsrtombs function differs from wcstombs, _wcstombs_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 wcsrlen rather than wcsnlen, if a subsequent call to wcsrtombs were used instead of wcstombs.
If the mbstr argument is NULL, wcsrtombs returns the required size in bytes 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.
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 wcsrtombs function is multithread safe as long as no function in the current thread calls setlocale while this function is executing and the mbstate is null.
Example
// crt_wcsrtombs.cpp
// compile with: /W3
// This code example converts a wide
// character string into a multibyte
// character string.
#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>
#define MB_BUFFER_SIZE 100
int main()
{
const wchar_t wcString[] =
{L"Every good boy does fine."};
const wchar_t *wcsIndirectString = wcString;
char mbString[MB_BUFFER_SIZE];
size_t countConverted;
mbstate_t mbstate;
// Reset to initial shift state
::memset((void*)&mbstate, 0, sizeof(mbstate));
countConverted = wcsrtombs(mbString, &wcsIndirectString,
MB_BUFFER_SIZE, &mbstate); // C4996
// Note: wcsrtombs is deprecated; consider using wcsrtombs_s
if (errno == EILSEQ)
{
printf( "An encoding error was detected in the string.\n" );
}
else
{
printf( "The string was successfuly converted.\n" );
}
}
The string was successfuly converted.
.NET Framework Equivalent
Not applicable. To call the standard C function, use PInvoke. For more information, see Platform Invoke Examples.
Requirements
Routine |
Required header |
|---|---|
wcsrtombs |
<wchar.h> |