man/iconv_open.3

   1 .\" Copyright (c) Free Software Foundation, Inc.
   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 3 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 20, 2023" "GNU"
  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,1131},
  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 ISO-2022\-JP\-MS
  50 .TP
  51 Chinese
  52 .nf
  53 .fi
  54 EUC\-CN, HZ, GBK, CP936, GB18030, GB18030:2022, EUC\-TW, BIG5, CP950,
  55 BIG5\-HKSCS, BIG5\-HKSCS:2004, BIG5\-HKSCS:2001, BIG5\-HKSCS:1999,
  56 ISO\-2022\-CN, ISO\-2022\-CN\-EXT
  57 .TP
  58 Korean
  59 .nf
  60 .fi
  61 EUC\-KR, CP949, ISO\-2022\-KR, JOHAB
  62 .TP
  63 Armenian
  64 .nf
  65 .fi
  66 ARMSCII\-8
  67 .TP
  68 Georgian
  69 .nf
  70 .fi
  71 Georgian\-Academy, Georgian\-PS
  72 .TP
  73 Tajik
  74 .nf
  75 .fi
  76 KOI8\-T
  77 .TP
  78 Kazakh
  79 .nf
  80 .fi
  81 PT154, RK1048
  82 .TP
  83 Thai
  84 .nf
  85 .fi
  86 TIS\-620, CP874, MacThai
  87 .TP
  88 Laotian
  89 .nf
  90 .fi
  91 MuleLao\-1, CP1133
  92 .TP
  93 Vietnamese
  94 .nf
  95 .fi
  96 VISCII, TCVN, CP1258
  97 .TP
  98 Platform specifics
  99 .nf
 100 .fi
 101 HP\-ROMAN8, NEXTSTEP
 102 .TP
 103 Full Unicode
 104 .nf
 105 .fi
 106 UTF\-8
 107 .nf
 108 .fi
 109 UCS\-2, UCS\-2BE, UCS\-2LE
 110 .nf
 111 .fi
 112 UCS\-4, UCS\-4BE, UCS\-4LE
 113 .nf
 114 .fi
 115 UTF\-16, UTF\-16BE, UTF\-16LE
 116 .nf
 117 .fi
 118 UTF\-32, UTF\-32BE, UTF\-32LE
 119 .nf
 120 .fi
 121 UTF\-7
 122 .nf
 123 .fi
 124 C99, JAVA
 125 .TP
 126 Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP
 127 (with machine dependent endianness and alignment)
 128 .nf
 129 .fi
 130 UCS\-2\-INTERNAL, UCS\-4\-INTERNAL
 131 .TP
 132 Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP
 133 (with machine dependent endianness and alignment, and with semantics
 134 depending on the OS and the current LC_CTYPE locale facet)
 135 .nf
 136 .fi
 137 char, wchar_t
 138 .PP
 139 When configured with the option \fB\-\-enable\-extra\-encodings\fP, it also
 140 provides support for a few extra encodings:
 141 .TP
 142 European languages
 143 .nf
 144 CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
 145 .fi
 146 .TP
 147 Semitic languages
 148 .nf
 149 .fi
 150 CP864
 151 .TP
 152 Japanese
 153 .nf
 154 .fi
 155 EUC\-JISX0213, Shift_JISX0213, ISO\-2022\-JP\-3
 156 .TP
 157 Chinese
 158 .nf
 159 .fi
 160 BIG5\-2003 (experimental)
 161 .TP
 162 Turkmen
 163 .nf
 164 .fi
 165 TDS565
 166 .TP
 167 Platform specifics
 168 .nf
 169 .fi
 170 ATARIST, RISCOS\-LATIN1
 171 .PP
 172 .TP
 173 EBCDIC compatible (not ASCII compatible, very rarely used)
 174 .nf
 175 .fi
 176 European languages:
 177 .nf
 178 .fi
 179     IBM-{037,273,277,278,280,282,284,285,297,423,500,870,871,875,880},
 180     IBM-{905,924,1025,1026,1047,1112,1122,1123,1140,1141,1142,1143},
 181     IBM-{1144,1145,1146,1147,1148,1149,1153,1154,1155,1156,1157,1158},
 182     IBM-{1165,1166,4971}
 183 .nf
 184 .fi
 185 Semitic languages:
 186 .nf
 187 .fi
 188     IBM-{424,425,12712,16804}
 189 .nf
 190 .fi
 191 Persian:
 192 .nf
 193 .fi
 194     IBM-1097
 195 .nf
 196 .fi
 197 Thai:
 198 .nf
 199 .fi
 200     IBM-{838,1160}
 201 .nf
 202 .fi
 203 Laotian:
 204 .nf
 205 .fi
 206     IBM-1132
 207 .nf
 208 .fi
 209 Vietnamese:
 210 .nf
 211 .fi
 212     IBM-{1130,1164}
 213 .nf
 214 .fi
 215 Indic languages:
 216 .nf
 217 .fi
 218     IBM-1137
 219 .PP
 220 The empty encoding name "" is equivalent to "char": it denotes the
 221 locale dependent character encoding.
 222 .PP
 223 When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
 224 is activated. This means that when a character cannot be represented in the
 225 target character set, it can be approximated through one or several characters
 226 that look similar to the original character.
 227 .PP
 228 When the string "//IGNORE" is appended to \fItocode\fP, characters that
 229 cannot be represented in the target character set will be silently discarded.
 230 .PP
 231 The resulting conversion descriptor can be used with \fBiconv\fP any number
 232 of times. It remains valid until deallocated using \fBiconv_close\fP.
 233 .PP
 234 A conversion descriptor contains a conversion state. After creation using
 235 \fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
 236 modifies the descriptor's conversion state. (This implies that a conversion
 237 descriptor can not be used in multiple threads simultaneously.) To bring the
 238 state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
 239 argument.
 240 .SH "RETURN VALUE"
 241 The \fBiconv_open\fP function returns a freshly allocated conversion
 242 descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(\-1).
 243 .SH ERRORS
 244 The following error can occur, among others:
 245 .TP
 246 .B EINVAL
 247 The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
 248 implementation.
 249 .SH "CONFORMING TO"
 250 POSIX:2001
 251 .SH "SEE ALSO"
 252 .BR iconv (3)
 253 .BR iconvctl (3)
 254 .BR iconv_close (3)