.\" -*- coding: UTF-8 -*- .\" Copyright (c) Bruno Haible .\" .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA) .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of .\" the License, or (at your option) any later version. .\" %%%LICENSE_END .\" .\" 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 "15 сентября 2017 г." GNU "Руководство программиста Linux" .SH ИМЯ iconv \- изменяет кодировку символов .SH СИНТАКСИС .nf \fB#include \fP .PP \fBsize_t iconv(iconv_t \fP\fIcd\fP\fB,\fP \fB char **\fP\fIinbuf\fP\fB, size_t *\fP\fIinbytesleft\fP\fB,\fP \fB char **\fP\fIoutbuf\fP\fB, size_t *\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 Функция \fBiconv\fP() преобразует один многобайтовый символ за один раз и после каждого преобразования увеличивает \fI*inbuf\fP и уменьшает \fI*inbytesleft\fP на количество преобразованных входных байт, увеличивает \fI*outbuf\fP и уменьшает \fI*outbytesleft\fP на количество преобразованных выходных байт и обновляет состояние преобразования, содержащееся в \fIcd\fP. Если кодировка входных символов зависит от состояния, то функция \fBiconv\fP() также может преобразовать последовательность входных байт в простое обновление состояния преобразования без создания выходных байт; такие входные данные называются \fIпереключающей последовательностью\fP. Процесс преобразования может прерваться в четырех случаях: .IP 1. 3 Для обработки представлена неправильная многобайтная последовательность. В этом случае переменной \fIerrno\fP присваивается значение \fBEILSEQ\fP и возвращается значение \fI(size_t)\ \-1\fP. Значение \fI*inbuf\fP не меняется и указывает на начало неправильной многобайтной последовательности. .IP 2. Входящая последовательность байтов была полностью перекодирована, то есть \fI*inbytesleft\fP уменьшилось до нуля. В этом случае \fBiconv\fP() возвращает количество необратимых преобразований, выполненных функцией во время работы. .IP 3. Неполная многобайтовая последовательность получена во входных данных и входная байтовая последовательность после неё заканчивается. В этом случае переменная \fIerrno\fP устанавливается равной \fBEINVAL\fP и возвращается \fI(size_t)\ \-1\fP. Значение \fI*inbuf\fP не меняется и указывает на начало неполной многобайтовой последовательности. .IP 4. В буфере вывода нет места для очередного преобразованного символа. В этом случае значение \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 "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" Функция \fBiconv\fP() возвращает количество символов, необратимое изменение кодировки которых произошло в течение текущего вызова функции; возможные обратимые перекодировки не учитываются. В случае ошибок изменяется переменная \fIerrno\fP и возвращается \fI(size_t)\ \-1\fP. .SH ОШИБКИ Среди прочих могут возникнуть и такие ошибки: .TP \fBE2BIG\fP Недостаточно места в \fI*outbuf\fP. .TP \fBEILSEQ\fP Во входных данных находится неправильная многобайтовая последовательность. .TP \fBEINVAL\fP Во входных данных находится неполная многобайтовая последовательность. .SH ВЕРСИИ Эта функция доступна в glibc начиная с версии 2.1. .SH АТРИБУТЫ Описание терминов данного раздела смотрите в \fBattributes\fP(7). .TS allbox; lb lb lb l l l. Интерфейс Атрибут Значение T{ \fBiconv\fP() T} Безвредность в нитях MT\-Safe race:cd .TE .PP Функцию \fBiconv\fP() можно использовать в нескольких нитях одновременно пока вызывающий не использует аргумент \fIcd\fP где\-то ещё. .SH "СООТВЕТСТВИЕ СТАНДАРТАМ" POSIX.1\-2001, POSIX.1\-2008. .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) .SH ЗАМЕЧАНИЯ Эта страница является частью проекта Linux \fIman\-pages\fP версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу \%https://www.kernel.org/doc/man\-pages/. .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 .