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  "May 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 UCS-2-INTERNAL, UCS-4-INTERNAL
  83 .TP
  84 Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP
  85 (with machine dependent endianness and alignment, and with semantics
  86 depending on the OS and the current LC_CTYPE locale facet)
  87 char, wchar_t
  88 .PP
  89 When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration
  90 is activated. This means that when a character cannot be represented in the
  91 target character set, it can be approximated through one or several
  92 similarly looking characters.
  93 .PP
  94 The resulting conversion descriptor can be used with \fBiconv\fP any number
  95 of times. It remains valid until deallocated using \fBiconv_close\fP.
  96 .PP
  97 A conversion descriptor contains a conversion state. After creation using
  98 \fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP
  99 modifies the descriptor's conversion state. (This implies that a conversion
 100 descriptor can not be used in multiple threads simultaneously.) To bring the
 101 state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP
 102 argument.
 103 .SH "RETURN VALUE"
 104 The \fBiconv_open\fP function returns a freshly allocated conversion
 105 descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(-1).
 106 .SH ERRORS
 107 The following error can occur, among others:
 108 .TP
 109 .B EINVAL
 110 The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the
 111 implementation.
 112 .SH "CONFORMING TO"
 113 UNIX98
 114 .SH "SEE ALSO"
 115 .BR iconv "(3), " iconv_close (3)