LinuxDoc.Ruwcsnrtombs - преобразование строки широких символов в многобайтовую строку
НАЗВАНИЕwcsnrtombs - преобразование строки широких символов в
многобайтовую строку
СИНТАКСИС
#include
size_t wcsnrtombs(char *dest, const wchar_t **src, size_t nwc,
size_t len, mbstate_t *ps);
ОПИСАНИЕ
Функция wcsnrtombs похожа на функцию wcsrtombs, исключая
то, что количество преобразуемых широких символов, начиная
с *src, ограничено nwc.
Если dest не является NULL-указателем, то функция wcsnr-
tombs преобразует максимум 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.
ЗАМЕЧАНИЯ
Поведение функции wcsnrtombs зависит от категории LC_CTYPE
текущей локали.
Передавать NULL в качестве ps небезопасно с точки зрения
работы подпроцессов.