Provided by: manpages-ru-dev_4.19.0-7_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 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ или более позднюю, чтобы
узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.
Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте
электронное письмо на ⟨man-pages-ru-talks@lists.sourceforge.net⟩.