mbstowcs_s, _mbstowcs_s_l

Статья
06/09/2015

Преобразование последовательности многобайтовых символов в соответствующую последовательность расширенных символов. Версии mbstowcs, _mbstowcs_l с усовершенствованной безопасностью, как описано в разделе Функции безопасности в CRT.

errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count 
);
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t *wcstr,
   size_t sizeInWords,
   const char *mbstr,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t mbstowcs_s(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbstowcs_s_l(
   size_t *pReturnValue,
   wchar_t (&wcstr)[size],
   const char *mbstr,
   size_t count,
   _locale_t locale
); // C++ only

Параметры

[исходящий] pReturnValue
Количество символов для преобразования.
[исходящий] wcstr
Адрес буфера для результирующей преобразованной строки расширенных символов.
[входящий] sizeInWords
Размер буфера wcstr в словах.
[входящий]mbstr
Адрес последовательности многобайтовых символов, завершенной нулевым символом.
[входящий] count
Максимальное количество расширенных символов, которые необходимо сохранить в буфере wcstr, не включая завершающий нулевой символ, или _TRUNCATE.
[входящий] locale
Используемый языковой стандарт.

Возвращаемое значение

Нуль, если успешно; код ошибки при неудаче.

Условие ошибки.	Возвращает значение и errno
wcstr содержит значение NULL и sizeInWords > 0	EINVAL
Параметр mbstr содержит значение NULL	EINVAL
Буфер назначения слишком мал, чтобы вместить преобразованную строку (иначе count будет _TRUNCATE; см. примечания ниже)	ERANGE
wcstr не должен быть NULL и sizeInWords == 0	EINVAL

Если срабатывает какое-либо из этих условий, то возникает исключение о недопустимом параметре, как описано в Проверка параметров. Если выполнение может быть продолжено, то функция возвращает код ошибки и устанавливает errno как показано в таблице.

Заметки

Функция mbstowcs_s выполнит преобразование строки многобайтовых символов, содержащихся в mbstr, в расширенные, сохраняемые в буфере, на который указывает wcstr. Преобразование будет продолжаться для каждого символа до тех пор, пока одно не будет выполнено одно из следующих условий:

Встретился многобайтовый нулевой символ
Встретился недопустимый многобайтовый символ
Количество расширенных символов, хранящихся в буфере wcstr, равно count.

Строка назначения всегда содержит завершающий null (даже в случае ошибки).

Если count является специальным значением _TRUNCATE, то преобразование mbstowcs_s будет выполняться до тех пор, пока буфер назначения не будет заполнен с учетом завершающего признака null.

Если mbstowcs_s успешно выполнит преобразование исходной строки, то значение, содержащее размер преобразованной строки в расширенных символах с учетом завершающего нулевого символа конца строки, будет помещено в *pReturnValue (предоставленное значение pReturnValue не равно NULL). Это происходит даже если аргумент wcstr равен NULL, таким образом, предоставляя возможность задать необходимый размер буфера. Обратите внимание, что если wcstr — NULL, то count игнорируется, а sizeInWords должен быть равен 0.

Если mbstowcs_s встречает недопустимый многобайтовый символ, он помещает 0 в *pReturnValue, устанавливает буфер назначения в пустую строку, устанавливает errno в EILSEQ и возвращает EILSEQ.

Если последовательности, на которые указывают mbstr и wcstr, перекрываются, то поведение mbstowcs_s не определено.

Примечание по безопасности
Убедитесь, что wcstr и mbstr не перекрываются, и что count правильно отражает количество многобайтовых символов для преобразования.

mbstowcs_s использует текущий языковой стандарт для любых расширений, зависящих от языкового стандарта; _mbstowcs_s_l идентична за исключением того, что она использует переданный языковой стандарт. Для получения дополнительной информации см. Языковой стандарт.

В C++ использование данных функций упрощено наличием шаблонных перегрузок; перегруженные методы могут автоматически определять длину буфера (что исключает необходимость указания аргумента с размером буфера), а также они могут автоматически заменять более старые, незащищенные функции их новыми безопасными аналогами. Дополнительные сведения см. в разделе Безопасные перегрузки шаблонов.