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

i
iconv(3C) iconv(3C)
NAME
iconv(), iconv_open(), iconv_close() - codeset conversion routines
SYNOPSIS
#include <iconv.h>
iconv_t iconv_open(const char *
tocode, const char *fromcode);
size_t iconv(
iconv_t
cd,
const char **
inbuf,
size_t *
inbytesleft,
char **
outbuf,
size_t *
outbytesleft
);
int iconv_close(iconv_t
cd);
Remarks
These interfaces conform to the XPG4 standard, and should be used instead of the 9.0 iconv interfaces,
such as,
iconvopen() , iconvclose() , iconvsize() , iconvlock() , ICONV(), ICONV1(),
and ICONV2().
Refer to the white paper entitled, HP-UX 9.x - 11i Internationalization Features White Paper for an under-
standing of the conversion process. The white paper explains how
iconv uses tables and methods to do
the conversions. This white paper also shows you how to customize your own conversions. The white
paper is in www.docs.hp.com
.
DESCRIPTION
The entries in the
config.iconv file are the set of conversions that are supported by iconv()
. The
first two columns correspond to the fromcode and tocode names. These names may be directly used or their
corresponding aliases may be used as parameters to
iconv_open() .
iconv_open() Returns a conversion descriptor that describes a conversion from the codeset specified
by the string pointed to by the fromcode argument to the codeset specified by the
tocode argument.
A conversion descriptor remains valid in a process until that process closes it.
The fromcode and tocode arguments must have a corresponding entry in the
configuration file /usr/lib/nls/iconv/config.iconv
. (See FILES section.)
iconv() Converts a sequence of characters from one codeset that is contained in the array
specified by inbuf, into a sequence of corresponding characters in another codeset,
contained in the array specified by outbuf. The codesets are those specified in the
iconv_open() call that returned the conversion descriptor cd. The inbuf argu-
ment points to a variable that points to the first character in the input buffer and
inbytesleft indicates the number of remaining bytes in the buffer being converted. The
outbuf argument points to a variable that points to the first available byte in the out-
put buffer and outbytesleft indicates the number of the available remaining bytes in
the buffer.
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
630 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: December 2007 Update