1            GNU LIBICONV - character set conversion library
2
3This library provides an iconv() implementation, for use on systems which
4don't have one, or whose implementation cannot convert from/to Unicode.
5
6It provides support for the encodings:
7
8    European languages
9        ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16},
10        KOI8-R, KOI8-U, KOI8-RU,
11        CP{1250,1251,1252,1253,1254,1257}, CP{850,866},
12        Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
13        Mac{Cyrillic,Ukraine,Greek,Turkish},
14        Macintosh
15    Semitic languages
16        ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}
17    Japanese
18        EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1
19    Chinese
20        EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS,
21        BIG5-HKSCS:2001, BIG5-HKSCS:1999, ISO-2022-CN, ISO-2022-CN-EXT
22    Korean
23        EUC-KR, CP949, ISO-2022-KR, JOHAB
24    Armenian
25        ARMSCII-8
26    Georgian
27        Georgian-Academy, Georgian-PS
28    Tajik
29        KOI8-T
30    Kazakh
31        PT154, RK1048
32    Thai
33        ISO-8859-11, TIS-620, CP874, MacThai
34    Laotian
35        MuleLao-1, CP1133
36    Vietnamese
37        VISCII, TCVN, CP1258
38    Platform specifics
39        HP-ROMAN8, NEXTSTEP
40    Full Unicode
41        UTF-8
42        UCS-2, UCS-2BE, UCS-2LE
43        UCS-4, UCS-4BE, UCS-4LE
44        UTF-16, UTF-16BE, UTF-16LE
45        UTF-32, UTF-32BE, UTF-32LE
46        UTF-7
47        C99, JAVA
48    Full Unicode, in terms of `uint16_t' or `uint32_t'
49        (with machine dependent endianness and alignment)
50        UCS-2-INTERNAL, UCS-4-INTERNAL
51    Locale dependent, in terms of `char' or `wchar_t'
52        (with machine dependent endianness and alignment, and with OS and
53        locale dependent semantics)
54        char, wchar_t
55        The empty encoding name "" is equivalent to "char": it denotes the
56        locale dependent character encoding.
57
58When configured with the option --enable-extra-encodings, it also provides
59support for a few extra encodings:
60
61    European languages
62        CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
63    Semitic languages
64        CP864
65    Japanese
66        EUC-JISX0213, Shift_JISX0213, ISO-2022-JP-3
67    Chinese
68        BIG5-2003 (experimental)
69    Turkmen
70        TDS565
71    Platform specifics
72        ATARIST, RISCOS-LATIN1
73
74It can convert from any of these encodings to any other, through Unicode
75conversion.
76
77It has also some limited support for transliteration, i.e. when a character
78cannot be represented in the target character set, it can be approximated
79through one or several similarly looking characters. Transliteration is
80activated when "//TRANSLIT" is appended to the target encoding name.
81
82libiconv is for you if your application needs to support multiple character
83encodings, but that support lacks from your system.
84
85
86Installation
87------------
88
89As usual for GNU packages:
90
91    $ ./configure --prefix=/usr/local
92    $ make
93    $ make install
94
95After installing GNU libiconv for the first time, it is recommended to
96recompile and reinstall GNU gettext, so that it can take advantage of
97libiconv.
98
99On systems other than GNU/Linux, the iconv program will be internationalized
100only if GNU gettext has been built and installed before GNU libiconv. This
101means that the first time GNU libiconv is installed, we have a circular
102dependency between the GNU libiconv and GNU gettext packages, which can be
103resolved by building and installing either
104  - first libiconv, then gettext, then libiconv again,
105or (on systems supporting shared libraries, excluding AIX)
106  - first gettext, then libiconv, then gettext again.
107Recall that before building a package for the second time, you need to erase
108the traces of the first build by running "make distclean".
109
110This library can be built and installed in two variants:
111
112  - The library mode. This works on all systems, and uses a library
113    `libiconv.so' and a header file `<iconv.h>'. (Both are installed
114    through "make install".)
115
116    To use it, simply #include <iconv.h> and use the functions.
117
118    To use it in an autoconfiguring package:
119    - If you don't use automake, append m4/iconv.m4 to your aclocal.m4
120      file.
121    - If you do use automake, add m4/iconv.m4 to your m4 macro repository.
122    - Add to the link command line of libraries and executables that use
123      the functions the placeholder @LIBICONV@ (or, if using libtool for
124      the link, @LTLIBICONV@). If you use automake, the right place for
125      these additions are the *_LDADD variables.
126    Note that 'iconv.m4' is also part of the GNU gettext package, which
127    installs it in /usr/local/share/aclocal/iconv.m4.
128
129  - The libc plug/override mode. This works on GNU/Linux, Solaris and OSF/1
130    systems only. It is a way to get good iconv support without having
131    glibc-2.1.
132    It installs a library `preloadable_libiconv.so'. This library can be used
133    with LD_PRELOAD, to override the iconv* functions present in the C library.
134
135    On GNU/Linux and Solaris:
136        $ export LD_PRELOAD=/usr/local/lib/preloadable_libiconv.so
137
138    On OSF/1:
139        $ export _RLD_LIST=/usr/local/lib/preloadable_libiconv.so:DEFAULT
140
141    A program's source need not be modified, the program need not even be
142    recompiled. Just set the LD_PRELOAD environment variable, that's it!
143
144
145Copyright
146---------
147
148The libiconv and libcharset _libraries_ and their header files are under LGPL,
149see file COPYING.LIB.
150
151The iconv _program_ and the documentation are under GPL, see file COPYING.
152
153
154Download
155--------
156
157    ftp://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.12.tar.gz
158
159Homepage
160--------
161
162    http://www.gnu.org/software/libiconv/
163
164Bug reports to
165--------------
166
167    <bug-gnu-libiconv@gnu.org>
168
169
170Bruno Haible <bruno@clisp.org>
171