Annotation of embedaddon/libiconv/man/iconv.3.html, revision 1.1.1.2
1.1.1.2 ! misho 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">
1.1 misho 5: <html>
6: <head>
7: <meta name="generator" content="groff -Thtml, see www.gnu.org">
1.1.1.2 ! misho 8: <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
1.1 misho 9: <meta name="Content-Style" content="text/css">
1.1.1.2 ! misho 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>
1.1 misho 16: <title>ICONV</title>
1.1.1.2 ! misho 17:
1.1 misho 18: </head>
19: <body>
20:
1.1.1.2 ! misho 21: <h1 align="center">ICONV</h1>
! 22:
1.1 misho 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>
1.1.1.2 ! misho 32:
! 33:
! 34: <h2>NAME
1.1 misho 35: <a name="NAME"></a>
1.1.1.2 ! misho 36: </h2>
! 37:
! 38:
! 39: <p style="margin-left:11%; margin-top: 1em">iconv −
! 40: perform character set conversion</p>
! 41:
! 42: <h2>SYNOPSIS
1.1 misho 43: <a name="SYNOPSIS"></a>
1.1.1.2 ! misho 44: </h2>
! 45:
! 46:
! 47: <p style="margin-left:11%; margin-top: 1em"><b>#include
! 48: <iconv.h></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
1.1 misho 58: <a name="DESCRIPTION"></a>
1.1.1.2 ! misho 59: </h2>
1.1 misho 60:
1.1.1.2 ! misho 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
1.1 misho 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>
1.1.1.2 ! misho 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)(−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
1.1 misho 98: <b>iconv</b> returns the number of non-reversible
99: conversions performed during this call.</p>
1.1.1.2 ! misho 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
1.1 misho 105: (size_t)(−1). <i>*inbuf</i> is left pointing to the
106: beginning of the incomplete multibyte sequence.</p>
1.1.1.2 ! misho 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
1.1 misho 111: (size_t)(−1).</p>
1.1.1.2 ! misho 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>’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)(−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>’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)(−1).</p>
! 142:
! 143: <h2>ERRORS
1.1 misho 144: <a name="ERRORS"></a>
1.1.1.2 ! misho 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">
1.1 misho 153: <tr valign="top" align="left">
154: <td width="11%"></td>
1.1.1.2 ! misho 155: <td width="9%">
! 156:
1.1 misho 157:
1.1.1.2 ! misho 158: <p><b>E2BIG</b></p></td>
! 159: <td width="2%"></td>
! 160: <td width="78%">
1.1 misho 161:
1.1.1.2 ! misho 162:
! 163: <p>There is not sufficient room at <i>*outbuf</i>.</p></td></tr>
1.1 misho 164: <tr valign="top" align="left">
165: <td width="11%"></td>
1.1.1.2 ! misho 166: <td width="9%">
! 167:
! 168:
! 169: <p><b>EILSEQ</b></p></td>
! 170: <td width="2%"></td>
! 171: <td width="78%">
1.1 misho 172:
173:
174: <p>An invalid multibyte sequence has been encountered in
1.1.1.2 ! misho 175: the input.</p></td></tr>
1.1 misho 176: <tr valign="top" align="left">
177: <td width="11%"></td>
1.1.1.2 ! misho 178: <td width="9%">
! 179:
! 180:
! 181: <p><b>EINVAL</b></p></td>
! 182: <td width="2%"></td>
! 183: <td width="78%">
1.1 misho 184:
185:
186: <p>An incomplete multibyte sequence has been encountered in
1.1.1.2 ! misho 187: the input.</p></td></tr>
1.1 misho 188: </table>
1.1.1.2 ! misho 189:
! 190: <h2>CONFORMING TO
1.1 misho 191: <a name="CONFORMING TO"></a>
1.1.1.2 ! misho 192: </h2>
! 193:
! 194:
! 195: <p style="margin-left:11%; margin-top: 1em">POSIX:2001</p>
! 196:
! 197: <h2>SEE ALSO
1.1 misho 198: <a name="SEE ALSO"></a>
1.1.1.2 ! misho 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>
1.1 misho 205: <hr>
206: </body>
207: </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