ОБЗОР

#include <wchar.h>

---

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

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

wcsnrtombs():

Начиная с glibc 2.10:

_XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L

До glibc 2.10:

_GNU_SOURCE

ОПИСАНИЕ

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

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

1.

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

2.

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

3.

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

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

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

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

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

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

АТРИБУТЫ

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

Интерфейс	Атрибут	Значение
wcsnrtombs()	безвредность в нитях	небезопасно (MT-Unsafe race:wcsnrtombs//!ps)

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

POSIX.1-2008.

ЗАМЕЧАНИЯ

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

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