HP-UX Reference (11i v3 07/02) - 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 11.0 - 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 http://docs.hp.com
.
DESCRIPTION
The
iconv_open() routine uses two configuration files, system.config.iconv
and
config.iconv residing in the /usr/lib/nls/iconv
directory. The entries in the
system.config.iconv
and config.iconv file are the set of conversions (codeset names) 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 files
/usr/lib/nls/iconv/system.config.iconv
or
/usr/lib/nls/iconv/config.iconv
.
The system file
/usr/lib/nls/iconv/system.config.iconv
can not be
modified and contains codeset names supported by the operating system.
/usr/lib/nls/iconv/config.iconv
can be modified by the user for custom-
ization.
iconv_open() searches the codeset names first in
/usr/lib/nls/iconv/system.config.iconv
and then in
/usr/lib/nls/iconv/config.iconv to check if the requested conversion is
supported. If so,
iconv_open() determines which table and/or method to use for
the conversion.
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.
660 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007