HP-UX Reference (11i v1 00/12) - 3 Library Functions A-M (vol 6)
__________________________________________________________________________________________________________________________________________________________________________________________________
__________________________________________________________________________________________________________________________________________________________________________________________________
STANDARD Printed by: Nora Chuang [nchuang] STANDARD
/build/1111/BRICK/man3/!!!intro.3c
________________________________________________________________
___ ___
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 interfaces,
such as,
iconvopen() , iconvclose() , iconvsize() ,
iconvlock() , ICONV(), ICONV1(),
and
ICONV2().
Refer to the white paper entitled, iconv Customization, 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
/usr/share/doc/iconv.ps
(postscript file) and /usr/share/doc/iconv.txt (plain ASCII
text file).
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, con-
tained in the array specified by outbuf. The codesets are those specified in the
iconv_open() call that returned the conversion descriptor cd. The inbuf argument
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 argu-
ment 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 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
HP-UX Release 11i: December 2000 − 1 − Section 3−−435
___
___