iconv.3c (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

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);

DESCRIPTION

The iconv_open() routine uses the following iconv conﬁguration ﬁles in descending order of pre-

cedence:

•

/usr/lib/nls/iconv/system.config.iconv

• /usr/lib/nls/iconv/config.iconv

The system ﬁle /usr/lib/nls/iconv/system.config.iconv

is searched ﬁrst. It cannot be

modiﬁed and contains codeset names supported by the operating system. The

/usr/lib/nls/iconv/config.iconv

ﬁle, on the other hand, is user-modiﬁable and can be used by

the system adminstrator or third-party applications to add custom iconv converters.

The conﬁguration ﬁles are divided into two sections. The ﬁrst section is for deﬁning aliases to the canoni-

cal codeset names used in the second section. It is ended by the keyword

end_aliases. The second

section contains the set of conversions (codeset names) that are supported by iconv(). The ﬁrst 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(). The remaining three columns

corresponds to the name of the translation table, the iconv method, and the corresponding

mblen()

function name and method library (for multi-byte codeset).

The symbol

- is used if the columns are not applicable. The .sl and .so method library sufﬁces in

these conﬁguration ﬁles, if present, are now redundant. They are ignored by the iconv_open()

func-

tion, and the right architecture speciﬁc method library extension will be appended automatically.

iconv_open() Returns a conversion descriptor that describes a conversion from the codeset

speciﬁed by the string pointed to by the fromcode argument to the codeset speciﬁed

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 at least one

of the iconv conﬁguration ﬁles.

The iconv_open() function searches the codeset names ﬁrst 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

speciﬁed by inbuf , into a sequence of corresponding characters in another codeset,

contained in the array speciﬁed by outbuf . The codesets are those speciﬁed in the

iconv_open() call that returned the conversion descriptor cd. The inbuf argu-

ment points to a variable that points to the ﬁrst 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 ﬁrst available byte in

the output buffer, and outbytesleft indicates the number of the available remaining

bytes in the buffer.

HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1

Summary of content (6 pages)

PAGE 1
iconv(3C) iconv(3C) NAME iconv(), iconv_open(), iconv_close() - codeset conversion routines SYNOPSIS #include iconv_t iconv_open(const char *tocode , const char *fromcode ); size_t iconv( iconv_t const char size_t char size_t ); cd , **inbuf , *inbytesleft , **outbuf , *outbytesleft int iconv_close(iconv_t cd ); DESCRIPTION The iconv_open() routine uses the following iconv configuration files in descending order of precedence: • /usr/lib/nls/iconv/system.config.
PAGE 2
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 section), conversion stops after the previous successfully converted character.
PAGE 3
iconv(3C) iconv(3C) iconv() fails if any of the following conditions are encountered: [EILSEQ] Input conversion stopped due to an input character that does not belong to the input codeset, or if the conversion table does not contain an entry corresponding to this input character and a galley character was not defined for that particular table. [E2BIG] Input conversion stopped due to lack of space in the output buffer.
PAGE 4
iconv(3C) iconv(3C) (size_t)BUFSIZ-inbytesleft)) < 0) { perror("prog"); return BAD; } if (!(inbytesleft += bytesread)) { break; /* end of conversions */ } ret_val = iconv(cd, &inchar, &inbytesleft, &outchar, &outbytesleft); if (write(1, outbuf, (size_t)BUFSIZ-outbytesleft) < 0) { perror("prog"); return BAD; } A /* iconv() returns the number of non-identical conversions * performed. If the entire string in the input buffer is * converted, the value pointed to by inbytesleft will be * zero.
PAGE 5
iconv(3C) iconv(3C) export CCOPTS="-Wl,-a,archive options -Wl,-E -l:libdld.sl" export LDOPTS="options -E +n -l:libdld.sl" cc -o outfile source The option -Wl,-a,archive is positionally dependent and should occur at the beginning of the compile line. For optimum compatibility in future releases, you should avoid using archive libc with other shared libraries except for libdld.sl as needed above. There is a corner-case situation for multi-byte characters that is not correctly handled by iconv().
PAGE 6
(Notes) A (Notes) iA 6 Hewlett-Packard Company −1− HP-UX 11i Version 3: September 2010