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.2 --> 20<!-- CreationDate: Wed Jan 5 19:32:25 2005 --> 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%"> 27iconv - 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 <iconv.h> 36 37size_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%"> 48The argument <i>cd</i> must be a conversion descriptor 49created 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%"> 55The 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> 57function 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 60at <i>*inbuf</i>, will be read. At most <i>*outbytesleft</i> 61bytes, starting at <i>*outbuf</i>, will be 62written.</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%"> 68The <b>iconv</b> function converts one multibyte character 69at a time, and for each character conversion it increments 70<i>*inbuf</i> and decrements <i>*inbytesleft</i> by the 71number of converted input bytes, it increments 72<i>*outbuf</i> and decrements <i>*outbytesleft</i> by the 73number of converted output bytes, and it updates the 74conversion state contained in <i>cd</i>. The conversion can 75stop 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%"> 811. An invalid multibyte sequence is encountered in the 82input. In this case it sets <b>errno</b> to <b>EILSEQ</b> 83and returns (size_t)(-1). <i>*inbuf</i> is left pointing to 84the beginning of the invalid multibyte 85sequence.</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%"> 912. 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 94conversions 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%"> 1003. An incomplete multibyte sequence is encountered in the 101input, and the input byte sequence terminates after it. In 102this case it sets <b>errno</b> to <b>EINVAL</b> and returns 103(size_t)(-1). <i>*inbuf</i> is left pointing to the 104beginning 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%"> 1104. The output buffer has no more room for the next converted 111character. In this case it sets <b>errno</b> to <b>E2BIG</b> 112and 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%"> 118A 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> 121function attempts to set <i>cd</i>'s conversion state to the 122initial state and store a corresponding shift sequence at 123<i>*outbuf</i>. At most <i>*outbytesleft</i> bytes, starting 124at <i>*outbuf</i>, will be written. If the output buffer has 125no more room for this reset sequence, it sets <b>errno</b> 126to <b>E2BIG</b> and returns (size_t)(-1). Otherwise it 127increments <i>*outbuf</i> and decrements 128<i>*outbytesleft</i> by the number of bytes 129written.</td></table> 130 131<table width="100%" border=0 rules="none" frame="void" 132 cols="2" cellspacing="0" cellpadding="0"> 133<tr valign="top" align="left"> 134<td width="10%"></td><td width="90%"> 135A third case is when <i>inbuf</i> is NULL or <i>*inbuf</i> 136is NULL, and <i>outbuf</i> is NULL or <i>*outbuf</i> is 137NULL. In this case, the <b>iconv</b> function sets 138<i>cd</i>'s conversion state to the initial 139state.</td></table> 140<a name="RETURN VALUE"></a> 141<h2>RETURN VALUE</h2> 142 143<table width="100%" border=0 rules="none" frame="void" 144 cols="2" cellspacing="0" cellpadding="0"> 145<tr valign="top" align="left"> 146<td width="10%"></td><td width="90%"> 147The <b>iconv</b> function returns the number of characters 148converted in a non-reversible way during this call; 149reversible conversions are not counted. In case of error, it 150sets <b>errno</b> and returns (size_t)(-1).</td></table> 151<a name="ERRORS"></a> 152<h2>ERRORS</h2> 153 154<table width="100%" border=0 rules="none" frame="void" 155 cols="2" cellspacing="0" cellpadding="0"> 156<tr valign="top" align="left"> 157<td width="10%"></td><td width="90%"> 158The following errors can occur, among others:</td></table> 159 160<table width="100%" border=0 rules="none" frame="void" 161 cols="2" cellspacing="0" cellpadding="0"> 162<tr valign="top" align="left"> 163<td width="10%"></td><td width="90%"> 164<b>E2BIG</b></td></table> 165 166<table width="100%" border=0 rules="none" frame="void" 167 cols="2" cellspacing="0" cellpadding="0"> 168<tr valign="top" align="left"> 169<td width="21%"></td><td width="79%"> 170There is not sufficient room at <i>*outbuf</i>.</td></table> 171 172<table width="100%" border=0 rules="none" frame="void" 173 cols="2" cellspacing="0" cellpadding="0"> 174<tr valign="top" align="left"> 175<td width="10%"></td><td width="90%"> 176<b>EILSEQ</b></td></table> 177 178<table width="100%" border=0 rules="none" frame="void" 179 cols="2" cellspacing="0" cellpadding="0"> 180<tr valign="top" align="left"> 181<td width="21%"></td><td width="79%"> 182An invalid multibyte sequence has been encountered in the 183input.</td></table> 184 185<table width="100%" border=0 rules="none" frame="void" 186 cols="2" cellspacing="0" cellpadding="0"> 187<tr valign="top" align="left"> 188<td width="10%"></td><td width="90%"> 189<b>EINVAL</b></td></table> 190 191<table width="100%" border=0 rules="none" frame="void" 192 cols="2" cellspacing="0" cellpadding="0"> 193<tr valign="top" align="left"> 194<td width="21%"></td><td width="79%"> 195An incomplete multibyte sequence has been encountered in the 196input.</td></table> 197<a name="CONFORMING TO"></a> 198<h2>CONFORMING TO</h2> 199 200<table width="100%" border=0 rules="none" frame="void" 201 cols="2" cellspacing="0" cellpadding="0"> 202<tr valign="top" align="left"> 203<td width="10%"></td><td width="90%"> 204UNIX98</td></table> 205<a name="SEE ALSO"></a> 206<h2>SEE ALSO</h2> 207 208<table width="100%" border=0 rules="none" frame="void" 209 cols="2" cellspacing="0" cellpadding="0"> 210<tr valign="top" align="left"> 211<td width="10%"></td><td width="90%"> 212<b>iconv_open</b>(3), <b>iconvctl</b>(3), 213<b>iconv_close</b>(3)</td></table> 214<hr> 215</body> 216</html> 217