MBRTOWC(3)

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

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

size_t mbrtowc(wchar_t *pwc, const char *s, size_t n, mbstate_t *ps);

ОПИСАНИЕ
Основной случай, определенный для этой функции, - когда s не равно NULL и pwc не равно NULL. В этом случае функция mbrtowc проверяет максимальное количество n байтов в многобайтовой строке, начиная с s, извлекает следующий полный многобайтовый символ, преобразует его в широкий символ и сохраняет его в *pwc. Статус смещения *ps обновляется. Если преобразованный широкий символ не равен L'\0', то возвращается количество байтов, которые использовались в s. Если преобразованный широкий символ равен L'\0', то статус смещения *ps становится начальным и возвращается 0.

Если в количество n байтов, начинающихся с s, не входит полный многобайтовый символ, то mbrtowc возвращает (size_t)(-2). Такое может случиться, если n >= MB_CUR_MAX или если многобайтовая строка содержит лишние последовательности смещения.

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

Если s не равно NULL, но pwc равно NULL, тогда функция mbrtowc ведет себя так, как описано выше (за исключением того, что она не сохраняет преобразованные широкие символы в памяти).

Третий случай - когда s равно NULL. Тогда pwc и n игнорируются. Если статус смещения, представленный *ps указывает на незавершенное преобразование, то функция mbrtowc возвращает (size_t)(-1), устанавливает errno в EILSEQ и оставляет *ps в неопределенном состоянии. Иначе функция mbrtowc переводит *ps в изначальное состояние и возвращает 0.

Во всех вышеперечисленных случаях, если ps является NULL-указателем, вместо него используется статическое анонимное состояние, известное только функции mbrtowc. В противном случае, *ps должен быть правильным объектом типа mbstate_t. Объект a типа mbstate_t может быть переведен в изначальное состояние заполнением его нулями, например

    memset(&a, 0, sizeof(a));

ВОЗВРАЩАЕМЫЕ ЗНАЧЕНИЯ
Функция mbrtowc возвращает количество байтов, выделенных из многобайтовой последовательности, начиная с s, если был распознан широкий символ non-L'\0'. Возвращается 0, если был распознан широкий символ L'\0'. Возвращается (size_t)(-1) и errno меняется на значение EILSEQ в случае, если была встречена неправильная многобайтовая последовательность. Возвращается (size_t)(-2), если не удалось выделить полный многобайтовый символ; при этом считается, что n должно увеличиться.

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

СМ. ТАКЖЕ
mbsrtowcs(3)

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