HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

i
iconv(3C) iconv(3C)
time of table generation. (See genxlt(1)).
iconv_close()
Deallocates the conversion descriptor cd and all other associated resources allocated
by
iconv_open().
APPLICATION USAGE
Portable applications must assume that conversion descriptors are not valid after calls to any of the
exec functions.
Special Usage
In state-dependent encodings, the characters are interpreted depending on "state" of the input. State
shifts occur when a specific sequence of bytes are seen in the input. These sequences will change the way
subsequent characters are interpreted (that is, initially the characters may be single-byte characters,
after a state shift, subsequent characters may be interpreted as two-byte characters). For state-
dependent encodings, the conversion descriptor after
iconv_open() is in a codeset-dependent initial
shift state, ready for immediate use with
iconv().
For state-dependent encodings, the conversion descriptor cd is placed into its initial shift state by a call to
iconv() for which the inbuf is a null pointer, or for which inbuf points to a null pointer. When
iconv() is called in this way, and outbuf is not a null pointer or a pointer to a null pointer, and out-
bytesleft points to a positive value,
iconv() places the byte sequence to change the output buffer to its
initial shift state. If the output buffer is not large enough to hold the entire reset sequence,
iconv()
fails and sets errno to [E2BIG]. Subsequent calls with inbuf set to other than a null pointer or a
pointer to a null pointer cause the conversion to take place from the current state of the conversion
descriptor.
For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in effect at
the end of the last successfully converted byte sequence.
RETURN VALUE
iconv_open() Upon successful completion, iconv_open() returns a conversion descriptor for
use on subsequent calls to iconv(). Otherwise iconv_open() returns
(iconv_t)−1 and sets errno to indicate the error.
iconv() iconv() updates the variables pointed to by the arguments to reflect the extent of
conversion, and returns the the number of non-identical conversions performed. If
the entire string in the input buffer is converted, the value pointed to by inbytesleft
is zero. If an error occurs,
iconv() returns (size_t)−1 and sets errno
to indi-
cate the error.
iconv_close() Upon successful completion,
iconv_close() returns a value of zero. Otherwise
it returns −1 and sets
errno to indicate the error.
ERRORS
iconv_open() fails if any of the following conditions are encountered:
[ENOMEM] Insufficient storage space is available.
[EINVAL] The conversion specified by the fromcode and tocode is not supported, or the table or
method specified in the configuration file could not be read or loaded correctly. This
error will also occur if the configuration file itself is faulty.
iconv() fails if any of the following conditions are encountered:
[EILSEQ] Input conversion stopped due to an input character that does not belong to the input
codeset, or if the conversion table does not contain an entry corresponding to this
input character and a galley character was not defined for that particular table.
[E2BIG] Input conversion stopped due to lack of space in the output buffer.
[EINVAL] Input conversion stopped due to an incomplete character or shift sequence at the
end of the input buffer.
[EBADF] The cd argument is not a valid open conversion descriptor.
iconv_close() fails if any of the following conditions are encountered:
[EBADF] The conversion descriptor is invalid.
Section 3−−524 Hewlett-Packard Company − 2 − HP-UX 11i Version 2: September 2004