ИМЯ¶

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.

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() можно использовать в нескольких нитях одновременно пока вызывающий не использует аргумент 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>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику по его адресу электронной почты или по адресу списка рассылки русских переводчиков.