MBSRTOWCS(3)

НАЗВАНИЕ
mbsrtowcs - преобразует многобайтовую строку в строку широких символов

СИНТАКСИС
#include <wchar.h>

size_t mbsrtowcs(wchar_t *dest, const char **src,
                  size_t len, mbstate_t *ps);

ОПИСАНИЕ
Если dest не является NULL-указателем, то функция mbsrtowcs преобразует многобайтовую строку *src в строку широких символов, начиная с dest. В dest запишется максимум len широких символов. Статус смещения *ps обновляется. Преобразование эффективно выполняется многократным вызовом mbrtowc (dest,*src,n,ps), где n - некоторое положительное число (до тех пор, пока данный вызов успешно работает); и последующим увеличением dest на единицу и *src на количество "отработанных" байтов. Преобразование может остановиться по трем следующим причинам:

1. Была встречена неправильная многобайтовая последовательность. В этом случае *src оставляют для указания на неправильную многобайтовую последовательность, при этом возвращается (size_t)(-1), а значение errno меняется на EILSEQ.

2. В dest было сохранено len ненулевых широких символов. В этом случае *src оставляют для указания на следующую многобайтовую последовательность для преобразований, при этом возвращается количество широких символов, записанных в dest.

3. Многобайтовая строка была полностью преобразована, включая заключительный '\0' (который, помимо этого, возвращает *ps в исходное состояние). В этом случае *src устанавливается равным NULL и возвращается количество широких символов, записанных в dest, кроме заключительного символа L'\0'.

Если dest равно NULL, то len игнорируется и преобразование продолжается по схеме, описанной выше, за исключением того, что преобразованные широкие символы не записываются в память и что при записи не существует ограничений длины строки символов.

В обоих вышеперечисленных случаях, если ps является NULL-указателем, вместо него используется статическое анонимное состояние, известное только функции mbsnrtowcs.

Программист должен убедиться, что в dest существует достаточно места для размещения, по меньшей мере, len широких символов.

ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
Функция mbsrtowcs возвращает количество широких символов, которые составляют преобразованную часть строки широких символов и не содержат заключительный широкий null-символ. Если была встречена неправильная многобайтовая последовательность, то возвращается (size_t)(-1), а значение переменной errno меняется на EILSEQ.

СООТВЕТСТВИЕ СТАНДАРТАМ
ISO/ANSI C, UNIX98

СМ. ТАКЖЕ
mbstowcs(3), mbsnrtowcs(3), iconv(3)

ЗАМЕЧАНИЯ
Поведение mbsrtowcs зависит от категории LC_CTYPE текущей локали.

Использование NULL как ps для нескольких подпроцессов небезопасно.