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

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)