release/src-rt-6.x.4708/router/libiconv/man/iconv.3.html

   1 <!-- Creator     : groff version 1.20.1 -->
   2 <!-- CreationDate: Sun Aug  7 19:49:14 2011 -->
   3 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   4 "http://www.w3.org/TR/html4/loose.dtd">
   5 <html>
   6 <head>
   7 <meta name="generator" content="groff -Thtml, see www.gnu.org">
   8 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   9 <meta name="Content-Style" content="text/css">
  10 <style type="text/css">
  11        p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
  12        pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
  13        table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
  14        h1      { text-align: center }
  15 </style>
  16 <title>ICONV</title>
  17
  18 </head>
  19 <body>
  20
  21 <h1 align="center">ICONV</h1>
  22
  23 <a href="#NAME">NAME</a><br>
  24 <a href="#SYNOPSIS">SYNOPSIS</a><br>
  25 <a href="#DESCRIPTION">DESCRIPTION</a><br>
  26 <a href="#RETURN VALUE">RETURN VALUE</a><br>
  27 <a href="#ERRORS">ERRORS</a><br>
  28 <a href="#CONFORMING TO">CONFORMING TO</a><br>
  29 <a href="#SEE ALSO">SEE ALSO</a><br>
  30
  31 <hr>
  32
  33
  34 <h2>NAME
  35 <a name="NAME"></a>
  36 </h2>
  37
  38
  39 <p style="margin-left:11%; margin-top: 1em">iconv &minus;
  40 perform character set conversion</p>
  41
  42 <h2>SYNOPSIS
  43 <a name="SYNOPSIS"></a>
  44 </h2>
  45
  46
  47 <p style="margin-left:11%; margin-top: 1em"><b>#include
  48 &lt;iconv.h&gt;</b></p>
  49
  50 <p style="margin-left:11%; margin-top: 1em"><b>size_t iconv
  51 (iconv_t</b> <i>cd</i><b>, <br>
  52 const char* *</b> <i>inbuf</i><b>, size_t *</b>
  53 <i>inbytesleft</i><b>, <br>
  54 char* *</b> <i>outbuf</i><b>, size_t *</b>
  55 <i>outbytesleft</i><b>);</b></p>
  56
  57 <h2>DESCRIPTION
  58 <a name="DESCRIPTION"></a>
  59 </h2>
  60
  61
  62 <p style="margin-left:11%; margin-top: 1em">The argument
  63 <i>cd</i> must be a conversion descriptor created using the
  64 function <b>iconv_open</b>.</p>
  65
  66 <p style="margin-left:11%; margin-top: 1em">The main case
  67 is when <i>inbuf</i> is not NULL and <i>*inbuf</i> is not
  68 NULL. In this case, the <b>iconv</b> function converts the
  69 multibyte sequence starting at <i>*inbuf</i> to a multibyte
  70 sequence starting at <i>*outbuf</i>. At most
  71 <i>*inbytesleft</i> bytes, starting at <i>*inbuf</i>, will
  72 be read. At most <i>*outbytesleft</i> bytes, starting at
  73 <i>*outbuf</i>, will be written.</p>
  74
  75 <p style="margin-left:11%; margin-top: 1em">The
  76 <b>iconv</b> function converts one multibyte character at a
  77 time, and for each character conversion it increments
  78 <i>*inbuf</i> and decrements <i>*inbytesleft</i> by the
  79 number of converted input bytes, it increments
  80 <i>*outbuf</i> and decrements <i>*outbytesleft</i> by the
  81 number of converted output bytes, and it updates the
  82 conversion state contained in <i>cd</i>. If the character
  83 encoding of the input is stateful, the <b>iconv</b> function
  84 can also convert a sequence of input bytes to an update of
  85 the conversion state without producing any output bytes;
  86 such input is called a <i>shift sequence</i>. The conversion
  87 can stop for four reasons:</p>
  88
  89 <p style="margin-left:11%; margin-top: 1em">1. An invalid
  90 multibyte sequence is encountered in the input. In this case
  91 it sets <b>errno</b> to <b>EILSEQ</b> and returns
  92 (size_t)(&minus;1). <i>*inbuf</i> is left pointing to the
  93 beginning of the invalid multibyte sequence.</p>
  94
  95 <p style="margin-left:11%; margin-top: 1em">2. The input
  96 byte sequence has been entirely converted, i.e.
  97 <i>*inbytesleft</i> has gone down to 0. In this case
  98 <b>iconv</b> returns the number of non-reversible
  99 conversions performed during this call.</p>
 100
 101 <p style="margin-left:11%; margin-top: 1em">3. An
 102 incomplete multibyte sequence is encountered in the input,
 103 and the input byte sequence terminates after it. In this
 104 case it sets <b>errno</b> to <b>EINVAL</b> and returns
 105 (size_t)(&minus;1). <i>*inbuf</i> is left pointing to the
 106 beginning of the incomplete multibyte sequence.</p>
 107
 108 <p style="margin-left:11%; margin-top: 1em">4. The output
 109 buffer has no more room for the next converted character. In
 110 this case it sets <b>errno</b> to <b>E2BIG</b> and returns
 111 (size_t)(&minus;1).</p>
 112
 113 <p style="margin-left:11%; margin-top: 1em">A different
 114 case is when <i>inbuf</i> is NULL or <i>*inbuf</i> is NULL,
 115 but <i>outbuf</i> is not NULL and <i>*outbuf</i> is not
 116 NULL. In this case, the <b>iconv</b> function attempts to
 117 set <i>cd</i>&rsquo;s conversion state to the initial state
 118 and store a corresponding shift sequence at <i>*outbuf</i>.
 119 At most <i>*outbytesleft</i> bytes, starting at
 120 <i>*outbuf</i>, will be written. If the output buffer has no
 121 more room for this reset sequence, it sets <b>errno</b> to
 122 <b>E2BIG</b> and returns (size_t)(&minus;1). Otherwise it
 123 increments <i>*outbuf</i> and decrements
 124 <i>*outbytesleft</i> by the number of bytes written.</p>
 125
 126 <p style="margin-left:11%; margin-top: 1em">A third case is
 127 when <i>inbuf</i> is NULL or <i>*inbuf</i> is NULL, and
 128 <i>outbuf</i> is NULL or <i>*outbuf</i> is NULL. In this
 129 case, the <b>iconv</b> function sets <i>cd</i>&rsquo;s
 130 conversion state to the initial state.</p>
 131
 132 <h2>RETURN VALUE
 133 <a name="RETURN VALUE"></a>
 134 </h2>
 135
 136
 137 <p style="margin-left:11%; margin-top: 1em">The
 138 <b>iconv</b> function returns the number of characters
 139 converted in a non-reversible way during this call;
 140 reversible conversions are not counted. In case of error, it
 141 sets <b>errno</b> and returns (size_t)(&minus;1).</p>
 142
 143 <h2>ERRORS
 144 <a name="ERRORS"></a>
 145 </h2>
 146
 147
 148 <p style="margin-left:11%; margin-top: 1em">The following
 149 errors can occur, among others:</p>
 150
 151 <table width="100%" border="0" rules="none" frame="void"
 152        cellspacing="0" cellpadding="0">
 153 <tr valign="top" align="left">
 154 <td width="11%"></td>
 155 <td width="9%">
 156
 157
 158 <p><b>E2BIG</b></p></td>
 159 <td width="2%"></td>
 160 <td width="78%">
 161
 162
 163 <p>There is not sufficient room at <i>*outbuf</i>.</p></td></tr>
 164 <tr valign="top" align="left">
 165 <td width="11%"></td>
 166 <td width="9%">
 167
 168
 169 <p><b>EILSEQ</b></p></td>
 170 <td width="2%"></td>
 171 <td width="78%">
 172
 173
 174 <p>An invalid multibyte sequence has been encountered in
 175 the input.</p></td></tr>
 176 <tr valign="top" align="left">
 177 <td width="11%"></td>
 178 <td width="9%">
 179
 180
 181 <p><b>EINVAL</b></p></td>
 182 <td width="2%"></td>
 183 <td width="78%">
 184
 185
 186 <p>An incomplete multibyte sequence has been encountered in
 187 the input.</p></td></tr>
 188 </table>
 189
 190 <h2>CONFORMING TO
 191 <a name="CONFORMING TO"></a>
 192 </h2>
 193
 194
 195 <p style="margin-left:11%; margin-top: 1em">POSIX:2001</p>
 196
 197 <h2>SEE ALSO
 198 <a name="SEE ALSO"></a>
 199 </h2>
 200
 201
 202
 203 <p style="margin-left:11%; margin-top: 1em"><b>iconv_open</b>(3),
 204 <b>iconvctl</b>(3) <b>iconv_close</b>(3)</p>
 205 <hr>
 206 </body>
 207 </html>