@node Iconv
@chapter Character-set conversions (@file{iconv.h})

This chapter describes the Newlib iconv library.
The iconv functions declarations are in
@file{iconv.h}.

@menu
* iconv::                 Character set conversion routines
* iconv configuration::   Newlib iconv-specific configure options
@end menu

@page
@include iconv/iconv.def

@page
@node iconv configuration
@section iconv configuration
@findex iconv configuration
@findex encoding
@*
To enable iconv, the --enable-newlib-iconv configuration option should be
used when configuring Newlib. 

@*
Iconv library is intended to perform conversions from one encoding to
another encoding. Thus, the only user-visible abstraction is encoding.
To enable particular encoding support user should enable it using
Newlib's configure script options. Encoding's support is divided into
two parts: "to" and "from". For example, if it is only wanted to have
UTF-8 -> UCS-4 coding capabilities, "from" UTF-8 and "to" UCS-4 support
should be enabled. In this case backward (UCS-4 -> UTF-8) conversion 
won't be possible (iconv_open will return error). Such division on "to"
and "from" parts helps to save memory.

@*
To enable encoding support --enable-newlib-iconv-encodings configure
script option should be used. This option accepts a comma-separated list
of encodins that should be enabled. Option enables each encoding in both
("to" and "from") directions.

@*
--enable-newlib-iconv-from-encodings configure script option enables
"from" support for each encoding that was passed to it.

@*
--enable-newlib-iconv-to-encodings configure script option enables
"to" support for each encoding that was passed to it.

@*
Example: if user plans only KOI8-R -> UTF-8, UTF-8 -> ISO-8859-5 and
KOI8-R -> UCS-2 conversions, the most optimal way (minimal iconv's
code and data will be linked) is to configure Newlib with 
--enable-newlib-iconv-encodings=UTF-8
--enable-newlib-iconv-from-encodings=KOI8-R
--enable-newlib-iconv-to-encodings=KOI8-R,ISO-8859-5

@*
There is one more configue script option for iconv library:
--enable-newlib-iconv-external-ccs. This options enables iconv's
capabilities to work with external CCS files. Exteral CCS files are just
conversion tables used by iconv. Without this option all conversion
tables are linked-in and occupy a lot of ROM. If target system has
some fyle-system, it can benefit using external CCS files which are
loaded on iconv_open and unloaded on iconv_close. But this way require
more RAM. Moreover, in current implementation, distinct copy of CCS file
is loaded for each fore each opended iconv decriptor for the same
encoding. This means that if, for example, two iconv descriptors for
KOI8-R -> UCS-4BE and KOI8-R -> UTF-16BE are opened, two copies of
koi8-r.cct file will be loaded. 

@*
Note: not evry encoding needs CCS tiles. For example, UTF-8, UTF-16,
UCS-2, UCS-4 doesn't use such files at all.

@*
Note: CCS file contains a number of tables, and only several needed tables
are loaded from this file. This means, that there is a possibility to save
some "fyle-system space" not including unneeded tables to that CCS
files. Such task may be performed using "mktbl.pl" Perl script
destributed with iconv library.

@*
Note: CCS files are searched by iconv_open in $NLSPATH/iconv_data/ directory.