ИМЯ

iconv - изменяет кодировку символов

ОБЗОР

#include <iconv.h>

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

ОПИСАНИЕ

Функция iconv() преобразует последовательность символов с одной кодировкой в последовательность символов с другой кодировкой. Аргумент cd должен быть дескриптором преобразования, созданным ранее с помощью функции iconv_open(3); дескриптор преобразования определяет кодировки символов, которые iconv() использует для преобразования. Аргумент inbuf содержит адрес переменной, которая указывает на первый символ входной последовательности; в inbytesleft содержится количество байт в этом буфере. В аргументе outbuf содержится адрес переменной, которая указывает на первый байт выходного буфера; в outbytesleft содержится количество байт в выходном буфере.

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

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

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 и возвращается (size_t) -1.

ОШИБКИ

Среди прочих могут возникнуть и такие ошибки:

E2BIG: Недостаточно места в *outbuf.
EILSEQ: Во входных данных находится неправильная многобайтовая последовательность.
EINVAL: Во входных данных находится неполная многобайтовая последовательность.

ВЕРСИИ

Эта функция доступна в glibc начиная с версии 2.1.

АТРИБУТЫ

Описание терминов данного раздела смотрите в attributes(7).

Интерфейс	Атрибут	Значение
iconv()	Безвредность в нитях	MT-Safe race:cd

Функцию iconv() можно использовать в нескольких нитях одновременно пока вызывающий не использует аргумент cd где-то ещё.

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

POSIX.1-2001, POSIX.1-2008.

ЗАМЕЧАНИЯ

В каждой последовательности вызовов iconv() у последнего значение inbuf или *inbuf должно быть равно NULL (для немедленного вывода остатка преобразованных данных).

Хотя inbuf и outbuf имеют тип char **, это не означает, что объекты, на которые они указывают, могут восприниматься как строки Си или массивы символов: реальное значение символьной последовательности байтов скрыто в преобразующих функциях. В некоторых кодировках нулевой байт может быть частью многобайтовой последовательности.

Вызывающий iconv() должен проверить, что указатели, передаваемые в функцию, пригодны для доступа к символам в соответствующем наборе символов. К этому относится проверка корректности выравнивания для платформ, которые имеют жёсткие ограничения по выравниванию.

ИМЯ