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