ICONV\_OPEN(3) Library Functions Manual ICONV\_OPEN(3)

# [NAME](#NAME)

iconv\_open - allocate descriptor for character set conversion

# [SYNOPSIS](#SYNOPSIS)

```
#include <iconv.h>

iconv_t iconv_open (const char* tocode, const char* fromcode);
```

# [DESCRIPTION](#DESCRIPTION)

The **iconv\_open** function allocates a conversion descriptor suitable for converting byte sequences from character encoding *fromcode* to character encoding *tocode*.

The values permitted for *fromcode* and *tocode* and the supported combinations are system dependent. For the libiconv library, the following encodings are supported, in all combinations.

[European languages](#European)

```

```

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

[Semitic languages](#Semitic)

```

```

ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}

[Japanese](#Japanese)

```

```

EUC-JP, SHIFT\_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1, ISO-2022-JP-MS

[Chinese](#Chinese)

```

```

EUC-CN, HZ, GBK, CP936, GB18030, GB18030:2022, EUC-TW, BIG5, CP950, BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999, ISO-2022-CN, ISO-2022-CN-EXT

[Korean](#Korean)

```

```

EUC-KR, CP949, ISO-2022-KR, JOHAB

[Armenian](#Armenian)

```

```

ARMSCII-8

[Georgian](#Georgian)

```

```

Georgian-Academy, Georgian-PS

[Tajik](#Tajik)

```

```

KOI8-T

[Kazakh](#Kazakh)

```

```

PT154, RK1048

[Thai](#Thai)

```

```

TIS-620, CP874, MacThai

[Laotian](#Laotian)

```

```

MuleLao-1, CP1133

[Vietnamese](#Vietnamese)

```

```

VISCII, TCVN, CP1258

[Platform specifics](#Platform)

```

```

HP-ROMAN8, NEXTSTEP

[Full Unicode](#Full)

```

```

UTF-8

```

```

UCS-2, UCS-2BE, UCS-2LE

```

```

UCS-4, UCS-4BE, UCS-4LE

```

```

UTF-16, UTF-16BE, UTF-16LE

```

```

UTF-32, UTF-32BE, UTF-32LE

```

```

UTF-7

```

```

C99, JAVA

[Full Unicode, in terms of **uint16\_t** or **uint32\_t**](#Full~2)

(with machine dependent endianness and alignment)

```

```

UCS-2-INTERNAL, UCS-4-INTERNAL

[Locale dependent, in terms of **char** or **wchar\_t**](#Locale)

(with machine dependent endianness and alignment, and with semantics depending on the OS and the current LC\_CTYPE locale facet)

```

```

char, wchar\_t

When configured with the option **--enable-extra-encodings**, it also provides support for a few extra encodings:

[European languages](#European~2)

```
CP{437,737,775,852,853,855,857,858,860,861,863,865,869,1125}
```

[Semitic languages](#Semitic~2)

```

```

CP864

[Japanese](#Japanese~2)

```

```

EUC-JISX0213, Shift\_JISX0213, ISO-2022-JP-3

[Chinese](#Chinese~2)

```

```

BIG5-2003 (experimental)

[Turkmen](#Turkmen)

```

```

TDS565

[Platform specifics](#Platform~2)

```

```

ATARIST, RISCOS-LATIN1

[EBCDIC compatible (not ASCII compatible, very rarely used)](#EBCDIC)

```

```

European languages:

```

```

IBM-{037,273,277,278,280,282,284,285,297,423,500,870,871,875,880},  
IBM-{905,924,1025,1026,1047,1112,1122,1123,1140,1141,1142,1143},  
IBM-{1144,1145,1146,1147,1148,1149,1153,1154,1155,1156,1157,1158},  
IBM-{1165,1166,4971}

```

```

Semitic languages:

```

```

IBM-{424,425,12712,16804}

```

```

Persian:

```

```

IBM-1097

```

```

Thai:

```

```

IBM-{838,1160}

```

```

Laotian:

```

```

IBM-1132

```

```

Vietnamese:

```

```

IBM-{1130,1164}

```

```

Indic languages:

```

```

IBM-1137

The empty encoding name "" is equivalent to "char": it denotes the locale dependent character encoding.

When the string "//TRANSLIT" is appended to *tocode*, 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.

When the string "//IGNORE" is appended to *tocode*, invalid multibyte sequences in the input and characters that cannot be represented in the target character set will be silently discarded.

When the string "//NON\_IDENTICAL\_DISCARD" is appended to *tocode*, characters that cannot be represented in the target character set will be silently discarded.

The resulting conversion descriptor can be used with **iconv** any number of times. It remains valid until deallocated using **iconv\_close**.

A conversion descriptor contains a conversion state. After creation using **iconv\_open**, the state is in the initial state. Using **iconv** 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 **iconv** with NULL as *inbuf* argument.

# [RETURN VALUE](#RETURN_VALUE)

The **iconv\_open** function returns a freshly allocated conversion descriptor. In case of error, it sets **errno** and returns (iconv\_t)(-1).

# [ERRORS](#ERRORS)

The following error can occur, among others:

[**EINVAL**](#EINVAL)

The conversion from *fromcode* to *tocode* is not supported by the implementation.

# [CONFORMING TO](#CONFORMING_TO)

POSIX:2024

# [SEE ALSO](#SEE_ALSO)

[**iconv**(3)](/man/os/gnu-libiconv/iconv.3) [**iconvctl**(3)](/man/os/gnu-libiconv/iconvctl.3) [**iconv\_close**(3)](/man/os/gnu-libiconv/iconv_close.3)

December 15, 2024 GNU

---

Document: iconv_open(3) from gnu-libiconv 1.19-r7 (Chainguard OS)
Source: https://git.savannah.gnu.org/git/libiconv.git