ИМЯ

mbsnrtowcs - преобразует многобайтовую строку в строку широких символов

ОБЗОР

#include <wchar.h>

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

Требования макроса тестирования свойств для glibc (смотрите feature_test_macros(7)):

mbsnrtowcs():

ОПИСАНИЕ

Функция mbsnrtowcs() похожа на функцию mbsrtowcs(3), исключая то, что количество преобразуемых байт, начиная с *src, ограничено nms байтами.

Если dest не равно NULL, то функция mbsnrtowcs() преобразует не более nms байт многобайтовой строки *src в строку широких символов, начинающуюся с dest. В dest будет записано не более len символов. Обновляется состояние сдвига *ps. Эффективное выполнение преобразования осуществляется повторяющимися вызовами mbrtowc(dest, *src, n, ps), где n — некое положительное число, и пока вызов завершается успешно, увеличивая dest на единицу и *src на количество использованных байт. Преобразование может остановиться по трём причинам:

1.

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

2.

Остановка происходит, если достигнуто ограничение nms или в dest было сохранено len не равных L'\0' широких символов. В этом случае *src продолжит указывать на следующую непреобразованную многобайтовую последовательность и будет возвращено количество широких символов, записанных в dest.

3.

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

Если входной буфер заканчивается неполным символом, в POSIX.1 не указано где остановится преобразование — в конце предыдущего символа (если есть) или в конце входного буфера. В реализации glibc принят первый вариант.

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

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

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

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

Функция mbsnrtowcs() возвращает количество широких символов, которые составили преобразованную часть широкосимвольной строки, не включая конечный широкий символ null. Если обнаружена некорректная многобайтовая последовательность, то возвращается (size_t) -1, а errno присваивается EILSEQ.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2008.

ЗАМЕЧАНИЯ

Поведение mbsnrtowcs() зависит от категории LC_CTYPE текущей локали.

Передавать NULL в качестве ps небезопасно при работе с нитями.

СМОТРИТЕ ТАКЖЕ

iconv(3), mbrtowc(3) mbsinit(3), mbsrtowcs(3)