HP-UX Reference (11i v2 03/08) - 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 the 9.0
iconv inter-
faces, such as,
iconvopen(), iconvclose(), iconvsize()
, iconvlock(), ICONV(),
ICONV1(), and ICONV2().
Refer to the white paper entitled, HP-UX 9.0-11i Version 1.6 Internationalization Features White Paper
for an understanding 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 (3C). 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 output 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 section on Special
Usage), 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
HP-UX 11i Version 2: August 2003 − 1 − Hewlett-Packard Company Section 3−−507