README

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