mbsrtowcs_s

Статья
06/09/2015

Преобразуют многобайтовую строку символов в текущем языковом стандарте в представление с расширенными символами. Версия функции mbsrtowcs с усовершенствованиями в части безопасности, описанными в разделе Функции безопасности в CRT.

errno_t mbsrtowcs_s(    size_t * pReturnValue,    wchar_t * wcstr,    size_t sizeInWords,    const char ** mbstr,    size_t count,    mbstate_t * mbstate ); template <size_t size> errno_t mbsrtowcs_s(    size_t * pReturnValue,    wchar_t (&wcstr)[size],    const char ** mbstr,    size_t count,    mbstate_t * mbstate ); // C++ only

Параметры

[выходной] pReturnValue
Количество символов для преобразования.
[выходной] wcstr
Адрес буфера для результирующей преобразованной строки расширенных символов.
[выходной] sizeInWords
Размер wcstr в словах (расширенных символах).
[in, out] mbstr
Косвенный указатель на расположение преобразуемой строки многобайтовых символов.
[in] count
Максимальное число расширенных символов для хранения в буфере wcstr, не считая завершающий нуль-символ, или _TRUNCATE.
[in, out] mbstate
Указатель на объект состояния преобразования mbstate_t. Если это значение является пустым указателем, используется статичный внутренний объект состояния преобразования. Так как внутренний объект mbstate_t не является потокобезопасным, мы рекомендуем всегда передавать собственный параметр mbstate.

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

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

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

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

Заметки

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

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

Строка назначения wcstr всегда завершается нуль-символом (даже в случае ошибки), если только wcstr не является пустым указателем.

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

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

Если wcstr не является пустым указателем, то объекту указателя, на который указывает параметр mbstr, присваивается пустой указатель, если преобразование останавливается из-за достижения завершающего нуль-символа. В противном случае ему назначается адрес позиции, следующей за последним преобразованным многобайтовым символом, если таковая имеется. Это позволяет продолжить преобразование с того же места при последующем вызове функции.

Если значение mbstate является пустым указателем, используется статичный внутренний объект состояния преобразования mbstate_t. Так как этот внутренний объект не является потокобезопасным, мы рекомендуем передавать собственное значение параметра mbstate.

Если функция mbsrtowcs_s обнаруживает многобайтовый символ, который не является допустимым в текущем языковом стандарте, то в *pReturnValue помещается значение -1, буфер назначения wcstr устанавливается равным пустой строке, для errno устанавливается значение EILSEQ и возвращается значение EILSEQ.

Если последовательности, на которые указывают параметры mbstr и wcstr, перекрываются, то поведение mbsrtowcs_s не определено. На функцию mbsrtowcs_s влияет категория LC_TYPE текущего языкового стандарта.

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

Функция mbsrtowcs_s отличается от функции mbstowcs_s, _mbstowcs_s_l возможностью перезапуска. Состояние преобразования хранится в переменной mbstate для последующих вызовов тех же или других перезапускаемых функций. При смешанном использовании перезапускаемых и неперезапускаемых функций результаты становятся неопределенными. Например, в приложении необходимо использовать функцию mbsrlen вместо функции mbslen, если в последующем вызове используется функция mbsrtowcs_s, а не функция mbstowcs_s..

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

Исключения

Функция mbsrtowcs_s является потокобезопасной, если ни одна из функций в текущем потоке не вызывает setlocale, пока выполняется данная функция, и аргумент mbstate не является пустым указателем.