Provided by: manpages-ru-dev_4.21.0-2_all 
ИМЯ
iconv - изменяет кодировку символов
LIBRARY
Standard C library (libc, -lc)
СИНТАКСИС
#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 <azamat.hackimov@gmail.com>, Dmitriy
S. Seregin <dseregin@59.ru>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>
Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3
или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо
на man-pages-ru-talks@lists.sourceforge.net.
Linux man-pages 6.03 5 февраля 2023 г. iconv(3)