WCSNRTOMBS(3)

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

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

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

ОПИСАНИЕ
Функция wcsnrtombs похожа на функцию wcsrtombs, исключая то, что количество преобразуемых широких символов, начиная с *src, ограничено nwc.

Если dest не является NULL-указателем, то функция wcsnrtombs преобразует максимум nwc широких символов из строки широких символов *src в многобайтовую строку, начинающуюся с dest. В dest записывается максимум len байтов. При этом производится обновление *ps. Преобразование производится путем повтора вызовов wcrtomb( dest, *src, ps) до тех пор, пока вызов этой функции не приведет к положительному результату, затем dest увеличивается на количество записанных байтов, а *src увеличивается на единицу. Преобразование может быть прервано по трем следующим причинам:

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

2. Было преобразовано nwc широких символов, и при этом не встретился символ L'\0'; достигнуто ограничение длины. В этом случае *src будет указывать на следующий широкий символ, подлежащий преобразованию, а функция вернет количество байтов, записанных в dest.

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

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

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

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

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

СООТВЕТСТВИЕ СТАНДАРТАМ
Эта функция является расширеним GNU.

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

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

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