LinuxDoc.Rumbsnrtowcs - преобразует многобайтовую строку в строку широких символов
НАЗВАНИЕmbsnrtowcs - преобразует многобайтовую строку в строку
широких символов
СИНТАКСИС
#include
size_t mbsnrtowcs(wchar_t *dest, const char **src,
size_t nms, size_t len, mbstate_t *ps);
ОПИСАНИЕ
Функция mbsnrtowcs очень похожа на функцию mbsrtowcs, но
количество байтов, предназначенных для преобразования и
начинающихся с *src, ограничено до nms.
Если dest не является NULL-указателем, то функция mbsnr-
towcs преобразует максимум nms байтов из многобайтовой
строки *src в строку широких символов, начиная с dest.
Максимум len широких символов запишется в dest. Статус
смещения *ps обновляется. Преобразование эффективно
выполняется многократным вызовом mbrtowc(dest,*src,n,ps) ,
где n - некоторое положительное число (пока данный вызов
успешно работает) и последующим увеличением dest на
единицу и *src на количество "отработанных" байтов.
Преобразование может остановиться по трем следующим
причинам:
1. Была встречена неправильная многобайтовая
последовательность. В этом случае *src оставляется для
указания на неправильную многобайтовую последовательность,
возвращается (size_t)(-1), а значение errno меняется на
EILSEQ.
2. Был достигнут предел nms или в dest было сохранено len
широких ненулевых символов. В этом случае *src оставляют
для указания на следующую многобайтовую последовательность
преобразований; при этом возвращается количество широких
символов, записанных в dest.
3. Многобайтовая строка была полностью преобразована,
включая заключительный '\0' (который дополнительно
производит возвращение *ps в исходное состояние). В этом
случае *src устанавливается равным NULL, возвращается
количество широких символов, записанных в dest, кроме
заключительного символа L'\0'.
Если dest равно NULL, то len игнорируется и преобразование
продолжается по схеме, описанной выше, хотя
преобразованные широкие символы не записываются в память,
и при записи не существует ограничений длины
результирующего преобразования.
В обоих вышеперечисленных случаях, если ps является
NULL-указателем, вместо него используется статическое
анонимное состояние, известное только функции mbsnrtowcs.
Программист должен убедиться, что в dest существует
достаточно места хотя бы для len широких символов.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функция mbsnrtowcs возвращает количество широких символов,
которые составляют преобразованную часть строки широких
символов без учета заключительного широкого null-символа.
Если была встречена неправильная многобайтовая
последовательность, то возвращается (size_t)(-1), а
значение переменной errno меняется на EILSEQ.
СООТВЕТСТВИЕ СТАНДАРТАМ
Эта функция является расширением GNU.
ЗАМЕЧАНИЯ
Поведение mbsnrtowcs зависит от категории LC_CTYPE текущей
локали.
Применение NULL как ps для нескольких подпроцессов
небезопасно.