You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
206 lines
4.6 KiB
206 lines
4.6 KiB
.\" Copyright (c) Free Software Foundation, Inc. |
|
.\" |
|
.\" This is free documentation; you can redistribute it and/or |
|
.\" modify it under the terms of the GNU General Public License as |
|
.\" published by the Free Software Foundation; either version 3 of |
|
.\" the License, or (at your option) any later version. |
|
.\" |
|
.\" References consulted: |
|
.\" GNU glibc-2 source code and manual |
|
.\" OpenGroup's Single Unix specification http://www.UNIX-systems.org/online.html |
|
.\" |
|
.TH ICONV_OPEN 3 "October 23, 2011" "GNU" "Linux Programmer's Manual" |
|
.SH NAME |
|
iconv_open \- allocate descriptor for character set conversion |
|
.SH SYNOPSIS |
|
.nf |
|
.B #include <iconv.h> |
|
.sp |
|
.BI "iconv_t iconv_open (const char* " tocode ", const char* " fromcode ); |
|
.fi |
|
.SH DESCRIPTION |
|
The \fBiconv_open\fP function allocates a conversion descriptor suitable |
|
for converting byte sequences from character encoding \fIfromcode\fP to |
|
character encoding \fItocode\fP. |
|
.PP |
|
The values permitted for \fIfromcode\fP and \fItocode\fP and the supported |
|
combinations are system dependent. For the libiconv library, the following |
|
encodings are supported, in all combinations. |
|
.TP |
|
European languages |
|
.nf |
|
.fi |
|
ASCII, ISO\-8859\-{1,2,3,4,5,7,9,10,13,14,15,16}, |
|
KOI8\-R, KOI8\-U, KOI8\-RU, |
|
CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131}, |
|
Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, |
|
Mac{Cyrillic,Ukraine,Greek,Turkish}, |
|
Macintosh |
|
.TP |
|
Semitic languages |
|
.nf |
|
.fi |
|
ISO\-8859\-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic} |
|
.TP |
|
Japanese |
|
.nf |
|
.fi |
|
EUC\-JP, SHIFT_JIS, CP932, ISO\-2022\-JP, ISO\-2022\-JP\-2, ISO\-2022\-JP\-1, |
|
ISO-2022\-JP\-MS |
|
.TP |
|
Chinese |
|
.nf |
|
.fi |
|
EUC\-CN, HZ, GBK, CP936, GB18030, EUC\-TW, BIG5, CP950, BIG5\-HKSCS, |
|
BIG5\-HKSCS:2004, BIG5\-HKSCS:2001, BIG5\-HKSCS:1999, ISO\-2022\-CN, |
|
ISO\-2022\-CN\-EXT |
|
.TP |
|
Korean |
|
.nf |
|
.fi |
|
EUC\-KR, CP949, ISO\-2022\-KR, JOHAB |
|
.TP |
|
Armenian |
|
.nf |
|
.fi |
|
ARMSCII\-8 |
|
.TP |
|
Georgian |
|
.nf |
|
.fi |
|
Georgian\-Academy, Georgian\-PS |
|
.TP |
|
Tajik |
|
.nf |
|
.fi |
|
KOI8\-T |
|
.TP |
|
Kazakh |
|
.nf |
|
.fi |
|
PT154, RK1048 |
|
.TP |
|
Thai |
|
.nf |
|
.fi |
|
TIS\-620, CP874, MacThai |
|
.TP |
|
Laotian |
|
.nf |
|
.fi |
|
MuleLao\-1, CP1133 |
|
.TP |
|
Vietnamese |
|
.nf |
|
.fi |
|
VISCII, TCVN, CP1258 |
|
.TP |
|
Platform specifics |
|
.nf |
|
.fi |
|
HP\-ROMAN8, NEXTSTEP |
|
.TP |
|
Full Unicode |
|
.nf |
|
.fi |
|
UTF\-8 |
|
.nf |
|
.fi |
|
UCS\-2, UCS\-2BE, UCS\-2LE |
|
.nf |
|
.fi |
|
UCS\-4, UCS\-4BE, UCS\-4LE |
|
.nf |
|
.fi |
|
UTF\-16, UTF\-16BE, UTF\-16LE |
|
.nf |
|
.fi |
|
UTF\-32, UTF\-32BE, UTF\-32LE |
|
.nf |
|
.fi |
|
UTF\-7 |
|
.nf |
|
.fi |
|
C99, JAVA |
|
.TP |
|
Full Unicode, in terms of \fBuint16_t\fP or \fBuint32_t\fP |
|
(with machine dependent endianness and alignment) |
|
.nf |
|
.fi |
|
UCS\-2\-INTERNAL, UCS\-4\-INTERNAL |
|
.TP |
|
Locale dependent, in terms of \fBchar\fP or \fBwchar_t\fP |
|
(with machine dependent endianness and alignment, and with semantics |
|
depending on the OS and the current LC_CTYPE locale facet) |
|
.nf |
|
.fi |
|
char, wchar_t |
|
.PP |
|
When configured with the option \fB\-\-enable\-extra\-encodings\fP, it also |
|
provides support for a few extra encodings: |
|
.TP |
|
European languages |
|
.nf |
|
CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125} |
|
.fi |
|
.TP |
|
Semitic languages |
|
.nf |
|
.fi |
|
CP864 |
|
.TP |
|
Japanese |
|
.nf |
|
.fi |
|
EUC\-JISX0213, Shift_JISX0213, ISO\-2022\-JP\-3 |
|
.TP |
|
Chinese |
|
.nf |
|
.fi |
|
BIG5\-2003 (experimental) |
|
.TP |
|
Turkmen |
|
.nf |
|
.fi |
|
TDS565 |
|
.TP |
|
Platform specifics |
|
.nf |
|
.fi |
|
ATARIST, RISCOS\-LATIN1 |
|
.PP |
|
The empty encoding name "" is equivalent to "char": it denotes the |
|
locale dependent character encoding. |
|
.PP |
|
When the string "//TRANSLIT" is appended to \fItocode\fP, transliteration |
|
is activated. This means that when a character cannot be represented in the |
|
target character set, it can be approximated through one or several characters |
|
that look similar to the original character. |
|
.PP |
|
When the string "//IGNORE" is appended to \fItocode\fP, characters that |
|
cannot be represented in the target character set will be silently discarded. |
|
.PP |
|
The resulting conversion descriptor can be used with \fBiconv\fP any number |
|
of times. It remains valid until deallocated using \fBiconv_close\fP. |
|
.PP |
|
A conversion descriptor contains a conversion state. After creation using |
|
\fBiconv_open\fP, the state is in the initial state. Using \fBiconv\fP |
|
modifies the descriptor's conversion state. (This implies that a conversion |
|
descriptor can not be used in multiple threads simultaneously.) To bring the |
|
state back to the initial state, use \fBiconv\fP with NULL as \fIinbuf\fP |
|
argument. |
|
.SH "RETURN VALUE" |
|
The \fBiconv_open\fP function returns a freshly allocated conversion |
|
descriptor. In case of error, it sets \fBerrno\fP and returns (iconv_t)(\-1). |
|
.SH ERRORS |
|
The following error can occur, among others: |
|
.TP |
|
.B EINVAL |
|
The conversion from \fIfromcode\fP to \fItocode\fP is not supported by the |
|
implementation. |
|
.SH "CONFORMING TO" |
|
POSIX:2001 |
|
.SH "SEE ALSO" |
|
.BR iconv (3) |
|
.BR iconvctl (3) |
|
.BR iconv_close (3)
|
|
|