[BACK]Return to iconv.3.html CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / man

Diff for /embedaddon/libiconv/man/iconv.3.html between versions 1.1.1.1 and 1.1.1.3

version 1.1.1.1, 2012/02/21 22:57:48 version 1.1.1.3, 2021/03/17 13:38:46
Line 1 Line 1
<!-- Creator     : groff version 1.18.1 --><!-- Creator     : groff version 1.22.3 -->
<!-- CreationDate: Tue Jun 30 22:52:08 2009 --><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
 <html>  <html>
 <head>  <head>
 <meta name="generator" content="groff -Thtml, see www.gnu.org">  <meta name="generator" content="groff -Thtml, see www.gnu.org">
   <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
 <meta name="Content-Style" content="text/css">  <meta name="Content-Style" content="text/css">
   <style type="text/css">
          p       { margin-top: 0; margin-bottom: 0; vertical-align: top }
          pre     { margin-top: 0; margin-bottom: 0; vertical-align: top }
          table   { margin-top: 0; margin-bottom: 0; vertical-align: top }
          h1      { text-align: center }
   </style>
 <title>ICONV</title>  <title>ICONV</title>
   
 </head>  </head>
 <body>  <body>
   
<h1 align=center>ICONV</h1><h1 align="center">ICONV</h1>
 
 <a href="#NAME">NAME</a><br>  <a href="#NAME">NAME</a><br>
 <a href="#SYNOPSIS">SYNOPSIS</a><br>  <a href="#SYNOPSIS">SYNOPSIS</a><br>
 <a href="#DESCRIPTION">DESCRIPTION</a><br>  <a href="#DESCRIPTION">DESCRIPTION</a><br>
Line 18 Line 28
 <a href="#SEE ALSO">SEE ALSO</a><br>  <a href="#SEE ALSO">SEE ALSO</a><br>
   
 <hr>  <hr>
   
   
   <h2>NAME
 <a name="NAME"></a>  <a name="NAME"></a>
<h2>NAME</h2></h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0"><p style="margin-left:11%; margin-top: 1em">iconv &minus;
<tr valign="top" align="left">perform character set conversion</p>
<td width="10%"></td>
<td width="89%"><h2>SYNOPSIS
<p>iconv &minus; perform character set conversion</p> 
</td> 
</table> 
 <a name="SYNOPSIS"></a>  <a name="SYNOPSIS"></a>
<h2>SYNOPSIS</h2></h2>
<!-- INDENTATION --> 
<table width="100%" border=0 rules="none" frame="void" 
       cols="2" cellspacing="0" cellpadding="0"> 
<tr valign="top" align="left"> 
<td width="10%"></td> 
<td width="89%"> 
<pre><b>#include &lt;iconv.h&gt; 
   
size_t iconv (iconv_t</b> <i>cd</i><b>,
              const char* *</b> <i>inbuf</i><b>, size_t *</b> <i>inbytesleft</i><b>,<p style="margin-left:11%; margin-top: 1em"><b>#include
              char* *</b> <i>outbuf</i><b>, size_t *</b> <i>outbytesleft</i><b>);&lt;iconv.h&gt;</b></p>
</b></pre>
</td><p style="margin-left:11%; margin-top: 1em"><b>size_t iconv
</table>(iconv_t</b> <i>cd</i><b>, <br>
 const char* *</b> <i>inbuf</i><b>, size_t *</b>
 <i>inbytesleft</i><b>, <br>
 char* *</b> <i>outbuf</i><b>, size_t *</b>
 <i>outbytesleft</i><b>);</b></p>
 
 <h2>DESCRIPTION
 <a name="DESCRIPTION"></a>  <a name="DESCRIPTION"></a>
<h2>DESCRIPTION</h2></h2>
<!-- INDENTATION --> 
   
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0"><p style="margin-left:11%; margin-top: 1em">The argument
<tr valign="top" align="left"><i>cd</i> must be a conversion descriptor created using the
<td width="10%"></td>function <b>iconv_open</b>.</p>
<td width="89%">
<p>The argument <i>cd</i> must be a conversion descriptor<p style="margin-left:11%; margin-top: 1em">The main case
created using the function <b>iconv_open</b>.</p>is when <i>inbuf</i> is not NULL and <i>*inbuf</i> is not
<!-- INDENTATION -->NULL. In this case, the <b>iconv</b> function converts the
<p>The main case is when <i>inbuf</i> is not NULL andmultibyte sequence starting at <i>*inbuf</i> to a multibyte
<i>*inbuf</i> is not NULL. In this case, the <b>iconv</b>sequence starting at <i>*outbuf</i>. At most
function converts the multibyte sequence starting at<i>*inbytesleft</i> bytes, starting at <i>*inbuf</i>, will
<i>*inbuf</i> to a multibyte sequence starting atbe read. At most <i>*outbytesleft</i> bytes, starting at
<i>*outbuf</i>. At most <i>*inbytesleft</i> bytes, starting<i>*outbuf</i>, will be written.</p>
at <i>*inbuf</i>, will be read. At most <i>*outbytesleft</i>
bytes, starting at <i>*outbuf</i>, will be written.</p><p style="margin-left:11%; margin-top: 1em">The
<!-- INDENTATION --><b>iconv</b> function converts one multibyte character at a
<p>The <b>iconv</b> function converts one multibytetime, and for each character conversion it increments
character at a time, and for each character conversion it<i>*inbuf</i> and decrements <i>*inbytesleft</i> by the
increments <i>*inbuf</i> and decrements <i>*inbytesleft</i>number of converted input bytes, it increments
by the number of converted input bytes, it increments 
 <i>*outbuf</i> and decrements <i>*outbytesleft</i> by the  <i>*outbuf</i> and decrements <i>*outbytesleft</i> by the
 number of converted output bytes, and it updates the  number of converted output bytes, and it updates the
 conversion state contained in <i>cd</i>. If the character  conversion state contained in <i>cd</i>. If the character
Line 77  can also convert a sequence of input bytes to an updat Line 84  can also convert a sequence of input bytes to an updat
 the conversion state without producing any output bytes;  the conversion state without producing any output bytes;
 such input is called a <i>shift sequence</i>. The conversion  such input is called a <i>shift sequence</i>. The conversion
 can stop for four reasons:</p>  can stop for four reasons:</p>
<!-- INDENTATION -->
<p>1. An invalid multibyte sequence is encountered in the<p style="margin-left:11%; margin-top: 1em">1. An invalid
input. In this case it sets <b>errno</b> to <b>EILSEQ</b>multibyte sequence is encountered in the input. In this case
and returns (size_t)(&minus;1). <i>*inbuf</i> is leftit sets <b>errno</b> to <b>EILSEQ</b> and returns
pointing to the beginning of the invalid multibyte(size_t)(&minus;1). <i>*inbuf</i> is left pointing to the
sequence.</p>beginning of the invalid multibyte sequence.</p>
<!-- INDENTATION -->
<p>2. The input byte sequence has been entirely converted,<p style="margin-left:11%; margin-top: 1em">2. The input
i.e. <i>*inbytesleft</i> has gone down to 0. In this casebyte sequence has been entirely converted, i.e.
 <i>*inbytesleft</i> has gone down to 0. In this case
 <b>iconv</b> returns the number of non-reversible  <b>iconv</b> returns the number of non-reversible
 conversions performed during this call.</p>  conversions performed during this call.</p>
<!-- INDENTATION -->
<p>3. An incomplete multibyte sequence is encountered in the<p style="margin-left:11%; margin-top: 1em">3. An
input, and the input byte sequence terminates after it. Inincomplete multibyte sequence is encountered in the input,
this case it sets <b>errno</b> to <b>EINVAL</b> and returnsand the input byte sequence terminates after it. In this
 case it sets <b>errno</b> to <b>EINVAL</b> and returns
 (size_t)(&minus;1). <i>*inbuf</i> is left pointing to the  (size_t)(&minus;1). <i>*inbuf</i> is left pointing to the
 beginning of the incomplete multibyte sequence.</p>  beginning of the incomplete multibyte sequence.</p>
<!-- INDENTATION -->
<p>4. The output buffer has no more room for the next<p style="margin-left:11%; margin-top: 1em">4. The output
converted character. In this case it sets <b>errno</b> tobuffer has no more room for the next converted character. In
<b>E2BIG</b> and returns (size_t)(&minus;1).</p>this case it sets <b>errno</b> to <b>E2BIG</b> and returns
<!-- INDENTATION --> 
<p>A different case is when <i>inbuf</i> is NULL or 
<i>*inbuf</i> is NULL, but <i>outbuf</i> is not NULL and 
<i>*outbuf</i> is not NULL. In this case, the <b>iconv</b> 
function attempts to set <i>cd</i>&rsquo;s conversion state 
to the initial state and store a corresponding shift 
sequence at <i>*outbuf</i>. At most <i>*outbytesleft</i> 
bytes, starting at <i>*outbuf</i>, will be written. If the 
output buffer has no more room for this reset sequence, it 
sets <b>errno</b> to <b>E2BIG</b> and returns 
(size_t)(&minus;1). Otherwise it increments <i>*outbuf</i> 
and decrements <i>*outbytesleft</i> by the number of bytes 
written.</p> 
<!-- INDENTATION --> 
<p>A third case is when <i>inbuf</i> is NULL or 
<i>*inbuf</i> is NULL, and <i>outbuf</i> is NULL or 
<i>*outbuf</i> is NULL. In this case, the <b>iconv</b> 
function sets <i>cd</i>&rsquo;s conversion state to the 
initial state.</p> 
</td> 
</table> 
<a name="RETURN VALUE"></a> 
<h2>RETURN VALUE</h2> 
<!-- INDENTATION --> 
<table width="100%" border=0 rules="none" frame="void" 
       cols="2" cellspacing="0" cellpadding="0"> 
<tr valign="top" align="left"> 
<td width="10%"></td> 
<td width="89%"> 
<p>The <b>iconv</b> function returns the number of 
characters converted in a non-reversible way during this 
call; reversible conversions are not counted. In case of 
error, it sets <b>errno</b> and returns 
 (size_t)(&minus;1).</p>  (size_t)(&minus;1).</p>
</td>
</table><p style="margin-left:11%; margin-top: 1em">A different
 case is when <i>inbuf</i> is NULL or <i>*inbuf</i> is NULL,
 but <i>outbuf</i> is not NULL and <i>*outbuf</i> is not
 NULL. In this case, the <b>iconv</b> function attempts to
 set <i>cd</i>&rsquo;s conversion state to the initial state
 and store a corresponding shift sequence at <i>*outbuf</i>.
 At most <i>*outbytesleft</i> bytes, starting at
 <i>*outbuf</i>, will be written. If the output buffer has no
 more room for this reset sequence, it sets <b>errno</b> to
 <b>E2BIG</b> and returns (size_t)(&minus;1). Otherwise it
 increments <i>*outbuf</i> and decrements
 <i>*outbytesleft</i> by the number of bytes written.</p>
 
 <p style="margin-left:11%; margin-top: 1em">A third case is
 when <i>inbuf</i> is NULL or <i>*inbuf</i> is NULL, and
 <i>outbuf</i> is NULL or <i>*outbuf</i> is NULL. In this
 case, the <b>iconv</b> function sets <i>cd</i>&rsquo;s
 conversion state to the initial state.</p>
 
 <h2>RETURN VALUE
 <a name="RETURN VALUE"></a>
 </h2>
 
 
 <p style="margin-left:11%; margin-top: 1em">The
 <b>iconv</b> function returns the number of characters
 converted in a non-reversible way during this call;
 reversible conversions are not counted. In case of error, it
 sets <b>errno</b> and returns (size_t)(&minus;1).</p>
 
 <h2>ERRORS
 <a name="ERRORS"></a>  <a name="ERRORS"></a>
<h2>ERRORS</h2></h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0"><p style="margin-left:11%; margin-top: 1em">The following
 errors can occur, among others:</p>
 
 <table width="100%" border="0" rules="none" frame="void"
        cellspacing="0" cellpadding="0">
 <tr valign="top" align="left">  <tr valign="top" align="left">
 <td width="10%"></td>  
 <td width="89%">  
 <p>The following errors can occur, among others:</p>  
 </td>  
 </table>  
 <!-- TABS -->  
 <table width="100%" border=0 rules="none" frame="void"  
        cols="3" cellspacing="0" cellpadding="0">  
 <tr valign="top" align="left">  
 <td width="11%"></td>  <td width="11%"></td>
<td width="10%"><td width="9%">
   
 <p><b>E2BIG</b></p>  
 </td>  
 <td width="77%">  
   
<p>There is not sufficient room at <i>*outbuf</i>.</p><p><b>E2BIG</b></p></td>
</td><td width="2%"></td>
 <td width="78%">
 
 
 <p>There is not sufficient room at <i>*outbuf</i>.</p></td></tr>
 <tr valign="top" align="left">  <tr valign="top" align="left">
 <td width="11%"></td>  <td width="11%"></td>
<td width="10%"><td width="9%">
   
 <p><b>EILSEQ</b></p>  
 </td>  
 <td width="77%">  
   
   <p><b>EILSEQ</b></p></td>
   <td width="2%"></td>
   <td width="78%">
   
   
 <p>An invalid multibyte sequence has been encountered in  <p>An invalid multibyte sequence has been encountered in
the input.</p>the input.</p></td></tr>
</td> 
 <tr valign="top" align="left">  <tr valign="top" align="left">
 <td width="11%"></td>  <td width="11%"></td>
<td width="10%"><td width="9%">
   
 <p><b>EINVAL</b></p>  
 </td>  
 <td width="77%">  
   
   <p><b>EINVAL</b></p></td>
   <td width="2%"></td>
   <td width="78%">
   
   
 <p>An incomplete multibyte sequence has been encountered in  <p>An incomplete multibyte sequence has been encountered in
the input.</p>the input.</p></td></tr>
</td> 
 </table>  </table>
   
   <h2>CONFORMING TO
 <a name="CONFORMING TO"></a>  <a name="CONFORMING TO"></a>
<h2>CONFORMING TO</h2></h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0"><p style="margin-left:11%; margin-top: 1em">POSIX:2001</p>
<tr valign="top" align="left">
<td width="10%"></td><h2>SEE ALSO
<td width="89%"> 
<p>POSIX:2001</p> 
</td> 
</table> 
 <a name="SEE ALSO"></a>  <a name="SEE ALSO"></a>
<h2>SEE ALSO</h2></h2>
<!-- INDENTATION -->
<table width="100%" border=0 rules="none" frame="void"
       cols="2" cellspacing="0" cellpadding="0">
<tr valign="top" align="left"><p style="margin-left:11%; margin-top: 1em"><b>iconv_open</b>(3),
<td width="10%"></td><b>iconvctl</b>(3) <b>iconv_close</b>(3)</p>
<td width="89%"> 
<p><b>iconv_open</b>(3), <b>iconvctl</b>(3) 
<b>iconv_close</b>(3)</p> 
</td> 
</table> 
 <hr>  <hr>
 </body>  </body>
 </html>  </html>
Removed from v.1.1.1.1  
changed lines
  Added in v.1.1.1.3

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>