wcsrtombs - преобразует широкосимвольную строку в многобайтовую строку
wcsrtombs(3)
преобразует широкосимвольную строку в многобайтовую строку
ОБЗОР
#include <wchar.h>
size_t wcsrtombs(char *dest, const wchar_t **src,
size_t len, mbstate_t *ps);
ОПИСАНИЕ
Если
dest не равно NULL, функция
wcsrtombs() преобразует
широкосимвольную строку
*src в многобайтовую строку, начиная с
dest. В
dest будет записано максимум
len байтов. Обновляется состояние
смещения в
*ps. Замена происходит путем повторяющихся вызовов
wcrtomb(dest, *src, ps) до тех пор, пока они выполняются без ошибок. При
этом значение
dest увеличивается на количество записанных байтов, а
*src — на единицу. Замена может быть остановлена в трех случаях:
1. Встретившийся широкий символ нельзя представить в виде многобайтовой
последовательности (в соответствии с текущей системной локалью). В этом
случае *src будет указывать на неправильный широкий символ, возвращается
(size_t) -1, а значение errno становится равным EILSEQ.
2. Остановка при достижении ограничения длины. В этом случае *src также
будет указывать на следующий широкий символ, подлежащий преобразованию, и
возвращается количество байтов, записанных в dest.
3. Широкосимвольная строка была полностью преобразована, включая завершающий
широкий символ null (L'\0') (побочный эффект: *ps возвращается в
начальное состояние). В этом случае *src устанавливается равным NULL и
возвращается количество байтов, записанных в dest, не считая завершающего
байта null ('\0').
Если значение dest равно NULL, то len игнорируется и преобразование
выполняется как описано выше, исключая то, что преобразованные байты не
записываются в память и нет ограничения по длине.
В обоих перечисленных случаях, если ps равно NULL, то используется
статическое анонимное состояние, известное только функции wcsrtombs().
Программист должен быть уверен, что в dest достаточно места для, по
крайней мере, len байт.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функция
wcsrtombs() возвращает количество байт в полученной многобайтовой
последовательности, не включая завершающий байт null. Если встречается
широкий символ, который невозможно преобразовать, возвращается
(size_t) -1 и значение
errno становится равным
EILSEQ.
АТРИБУТЫ
Описание терминов данного раздела смотрите в
attributes(7).
Интерфейс Атрибут Значение
wcsrtombs()
безвредность в потоках: небезопасно (MT-Unsafe race:wcrtombs/!ps)
СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008, C99.
ЗАМЕЧАНИЯ
Поведение
wcsrtombs() зависит от категории
LC_CTYPE текущей локали.
Передавать NULL в качестве ps небезопасно при работе с нитями.