man/iconv_open.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.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  "December 6, 2001" "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 ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16},
  32 KOI8-R, KOI8-U, KOI8-RU,
  33 CP{1250,1251,1252,1253,1254,1257}, CP{850,866},
  34 Mac{Roman,CentralEurope,Iceland,Croatian,Romania},
  35 Mac{Cyrillic,Ukraine,Greek,Turkish},
  36 Macintosh
  37 .TP
  38 Semitic languages
  39 ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}
  40 .TP
  41 Japanese
  42 EUC-JP, SHIFT-JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1
  43 .TP
  44 Chinese
  45 EUC-CN, HZ, GBK, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS,
  46 ISO-2022-CN, ISO-2022-CN-EXT
  47 .TP
  48 Korean
  49 EUC-KR, CP949, ISO-2022-KR, JOHAB
  50 .TP
  51 Armenian
  52 ARMSCII-8
  53 .TP
  54 Georgian
  55 Georgian-Academy, Georgian-PS
  56 .TP
  57 Thai
  58 TIS-620, CP874, MacThai
  59 .TP
  60 Laotian
  61 MuleLao-1, CP1133
  62 .TP
  63 Vietnamese
  64 VISCII, TCVN, CP1258
  65 .TP
  66 Platform specifics
  67 HP-ROMAN8, NEXTSTEP
  68 .TP
  69 Full Unicode
  70 .nf
  71 UTF-8
  72 UCS-2, UCS-2BE, UCS-2LE
  73 UCS-4, UCS-4BE, UCS-4LE
  74 UTF-16, UTF-16BE, UTF-16LE
  75 UTF-32, UTF-32BE, UTF-32LE
  76 UTF-7
  77 JAVA
  78 .fi
  79 .TP
  80 Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP
  81 (with machine dependent endianness and alignment)
  82 .nf
  83 UCS-2-INTERNAL, UCS-4-INTERNAL
  84 .fi
  85 .TP
  86 Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP
  87 (with machine dependent endianness and alignment, and with semantics
  88 depending on the OS and the current LC_CTYPE locale facet)
  89 .nf
  90 char, wchar_t
  91 .fi
  92 The empty encoding name "" is equivalent to "char": it denotes the
  93 locale dependent character encoding.
  94 .PP
  95 When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
  96 is activated. This means that when a character cannot be represented in the
  97 target character set, it can be approximated through one or several
  98 similarly looking characters.
  99 .PP
 100 The resulting conversion descriptor can be used with \fBiconv\fP any number
 101 of times. It remains valid until deallocated using \fBiconv_close\fP.
 102 .PP
 103 A conversion descriptor contains a conversion state. After creation using
 104 \fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
 105 modifies the descriptor's conversion state. (This implies that a conversion
 106 descriptor can not be used in multiple threads simultaneously.) To bring the
 107 state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
 108 argument.
 109 .SH "RETURN VALUE"
 110 The \fBiconv_open\fP function returns a freshly allocated conversion
 111 descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(-1).
 112 .SH ERRORS
 113 The following error can occur, among others:
 114 .TP
 115 .B EINVAL
 116 The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
 117 implementation.
 118 .SH "CONFORMING TO"
 119 UNIX98
 120 .SH "SEE ALSO"
 121 .BR iconv "(3), " iconv_close (3)