WCSRTOMBS(3)

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

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

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

ОПИСАНИЕ
Если dest не является нулевым указателем, функция wcsrtombs преобразует строку широких символов *src в многобайтовую строку, начиная с dest. Максимум len байтов будет записано в dest. Состояние смещения в *ps будет, соответственно, обновлено. Замена происходит путем вызова wcrtomb (dest,*src,ps), повторяющегося до тех пор, пока вызов не происходит успешно. При этом значение dest увеличивается на число записанных байтов, а *src - на единицу. Замена может быть остановлена в трех случаях:

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

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

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

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

Следует убедиться, что выделено минимум len байтов для записи в dest.

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

СООТВЕТСТВИЕ СТАНДАРТАМ
ISO/ANSI C, UNIX98

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

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

Передача NULL в параметре ps не поддерживает многопоточность.