Return to iconv.3 CVS log

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

libiconv

    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)