iconv

СИНТАКСИС

#include <iconv.h>

size_t iconv(iconv_t cd,
             char **restrict inbuf, size_t *restrict inbytesleft,
             char **restrict outbuf, size_t *restrict 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() также может преобразовать последовательность входных байт в простое обновление состояния преобразования без создания выходных байт; такие входные данные называются переключающей последовательностью. Процесс преобразования может прерваться в четырех случаях:

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

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

•: Неполная многобайтовая последовательность получена во входных данных и входная байтовая последовательность после неё заканчивается. В этом случае переменная errno устанавливается равной EINVAL и возвращается (size_t) -1. Значение *inbuf не меняется и указывает на начало неполной многобайтовой последовательности.

•: В буфере вывода нет места для очередного преобразованного символа. В этом случае значение 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 равным начальному состоянию.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

The iconv() function returns the number of characters converted in a nonreversible way during this call; reversible conversions are not counted. In case of error, iconv() returns (size_t) -1 and sets errno to indicate the error.

ОШИБКИ

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

E2BIG: Недостаточно места в *outbuf.

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

EINVAL: Во входных данных находится неполная многобайтовая последовательность.

ВЕРСИИ

This function is available since 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() должен проверить, что указатели, передаваемые в функцию, пригодны для доступа к символам в соответствующем наборе символов. К этому относится проверка корректности выравнивания для платформ, которые имеют жёсткие ограничения по выравниванию.

СМ. ТАКЖЕ

iconv_close(3), iconv_open(3), iconvconfig(8)

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <[email protected]>, Dmitriy S. Seregin <[email protected]>, Yuri Kozlov <[email protected]> и Иван Павлов <[email protected]>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на [email protected]

5 февраля 2023 г.

Linux man-pages 6.03