490 lines
14 KiB
HTML
490 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>iconv()--Code Conversion API</title>
|
|
<!-- Begin Header Records ========================================== -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
|
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
|
|
|
|
<!--File Edited December 2001 -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<!--End Header Records -->
|
|
<body>
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
<h2>iconv()--Code Conversion API</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
|
|
<br>
|
|
Syntax<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
|
|
<pre>
|
|
#include <iconv.h>
|
|
|
|
size_t <strong>iconv (<em>cd, inbuf, inbytesleft,
|
|
outbuf, outbytesleft</em>)
|
|
</strong>
|
|
|
|
iconv_t cd;
|
|
char **inbuf;
|
|
size_t *inbytesleft;
|
|
char **outbuf;
|
|
size_t *outbytesleft;
|
|
</pre>
|
|
|
|
<br>
|
|
Service Program: QTQICONV<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Conditional; see <a href="#USAGE_NOTES">Usage Notes</a>.<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>iconv()</strong> function converts a buffer of characters
|
|
specified by the <em>inbuf</em> parameter from one coded character set
|
|
identifier (CCSID) into another CCSID and stores the converted characters into
|
|
a buffer specified by the <em>outbuf</em> parameter. (The <em>inbuf</em>
|
|
parameter points to a variable that points to the first character in the input
|
|
buffer. The <em>outbuf</em> parameter points to a variable that points to the
|
|
first available byte in the output buffer.) The CCSIDs used are those in the
|
|
conversion descriptor, cd, which was returned from the call to either the
|
|
<strong>iconv_open()</strong> or the <strong>QtqIconvOpen()</strong>
|
|
function.</p>
|
|
|
|
<p>On input, the <em>inbytesleft</em> parameter indicates the number of bytes
|
|
in <em>inbuf</em> to be converted. Similarly, the <em>outbytesleft</em>
|
|
parameter indicates the number of bytes available in <em>outbuf</em>. These
|
|
values are decremented when the conversion is done, such that on return they
|
|
indicate the state of their associated buffers. For encodings dependent on
|
|
shift state, <strong>iconv()</strong> changes the shift state of the conversion
|
|
descriptor to match the shift state at the end of the input buffer. For
|
|
subsequent calls to <strong>iconv()</strong>, conversion begins using the
|
|
current shift state of the conversion descriptor. The only state-dependent
|
|
encodings in which <strong>iconv()</strong> supports the updating of the
|
|
conversion descriptor shift state is mixed-byte EBCDIC.</p>
|
|
|
|
<p>For encodings dependent on shift state, the conversion descriptor can be
|
|
returned to its initial shift state by calling <strong>iconv()</strong> with
|
|
<em>inbuf</em> equal to a null pointer, or with <em>inbuf</em> pointing to a
|
|
null pointer. The conversion descriptor can also be set to always return to its
|
|
initial shift state by specifying the appropriate shift state alternative on
|
|
the <strong>iconv_open()</strong> and <strong>QtqIconvOpen()</strong> APIs.
|
|
When <strong>iconv()</strong> is called with the conversion descriptor set in
|
|
this way, <strong>iconv()</strong> begins conversion from the initial shift
|
|
state.</p>
|
|
|
|
<p>If the input buffer ends with an incomplete character or shift sequence,
|
|
conversion stops after the previous successfully converted bytes. If the output
|
|
buffer is not large enough to hold the entire converted input, conversion stops
|
|
just prior to the input bytes that would cause the output buffer to
|
|
overflow.</p>
|
|
|
|
<p>During conversion, <strong>iconv()</strong> may encounter valid characters
|
|
in the input buffer that do not exist in the target CCSID. This is known as a
|
|
character mismatch. In this case, <strong>iconv()</strong> performs the
|
|
conversion based on the conversion alternative specified on the <strong>
|
|
iconv_open()</strong> function.</p>
|
|
|
|
<br>
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<!-- Use this if there are no authorities and locks. -->
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>cd</strong></dt>
|
|
|
|
<dd>INPUT
|
|
|
|
<p>The conversion descriptor returned by the <strong>iconv_open()</strong> or
|
|
<strong>QtqIconvOpen()</strong> function that represents the following:</p>
|
|
|
|
<ul>
|
|
<li>CCSIDs to convert from and to<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The conversion alternative to use for character mismatches<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The substitution alternative<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The shift-state alternative<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The input length option<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The error option for mixed data<br>
|
|
<br>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong>inbuf</strong></dt>
|
|
|
|
<dd>I/O
|
|
|
|
<p>A pointer to a variable (pointer) that points to the first character in the
|
|
input buffer. The variable (pointer) is updated to point to the byte following
|
|
the last byte successfully used in the conversion. The maximum size of the
|
|
input buffer is 16 773 104 bytes.</p>
|
|
</dd>
|
|
|
|
<dt><strong>inbytesleft</strong></dt>
|
|
|
|
<dd>I/O
|
|
|
|
<p>A pointer to a variable containing the number of bytes to the end of the
|
|
input buffer to be converted. This variable is decremented to reflect the
|
|
number of bytes still not converted in the input buffer. The maximum number of
|
|
bytes that can be converted is 16 773 104.</p>
|
|
</dd>
|
|
|
|
<dt><strong>outbuf</strong></dt>
|
|
|
|
<dd>OUTPUT
|
|
|
|
<p>A pointer to a variable (pointer) that points to the first available byte in
|
|
the output buffer. This variable (pointer) is updated to point to the byte
|
|
following the last byte of converted output data. The maximum size of the
|
|
output buffer is 16 773 104.</p>
|
|
</dd>
|
|
|
|
<dt><strong>outbytesleft</strong></dt>
|
|
|
|
<dd>I/O
|
|
|
|
<p>A pointer to a variable containing the number of the available bytes to the
|
|
end of the output buffer. This variable is decremented to reflect the number of
|
|
bytes still available in the output buffer. The maximum number of bytes
|
|
available is 16 773 104.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Restrictions</h3>
|
|
|
|
<p>If an error occurs during one of the following requested conversions, the
|
|
<em>inbuf</em>, <em>inbytesleft</em>, <em>outbuf</em>, and <em>
|
|
outbytesleft</em> parameters may not be updated properly. (ES means encoding
|
|
scheme.)</p>
|
|
|
|
<ul>
|
|
<li>EBCDIC mixed-byte (ES X'1301') to or from ASCII mixed-byte (ES X'2300')<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>EBCDIC mixed-byte (ES X'1301') to or from ASCII double-byte (ES
|
|
X'2200')<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>EBCDIC double-byte (ES X'1200') to or from ASCII mixed-byte (ES
|
|
X'2300')<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>EBCDIC double-byte (ES X'1200') to or from ASCII double-byte (ES
|
|
X'2200')</li>
|
|
</ul>
|
|
|
|
<p>If the input length option field (on the call to <strong>
|
|
iconv_open()</strong> or <strong>QtqIconvOpen()</strong>) is set for a
|
|
NULL-terminated input buffer and the conversion completes successfully, the
|
|
<em>inbuf</em> parameter is not updated for conversions involving the following
|
|
encoding schemes:</p>
|
|
|
|
<ul>
|
|
<li>Encoding scheme X'2300'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'4100'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'4403'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5100'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5200'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5404'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5405'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5700'<br>
|
|
<br>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>If the input length option field (on the call to <strong>
|
|
iconv_open()</strong> or <strong>QtqIconvOpen()</strong>) is set for a
|
|
NULL-terminated input buffer and an error occurs during the conversion, the
|
|
<em>inbytesleft</em> parameter is not updated for conversions involving the
|
|
following encoding schemes:</p>
|
|
|
|
<ul>
|
|
<li>Encoding scheme X'2300'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'4100'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'4403'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5100'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5200'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5404'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5405'<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Encoding scheme X'5700'</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<p>If the entire input buffer is successfully converted, <strong>
|
|
iconv()</strong> may return the number of nonidentical conversions performed
|
|
based on the substitution alternative. See <a href="iconvopn.htm">
|
|
iconv_open()--Code Conversion Allocation API</a> and <a href="QTQICONV.htm">
|
|
QtqIconvOpen()--Code Conversion Allocation API</a>. Otherwise, zero will be
|
|
returned.
|
|
|
|
If an error occurs, <strong>iconv()</strong> returns
|
|
-1 in the return value, and sets <strong>errno</strong> to indicate the
|
|
error.</p>
|
|
|
|
<br>
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>The following errors can be returned in <strong>errno</strong>:</p>
|
|
|
|
<dl>
|
|
<dt><strong>[E2BIG]</strong></dt>
|
|
|
|
<dd>Insufficient space.
|
|
|
|
<p>Conversion stopped due to lack of space in the output buffer or there was
|
|
not enough space to store the NULL character in the output buffer.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[EBADDATA]</strong></dt>
|
|
|
|
<dd>Shift state not valid in input data
|
|
|
|
<p>The beginning shift state of the input data buffer does not correspond to
|
|
the shift state of the conversion descriptor. A shift-state sequence was
|
|
encountered that tried to change the shift state of the input buffer to the
|
|
current shift state of the conversion descriptor. For example, an EBCDIC
|
|
shift-in control character may have been encountered while the conversion
|
|
descriptor indicated single-byte state. This error is only supported for EBCDIC
|
|
mixed-byte (X'1301') encoding schemes.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[EBADF]</strong></dt>
|
|
|
|
<dd>Descriptor not valid.
|
|
|
|
<p>The conversion descriptor (cd) parameter is not valid.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[ECONVERT]</strong></dt>
|
|
|
|
<dd>The mixed input data contained DBCS characters.
|
|
|
|
<p>Input conversion stopped due to the occurrence of DBCS characters in the
|
|
input data when converting from a mixed-byte encoding scheme. The shift state
|
|
for EBCDIC mixed data remains in the initial single-byte shift state. This
|
|
error can only be returned when the mixed error option has been set accordingly
|
|
for the <strong>QtqIconvOpen()</strong> or <strong>iconv_open()</strong>
|
|
function.</p>
|
|
|
|
<p>This error is supported only for the following conversions:</p>
|
|
|
|
<ul>
|
|
<li>EBCDIC mixed-byte (encoding scheme X'1301') to any single-byte encoding
|
|
scheme<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>ASCII mixed-byte (encoding scheme X'2300') to any single-byte encoding
|
|
scheme<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>EBCDIC mixed-byte (encoding scheme X'1301') to EBCDIC mixed-byte (encoding
|
|
scheme X'1301')<br>
|
|
<br>
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
|
|
<dt><strong>[EFAULT]</strong></dt>
|
|
|
|
<dd>Bad address
|
|
|
|
<p>The system detected an address that was not valid when attempting to use an
|
|
argument from the parameter list. An escape message may also be signaled as a
|
|
result.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[EINVAL]</strong></dt>
|
|
|
|
<dd>Parameter not valid.
|
|
|
|
<p>The conversion stopped because of an incomplete character or shift state
|
|
sequence at the end of the input buffer.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[ENOBUFS]</strong></dt>
|
|
|
|
<dd>Number of bytes for the input or output buffer not valid, or the input
|
|
length cannot be determined.
|
|
|
|
<p>The specified number of bytes for <em>inbytesleft</em> or <em>
|
|
outbytesleft</em> is not valid. If the input length option field (on the call
|
|
to <strong>iconv_open()</strong> or <strong>QtqIconvOpen()</strong>) specifies
|
|
that <strong>iconv()</strong> determines the length of the input buffer and if
|
|
<strong>iconv()</strong> cannot find a NULL character in the input buffer, this
|
|
error could be returned.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[ENOMEM]</strong></dt>
|
|
|
|
<dd>Not enough space
|
|
|
|
<p>Insufficient storage space was available to perform the conversion.</p>
|
|
</dd>
|
|
|
|
<dt><strong>[EUNKNOWN]</strong></dt>
|
|
|
|
<dd>Undetected error
|
|
|
|
<p>An undetected error occurred. Contact your service organization. An escape
|
|
message may also be signaled as a result.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>The following escape messages can be signaled:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Escape Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24B4 E</td>
|
|
<td valign="top">Severe error while addressing parameter list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
|
<td valign="top">Literal value cannot be changed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3CF2 E</td>
|
|
<td valign="top">Error(s) occurred during running of &1 API.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3><a name="USAGE_NOTES">Usage Notes</a></h3>
|
|
|
|
<p>This API is threadsafe if threads that share a conversion descriptor do not
|
|
attempt to preserve the shift state.</p>
|
|
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li><a href="iconvopn.htm">iconv_open()</a>--Code Conversion Allocation API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="QTQICONV.htm">QtqIconvOpen()</a>--Code Conversion Allocation
|
|
API<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="iconvcls.htm">iconv_close()</a>--Code Conversion Deallocation
|
|
API</li>
|
|
</ul>
|
|
|
|
<hr>
|
|
API introduced: V3R1
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"nls1.htm">National Language Support APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|