embedaddon/libiconv/man/iconv.3.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / man / iconv.3.html
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue May 29 09:29:43 2012 UTC (12 years, 2 months ago) by misho
Branches: libiconv, MAIN
CVS tags: v1_14p0, v1_14, HEAD

libiconv v1.14

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