libiconv/man/iconv.3.html

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