ICONV(3)

НАЗВАНИЕ
iconv - изменяет кодировку набора символов

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

size_t iconv(iconv_t cd,
              char **inbuf, size_t *inbytesleft,
              char **outbuf, size_t *outbytesleft);

ОПИСАНИЕ
Аргумент cd должен быть параметром изменения кодировки, который создается с помощью функции iconv_open.

Основным случаем работы функции является ситуация, когда inbuf не равно NULL и *inbuf не равно NULL. В этом случае функция iconv преобразует многобайтовую последовательность, начиная с *inbuf, в многобайтовую последовательность, начиная с *outbuf. Максимальное количество считанных байтов будет равно *inbytesleft, начиная с *inbuf. Максимальное количество записанных байтов будет равно *outbytesleft, начиная с *outbuf.

Функция iconv преобразует один за другим символы последовательности и после каждого преобразования увеличивает *inbuf и уменьшает *inbytesleft на количество измененных байтов, увеличивает *outbuf и уменьшает *outbytesleft на количество измененных байтов, обновляет статус процесса перекодировки, указанный в cd. Процесс перекодировки прерывается в четырех случаях:

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

2. Входящая последовательность байтов была полностью перекодирована, то есть *inbytesleft уменьшилось до нуля. В этом случае iconv возвращает количество необратимых преобразований, выполненных функцией во время работы.

3. Функции на входе для обработки была предоставлена короткая (неполная) последовательность, и процесс перекодирования был остановлен после обработки данной последовательности. В этом случае переменная errno устанавливается равной EINVAL и возвращает (size_t)(-1). *inbuf не меняется и указывает на начало входящей неполной байтовой последовательности.

4. В буфере вывода нет места для очередного символа, кодировка которого должна быть изменена. В этом случае errno устанавливается равной E2BIG и возвращает (size_t)(-1).

Есть еще особый случай, когда inbuf равно NULL (или *inbuf равно NULL), при этом outbuf не равно NULL и *outbuf не равно NULL. В этом случае функция iconv пытается установить статус приведения cd в исходное состояние и сохранить измененную последовательность в *outbuf. Максимальное количество записанных байтов будет равно *outbytesleft (начиная с *outbuf). Если в буфере для вывода данных нет места для данной последовательности, то переменная errno устанавливается равной E2BIG и возвращается (size_t)(-1). Иначе увеличивается *outbuf и уменьшается *outbytesleft на количество записанных байтов.

В третьем случае, когда inbuf равно NULL (или *inbuf равно NULL) и outbuf равно NULL (или *outbuf равно NULL), функция iconv устанавливает статус преобразования cd равным начальному состоянию.

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

НАЙДЕННЫЕ ОШИБКИ
Среди прочих могут произойти и такие ошибки:

E2BIG
    (недостаточно места в *outbuf);

EILSEQ
    (на входе для обработки находится неправильная многобайтовая последовательность);

EINVAL
    (на входе для обработки находится неполная многобайтовая последовательность).

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

СМ. ТАКЖЕ
iconv_open(3), iconv_close(3)