#include <iconv.h>
size_t iconv (cd, inbuf, inbytesleft,
outbuf, outbytesleft)
iconv_t cd;
char **inbuf;
size_t *inbytesleft;
char **outbuf;
size_t *outbytesleft;
The iconv() function converts a buffer of characters specified by the inbuf parameter from one coded character set identifier (CCSID) into another CCSID and stores the converted characters into a buffer specified by the outbuf parameter. (The inbuf parameter points to a variable that points to the first character in the input buffer. The outbuf 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 iconv_open() or the QtqIconvOpen() function.
On input, the inbytesleft parameter indicates the number of bytes in inbuf to be converted. Similarly, the outbytesleft parameter indicates the number of bytes available in outbuf. 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, iconv() changes the shift state of the conversion descriptor to match the shift state at the end of the input buffer. For subsequent calls to iconv(), conversion begins using the current shift state of the conversion descriptor. The only state-dependent encodings in which iconv() supports the updating of the conversion descriptor shift state is mixed-byte EBCDIC.
For encodings dependent on shift state, the conversion descriptor can be returned to its initial shift state by calling iconv() with inbuf equal to a null pointer, or with inbuf 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 iconv_open() and QtqIconvOpen() APIs. When iconv() is called with the conversion descriptor set in this way, iconv() begins conversion from the initial shift state.
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.
During conversion, iconv() 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, iconv() performs the conversion based on the conversion alternative specified on the iconv_open() function.
None.
The conversion descriptor returned by the iconv_open() or QtqIconvOpen() function that represents the following:
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.
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.
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.
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.
If an error occurs during one of the following requested conversions, the inbuf, inbytesleft, outbuf, and outbytesleft parameters may not be updated properly. (ES means encoding scheme.)
If the input length option field (on the call to iconv_open() or QtqIconvOpen()) is set for a NULL-terminated input buffer and the conversion completes successfully, the inbuf parameter is not updated for conversions involving the following encoding schemes:
If the input length option field (on the call to iconv_open() or QtqIconvOpen()) is set for a NULL-terminated input buffer and an error occurs during the conversion, the inbytesleft parameter is not updated for conversions involving the following encoding schemes:
If the entire input buffer is successfully converted, iconv() may return the number of nonidentical conversions performed based on the substitution alternative. See iconv_open()--Code Conversion Allocation API and QtqIconvOpen()--Code Conversion Allocation API. Otherwise, zero will be returned. If an error occurs, iconv() returns -1 in the return value, and sets errno to indicate the error.
The following errors can be returned in errno:
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.
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.
The conversion descriptor (cd) parameter is not valid.
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 QtqIconvOpen() or iconv_open() function.
This error is supported only for the following conversions:
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.
The conversion stopped because of an incomplete character or shift state sequence at the end of the input buffer.
The specified number of bytes for inbytesleft or outbytesleft is not valid. If the input length option field (on the call to iconv_open() or QtqIconvOpen()) specifies that iconv() determines the length of the input buffer and if iconv() cannot find a NULL character in the input buffer, this error could be returned.
Insufficient storage space was available to perform the conversion.
An undetected error occurred. Contact your service organization. An escape message may also be signaled as a result.
The following escape messages can be signaled:
| Message ID | Escape Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
This API is threadsafe if threads that share a conversion descriptor do not attempt to preserve the shift state.
| Top | National Language Support APIs | APIs by category |