mbstowcs - convert a character string to a wide-character string
mbstowcs_s - convert a character string to a wide-character string with additional safety checks
#include <stdlib.h> size_t mbstowcs(wchar_t *restrict pwcs, const char *restrict s, size_t n);
#define __STDC_WANT_LIB_EXT1__ 1 #include <stdlib.h> errno_t mbstowcs_s(size_t *restrict retval, wchar_t *restrict dst, rsize_t dstmax, const char *restrict src, rsize_t len);
The mbstowcs() function converts a sequence of characters from the array pointed to by s into a sequence of corresponding wide-character codes and stores not more than n wide-character codes into the array pointed to by pwcs. No characters that follow a null byte (which is converted into a wide-character code with value 0) will be examined or converted. Each character is converted as if by a call to mbtowc(3C).
No more than n elements will be modified in the array pointed to by pwcs. If copying takes place between objects that overlap, the behavior is undefined.
The behavior of this function is affected by the LC_CTYPE category of the current locale. If pwcs is a null pointer, mbstowcs() returns the length required to convert the entire array regardless of the value of n, but no values are stored.
The mbstowcs_s() function is part of the bounds checking interfaces specified in the C11 standard, Annex K. It is similar to the mbstowcs() function, but with differing parameters and explicit runtime-constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.
If an invalid character is encountered, mbstowcs() returns (size_t)−1 and may set errno to indicate the error. Otherwise, mbstowcs() returns the number of the array elements modified (or required if pwcs is NULL), not including a terminating 0 code, if any. The array will not be zero-terminated if the value returned is n.
If no runtime-constraint violation and no encoding error occurred, mbstowcs_s() returns zero. Otherwise, mbstowcs_s() returns a nonzero value.
The mbstowcs() function will fail if:
Invalid byte sequence is detected.
The mbstowcs_s() function will fail if:
Null pointer is passed.
size argument is not a valid value.
Invalid byte sequence is detected.
See attributes(7) for descriptions of the following attributes:
|
The mbstowcs() function can be used safely in multithreaded applications.
The mbstowcs_s() function cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.
setlocale(3C), mblen(3C), mbtowc(3C), wcstombs(3C), wctomb(3C), attributes(7), standards(7), wcstombs_s(3C), wctomb_s(3C), runtime_constraint_handler(3C)