HP-UX Reference (11i v3 07/02) - 3 Library Functions A-M (vol 6)

i
iconv(3C) iconv(3C)
If a sequence of input bytes does not form a valid character in the specified codeset,
conversion stops after the previous successfully converted character. If the input
buffer ends with an incomplete character or shift sequence (see Special Usage section),
conversion stops after the previous successfully converted character. If the output
buffer is not large enough to hold the entire converted output, conversion stops just
prior to the character that would cause the output buffer to overflow. The variable
pointed to by inbuf is updated to point to the byte following the last byte successfully
used in the conversion. The value pointed to by inbyesleft is reduced to reflect the
number of bytes still not converted in the input buffer. The variable pointed to by out-
buf is updated to point to the byte following the last byte of converted output data.
The value pointed to by outbytesleft is reduced to reflect the number of bytes still
available in the output buffer.
If
iconv() encounters a character in the input buffer that is legal but for which an
identical character does not exist in the target codeset,
iconv() maps this character
to a pre-defined character, called the "galley character" that is defined at the 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 subse-
quent 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 encod-
ings, 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 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 indicate
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.
HP-UX 11i Version 3: February 2007 − 2 − Hewlett-Packard Company 661