Provided by: manpages-ru-dev_4.27.0-1_all 
НАИМЕНОВАНИЕ
iconv - изменяет кодировку символов
БИБЛИОТЕКА
Стандартная библиотека языка C (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.
The iconv() function converts one multibyte character at a time, and for each character conversion it
increments *inbuf and decrements *inbytesleft by the number of converted input bytes, it increments
*outbuf and decrements *outbytesleft by the number of converted output bytes, and it updates the
conversion state contained in cd. If the character encoding of the input is stateful, the iconv()
function can also convert a sequence of input bytes to an update to the conversion state without
producing any output bytes; such input is called a shift sequence. The conversion can stop for five
reasons:
• Для обработки представлена неправильная многобайтная последовательность. В этом случае переменной
errno присваивается значение EILSEQ и возвращается значение (size_t) -1. Значение *inbuf не меняется
и указывает на начало неправильной многобайтной последовательности.
• A multibyte sequence is encountered that is valid but that cannot be translated to the character
encoding of the output. This condition depends on the implementation and on the conversion
descriptor. In the GNU C library and GNU libiconv, if cd was created without the suffix //TRANSLIT or
//IGNORE, the conversion is strict: lossy conversions produce this condition. If the suffix
//TRANSLIT was specified, transliteration can avoid this condition in some cases. In the musl C
library, this condition cannot occur because a conversion to '*' is used as a fallback. In the
FreeBSD, NetBSD, and Solaris implementations of iconv(), this condition cannot occur either, because a
conversion to '?' is used as a fallback. When this condition is met, iconv() sets errno to EILSEQ
and returns (size_t) -1. *inbuf is left pointing to the beginning of the unconvertible multibyte
sequence.
• Входящая последовательность байтов была полностью перекодирована, то есть *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 Во входных данных находится неполная многобайтовая последовательность.
АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
┌──────────────────────────────────────────────────────────────┬──────────────────────┬─────────────────┐
│ Интерфейс │ Атрибут │ Значение │
├──────────────────────────────────────────────────────────────┼──────────────────────┼─────────────────┤
│ iconv() │ Безвредность в нитях │ MT-Safe race:cd │
└──────────────────────────────────────────────────────────────┴──────────────────────┴─────────────────┘
Функцию iconv() можно использовать в нескольких нитях одновременно пока вызывающий не использует аргумент
cd где-то ещё.
СТАНДАРТЫ
POSIX.1-2008.
ИСТОРИЯ
glibc 2.1. POSIX.1-2001.
ПРИМЕЧАНИЯ
В каждой последовательности вызовов 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> и
Kirill Rekhov <krekhov.dev@gmail.com>
Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной
лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или
более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.
Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом
разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских
переводчиков.
Справочные страницы Linux 6.9.1 2 мая 2024 г. iconv(3)