libiconv/man/iconv_open.3

   1 .\" Copyright (c) Bruno Haible <bruno@clisp.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html
  11 .\"
  12 .TH ICONV_OPEN 3  "May 26, 2002" "GNU" "Linux Programmer's Manual"
  13 .SH NAME
  14 iconv_open \- allocate descriptor for character set conversion
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <iconv.h>
  18 .sp
  19 .BI "iconv_t iconv_open (const char* " tocode ", const char* " fromcode );
  20 .fi
  21 .SH DESCRIPTION
  22 The \fBiconv_open\fP function allocates a conversion descriptor suitable
  23 for converting byte sequences from character encoding \fIfromcode\fP to
  24 character encoding \fItocode\fP.
  25 .PP
  26 The values permitted for \fIfromcode\fP and \fItocode\fP and the supported
  27 combinations are system dependent. For the libiconv library, the following
  28 encodings are supported, in all combinations.
  29 .TP
  30 European languages
  31 .nf
  32 .fi
  33 ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16},
  34 KOI8-R, KOI8-U, KOI8-RU,
  35 CP{1250,1251,1252,1253,1254,1257}, CP{850,866},
  36 Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
  37 Mac{Cyrillic,Ukraine,Greek,Turkish},
  38 Macintosh
  39 .TP
  40 Semitic languages
  41 .nf
  42 .fi
  43 ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}
  44 .TP
  45 Japanese
  46 .nf
  47 .fi
  48 EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1
  49 .TP
  50 Chinese
  51 .nf
  52 .fi
  53 EUC-CN, HZ, GBK, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS,
  54 ISO-2022-CN, ISO-2022-CN-EXT
  55 .TP
  56 Korean
  57 .nf
  58 .fi
  59 EUC-KR, CP949, ISO-2022-KR, JOHAB
  60 .TP
  61 Armenian
  62 .nf
  63 .fi
  64 ARMSCII-8
  65 .TP
  66 Georgian
  67 .nf
  68 .fi
  69 Georgian-Academy, Georgian-PS
  70 .TP
  71 Tajik
  72 .nf
  73 .fi
  74 KOI8-T
  75 .TP
  76 Thai
  77 .nf
  78 .fi
  79 TIS-620, CP874, MacThai
  80 .TP
  81 Laotian
  82 .nf
  83 .fi
  84 MuleLao-1, CP1133
  85 .TP
  86 Vietnamese
  87 .nf
  88 .fi
  89 VISCII, TCVN, CP1258
  90 .TP
  91 Platform specifics
  92 .nf
  93 .fi
  94 HP-ROMAN8, NEXTSTEP
  95 .TP
  96 Full Unicode
  97 .nf
  98 .fi
  99 UTF-8
 100 .nf
 101 .fi
 102 UCS-2, UCS-2BE, UCS-2LE
 103 .nf
 104 .fi
 105 UCS-4, UCS-4BE, UCS-4LE
 106 .nf
 107 .fi
 108 UTF-16, UTF-16BE, UTF-16LE
 109 .nf
 110 .fi
 111 UTF-32, UTF-32BE, UTF-32LE
 112 .nf
 113 .fi
 114 UTF-7
 115 .nf
 116 .fi
 117 C99, JAVA
 118 .TP
 119 Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP
 120 (with machine dependent endianness and alignment)
 121 .nf
 122 .fi
 123 UCS-2-INTERNAL, UCS-4-INTERNAL
 124 .TP
 125 Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP
 126 (with machine dependent endianness and alignment, and with semantics
 127 depending on the OS and the current LC_CTYPE locale facet)
 128 .nf
 129 .fi
 130 char, wchar_t
 131 .PP
 132 When configured with the option \fB\-\-enable-extra-encodings\fP, it also
 133 provides support for a few extra encodings:
 134 .TP
 135 European languages
 136 .nf
 137 CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
 138 .fi
 139 .TP
 140 Semitic languages
 141 .nf
 142 .fi
 143 CP864
 144 .TP
 145 Japanese
 146 .nf
 147 .fi
 148 EUC-JISX0213, Shift_JISX0213, ISO-2022-JP-3
 149 .TP
 150 Turkmen
 151 .nf
 152 .fi
 153 TDS565
 154 .TP
 155 Platform specifics
 156 .nf
 157 .fi
 158 RISCOS-LATIN1
 159 .PP
 160 The empty encoding name "" is equivalent to "char": it denotes the
 161 locale dependent character encoding.
 162 .PP
 163 When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
 164 is activated. This means that when a character cannot be represented in the
 165 target character set, it can be approximated through one or several
 166 similarly looking characters.
 167 .PP
 168 When the string "//IGNORE" is appended to \fItocode\fP, characters that
 169 cannot be represented in the target character set will be silently discarded.
 170 .PP
 171 The resulting conversion descriptor can be used with \fBiconv\fP any number
 172 of times. It remains valid until deallocated using \fBiconv_close\fP.
 173 .PP
 174 A conversion descriptor contains a conversion state. After creation using
 175 \fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
 176 modifies the descriptor's conversion state. (This implies that a conversion
 177 descriptor can not be used in multiple threads simultaneously.) To bring the
 178 state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
 179 argument.
 180 .SH "RETURN VALUE"
 181 The \fBiconv_open\fP function returns a freshly allocated conversion
 182 descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(-1).
 183 .SH ERRORS
 184 The following error can occur, among others:
 185 .TP
 186 .B EINVAL
 187 The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
 188 implementation.
 189 .SH "CONFORMING TO"
 190 UNIX98
 191 .SH "SEE ALSO"
 192 .BR iconv "(3), " iconv_close (3)