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

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / libiconv / man / iconv.3.html
Revision 1.1.1.3 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Wed Mar 17 13:38:46 2021 UTC (4 years ago) by misho
Branches: libiconv, MAIN
CVS tags: v1_16p0, HEAD

libiconv 1.16

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