src/libs/iconv/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},
  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
  58 When configured with the option --enable-extra-encodings, it also provides
  59 support 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
  74 It can convert from any of these encodings to any other, through Unicode
  75 conversion.
  76
  77 It has also some limited support for transliteration, i.e. when a character
  78 cannot be represented in the target character set, it can be approximated
  79 through one or several similarly looking characters. Transliteration is
  80 activated when "//TRANSLIT" is appended to the target encoding name.
  81
  82 libiconv is for you if your application needs to support multiple character
  83 encodings, but that support lacks from your system.
  84
  85
  86 Installation
  87 ------------
  88
  89 As usual for GNU packages:
  90
  91     $ ./configure --prefix=/usr/local
  92     $ make
  93     $ make install
  94
  95 After installing GNU libiconv for the first time, it is recommended to
  96 recompile and reinstall GNU gettext, so that it can take advantage of
  97 libiconv.
  98
  99 On systems other than GNU/Linux, the iconv program will be internationalized
 100 only if GNU gettext has been built and installed before GNU libiconv. This
 101 means that the first time GNU libiconv is installed, we have a circular
 102 dependency between the GNU libiconv and GNU gettext packages, which can be
 103 resolved by building and installing either
 104   - first libiconv, then gettext, then libiconv again,
 105 or (on systems supporting shared libraries, excluding AIX)
 106   - first gettext, then libiconv, then gettext again.
 107 Recall that before building a package for the second time, you need to erase
 108 the traces of the first build by running "make distclean".
 109
 110 This 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
 145 Copyright
 146 ---------
 147
 148 The libiconv and libcharset _libraries_ and their header files are under LGPL,
 149 see file COPYING.LIB.
 150
 151 The iconv _program_ and the documentation are under GPL, see file COPYING.
 152
 153
 154 Download
 155 --------
 156
 157     ftp://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.12.tar.gz
 158
 159 Homepage
 160 --------
 161
 162     http://www.gnu.org/software/libiconv/
 163
 164 Bug reports to
 165 --------------
 166
 167     <bug-gnu-libiconv@gnu.org>
 168
 169
 170 Bruno Haible <bruno@clisp.org>