iconv.3c (2010 09)

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 sec-
tion), 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 outbuf is updated to point to the byte following the last byte of con-
verted 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 charac-
ter 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
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 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.
2 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: September 2010