.\" -*- coding: UTF-8 -*- '\" t .\" Copyright (c) Bruno Haible .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" References consulted: .\" GNU glibc-2 source code and manual .\" OpenGroup's Single UNIX specification .\" http://www.UNIX-systems.org/online.html .\" .\" 2000-06-30 correction by Yuichi SATO .\" 2000-11-15 aeb, fixed prototype .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH iconv 3 "20 июля 2023 г." "Linux man\-pages 6.05.01" .SH ИМЯ iconv \- изменяет кодировку символов .SH LIBRARY Standard C library (\fIlibc\fP, \fI\-lc\fP) .SH СИНТАКСИС .nf \fB#include \fP .PP \fBsize_t iconv(iconv_t \fP\fIcd\fP\fB,\fP \fB char **restrict \fP\fIinbuf\fP\fB, size_t *restrict \fP\fIinbytesleft\fP\fB,\fP \fB char **restrict \fP\fIoutbuf\fP\fB, size_t *restrict \fP\fIoutbytesleft\fP\fB);\fP .fi .SH ОПИСАНИЕ Функция \fBiconv\fP() преобразует последовательность символов с одной кодировкой в последовательность символов с другой кодировкой. Аргумент \fIcd\fP должен быть дескриптором преобразования, созданным ранее с помощью функции \fBiconv_open\fP(3); дескриптор преобразования определяет кодировки символов, которые \fBiconv\fP() использует для преобразования. Аргумент \fIinbuf\fP содержит адрес переменной, которая указывает на первый символ входной последовательности; в \fIinbytesleft\fP содержится количество байт в этом буфере. В аргументе \fIoutbuf\fP содержится адрес переменной, которая указывает на первый байт выходного буфера; в \fIoutbytesleft\fP содержится количество байт в выходном буфере. .PP В основной рабочей ситуации значение \fIinbuf\fP не равно NULL и \fI*inbuf\fP не равно NULL. В этом случае функция \fBiconv\fP() преобразует многобайтовую последовательность с начала \fI*inbuf\fP, в многобайтовую последовательность с начала \fI*outbuf\fP. Максимальное количество считанных байт будет равно \fI*inbytesleft\fP, начиная с \fI*inbuf\fP. Максимальное количество записанных байт будет равно \fI*outbytesleft\fP, начиная с \fI*outbuf\fP. .PP The \fBiconv\fP() function converts one multibyte character at a time, and for each character conversion it increments \fI*inbuf\fP and decrements \fI*inbytesleft\fP by the number of converted input bytes, it increments \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted output bytes, and it updates the conversion state contained in \fIcd\fP. If the character encoding of the input is stateful, the \fBiconv\fP() 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 \fIshift sequence\fP. The conversion can stop for five reasons: .IP \[bu] 3 Для обработки представлена неправильная многобайтная последовательность. В этом случае переменной \fIerrno\fP присваивается значение \fBEILSEQ\fP и возвращается значение \fI(size_t)\ \-1\fP. Значение \fI*inbuf\fP не меняется и указывает на начало неправильной многобайтной последовательности. .IP \[bu] 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 \fIcd\fP was created without the suffix \fB//TRANSLIT\fP or \fB//IGNORE\fP, the conversion is strict: lossy conversions produce this condition. If the suffix \fB//TRANSLIT\fP was specified, transliteration can avoid this condition in some cases. In the musl C library, this condition cannot occur because a conversion to \fB\[aq]*\[aq]\fP is used as a fallback. In the FreeBSD, NetBSD, and Solaris implementations of \fBiconv\fP(), this condition cannot occur either, because a conversion to \fB\[aq]?\[aq]\fP is used as a fallback. When this condition is met, \fBiconv\fP() sets \fIerrno\fP to \fBEILSEQ\fP and returns \fI(size_t)\ \-1\fP. \fI*inbuf\fP is left pointing to the beginning of the unconvertible multibyte sequence. .IP \[bu] Входящая последовательность байтов была полностью перекодирована, то есть \fI*inbytesleft\fP уменьшилось до нуля. В этом случае \fBiconv\fP() возвращает количество необратимых преобразований, выполненных функцией во время работы. .IP \[bu] Неполная многобайтовая последовательность получена во входных данных и входная байтовая последовательность после неё заканчивается. В этом случае переменная \fIerrno\fP устанавливается равной \fBEINVAL\fP и возвращается \fI(size_t)\ \-1\fP. Значение \fI*inbuf\fP не меняется и указывает на начало неполной многобайтовой последовательности. .IP \[bu] В буфере вывода нет места для очередного преобразованного символа. В этом случае значение \fIerrno\fP устанавливается равным \fBE2BIG\fP и возвращается \fI(size_t)\ \-1\fP. .PP Особым случаем считается вариант, когда \fIinbuf\fP равно NULL или \fI*inbuf\fP равно NULL, но при этом \fIoutbuf\fP не равно NULL и \fI*outbuf\fP не равно NULL. В этом случае функция \fBiconv\fP() пытается установить состояние преобразования \fIcd\fP в начальное состояние и сохранить переключающую последовательность в \fI*outbuf\fP. Максимальное количество записанных байтов будет равно \fI*outbytesleft\fP, начиная с \fI*outbuf\fP. Если в буфере вывода данных нет места для данной последовательности сброса, то переменная \fIerrno\fP устанавливается равной \fBE2BIG\fP и возвращается \fI(size_t)\ \-1\fP. В противном случае увеличивается \fI*outbuf\fP и уменьшается \fI*outbytesleft\fP на количество записанных байтов. .PP В третьем случае, когда \fIinbuf\fP равно NULL или \fI*inbuf\fP равно NULL, и \fIoutbuf\fP равно NULL или \fI*outbuf\fP равно NULL, функция \fBiconv\fP() устанавливает состояние преобразования \fIcd\fP равным начальному состоянию. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" The \fBiconv\fP() function returns the number of characters converted in a nonreversible way during this call; reversible conversions are not counted. In case of error, \fBiconv\fP() returns \fI(size_t)\ \-1\fP and sets \fIerrno\fP to indicate the error. .SH ОШИБКИ Среди прочих могут возникнуть и такие ошибки: .TP \fBE2BIG\fP Недостаточно места в \fI*outbuf\fP. .TP \fBEILSEQ\fP Во входных данных находится неправильная многобайтовая последовательность. .TP \fBEINVAL\fP Во входных данных находится неполная многобайтовая последовательность. .SH АТРИБУТЫ Описание терминов данного раздела смотрите в \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. Интерфейс Атрибут Значение T{ .na .nh \fBiconv\fP() T} Безвредность в нитях MT\-Safe race:cd .TE .sp 1 .PP Функцию \fBiconv\fP() можно использовать в нескольких нитях одновременно пока вызывающий не использует аргумент \fIcd\fP где\-то ещё. .SH СТАНДАРТЫ POSIX.1\-2008. .SH ИСТОРИЯ glibc 2.1. POSIX.1\-2001. .SH ЗАМЕЧАНИЯ В каждой последовательности вызовов \fBiconv\fP() у последнего значение \fIinbuf\fP или \fI*inbuf\fP должно быть равно NULL (для немедленного вывода остатка преобразованных данных). .PP Хотя \fIinbuf\fP и \fIoutbuf\fP имеют тип \fIchar\ **\fP, это не означает, что объекты, на которые они указывают, могут восприниматься как строки Си или массивы символов: реальное значение символьной последовательности байтов скрыто в преобразующих функциях. В некоторых кодировках нулевой байт может быть частью многобайтовой последовательности. .PP Вызывающий \fBiconv\fP() должен проверить, что указатели, передаваемые в функцию, пригодны для доступа к символам в соответствующем наборе символов. К этому относится проверка корректности выравнивания для платформ, которые имеют жёсткие ограничения по выравниванию. .SH "СМ. ТАКЖЕ" \fBiconv_close\fP(3), \fBiconv_open\fP(3), \fBiconvconfig\fP(8) .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Azamat Hackimov , Dmitriy S. Seregin , Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .