Return to iconv.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / man

Annotation of embedaddon/libiconv/man/iconv.3, revision 1.1

1.1     ! misho       1: .\" Copyright (c) Bruno Haible <bruno@clisp.org>
        !             2: .\"
        !             3: .\" This is free documentation; you can redistribute it and/or
        !             4: .\" modify it under the terms of the GNU General Public License as
        !             5: .\" published by the Free Software Foundation; either version 3 of
        !             6: .\" the License, or (at your option) any later version.
        !             7: .\"
        !             8: .\" References consulted:
        !             9: .\"   GNU glibc-2 source code and manual
        !            10: .\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
        !            11: .\"
        !            12: .TH ICONV 3  "September 7, 2008" "GNU" "Linux Programmer's Manual"
        !            13: .SH NAME
        !            14: iconv \- perform character set conversion
        !            15: .SH SYNOPSIS
        !            16: .nf
        !            17: .B #include <iconv.h>
        !            18: .sp
        !            19: .BI "size_t iconv (iconv_t " cd ,
        !            20: .BI "              const char* * " inbuf ", size_t * "inbytesleft ,
        !            21: .BI "              char* * " outbuf ", size_t * "outbytesleft );
        !            22: .fi
        !            23: .SH DESCRIPTION
        !            24: The argument \fIcd\fP must be a conversion descriptor created using the
        !            25: function \fBiconv_open\fP.
        !            26: .PP
        !            27: The main case is when \fIinbuf\fP is not NULL and \fI*inbuf\fP is not NULL.
        !            28: In this case, the \fBiconv\fP function converts the multibyte sequence
        !            29: starting at \fI*inbuf\fP to a multibyte sequence starting at \fI*outbuf\fP.
        !            30: At most \fI*inbytesleft\fP bytes, starting at \fI*inbuf\fP, will be read.
        !            31: At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
        !            32: .PP
        !            33: The \fBiconv\fP function converts one multibyte character at a time, and for
        !            34: each character conversion it increments \fI*inbuf\fP and decrements
        !            35: \fI*inbytesleft\fP by the number of converted input bytes, it increments
        !            36: \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of converted
        !            37: output bytes, and it updates the conversion state contained in \fIcd\fP.
        !            38: If the character encoding of the input is stateful, the \fBiconv\fP function
        !            39: can also convert a sequence of input bytes to an update of the conversion state
        !            40: without producing any output bytes; such input is called a \fIshift sequence\fP.
        !            41: The conversion can stop for four reasons:
        !            42: .PP
        !            43: 1. An invalid multibyte sequence is encountered in the input. In this case
        !            44: it sets \fBerrno\fP to \fBEILSEQ\fP and returns (size_t)(\-1). \fI*inbuf\fP
        !            45: is left pointing to the beginning of the invalid multibyte sequence.
        !            46: .PP
        !            47: 2. The input byte sequence has been entirely converted, i.e. \fI*inbytesleft\fP
        !            48: has gone down to 0. In this case \fBiconv\fP returns the number of
        !            49: non-reversible conversions performed during this call.
        !            50: .PP
        !            51: 3. An incomplete multibyte sequence is encountered in the input, and the
        !            52: input byte sequence terminates after it. In this case it sets \fBerrno\fP to
        !            53: \fBEINVAL\fP and returns (size_t)(\-1). \fI*inbuf\fP is left pointing to the
        !            54: beginning of the incomplete multibyte sequence.
        !            55: .PP
        !            56: 4. The output buffer has no more room for the next converted character. In
        !            57: this case it sets \fBerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1).
        !            58: .PP
        !            59: A different case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, but
        !            60: \fIoutbuf\fP is not NULL and \fI*outbuf\fP is not NULL. In this case, the
        !            61: \fBiconv\fP function attempts to set \fIcd\fP's conversion state to the
        !            62: initial state and store a corresponding shift sequence at \fI*outbuf\fP.
        !            63: At most \fI*outbytesleft\fP bytes, starting at \fI*outbuf\fP, will be written.
        !            64: If the output buffer has no more room for this reset sequence, it sets
        !            65: \fBerrno\fP to \fBE2BIG\fP and returns (size_t)(\-1). Otherwise it increments
        !            66: \fI*outbuf\fP and decrements \fI*outbytesleft\fP by the number of bytes
        !            67: written.
        !            68: .PP
        !            69: A third case is when \fIinbuf\fP is NULL or \fI*inbuf\fP is NULL, and
        !            70: \fIoutbuf\fP is NULL or \fI*outbuf\fP is NULL. In this case, the \fBiconv\fP
        !            71: function sets \fIcd\fP's conversion state to the initial state.
        !            72: .SH "RETURN VALUE"
        !            73: The \fBiconv\fP function returns the number of characters converted in a
        !            74: non-reversible way during this call; reversible conversions are not counted.
        !            75: In case of error, it sets \fBerrno\fP and returns (size_t)(\-1).
        !            76: .SH ERRORS
        !            77: The following errors can occur, among others:
        !            78: .TP
        !            79: .B E2BIG
        !            80: There is not sufficient room at \fI*outbuf\fP.
        !            81: .TP
        !            82: .B EILSEQ
        !            83: An invalid multibyte sequence has been encountered in the input.
        !            84: .TP
        !            85: .B EINVAL
        !            86: An incomplete multibyte sequence has been encountered in the input.
        !            87: .SH "CONFORMING TO"
        !            88: POSIX:2001
        !            89: .SH "SEE ALSO"
        !            90: .BR iconv_open (3),
        !            91: .BR iconvctl (3)
        !            92: .BR iconv_close (3)