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