---
name: "libiconv_iconv_open"
section: "3"
platform: "linux"
package: "libiconv"
version: "1.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libiconv_iconv_open"
---

# libiconv\_iconv\_open(3)

allocate descriptor for character set conversion

## NAME

iconv\_open - allocate descriptor for character set conversion

## SYNOPSIS

```
#include <iconv.h>

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

## 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

  ```

  ```

  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

  ```

  ```

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

- Japanese

  ```

  ```

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

- 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

  ```

  ```

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

- Armenian

  ```

  ```

  ARMSCII-8

- Georgian

  ```

  ```

  Georgian-Academy, Georgian-PS

- Tajik

  ```

  ```

  KOI8-T

- Kazakh

  ```

  ```

  PT154, RK1048

- Thai

  ```

  ```

  TIS-620, CP874, MacThai

- Laotian

  ```

  ```

  MuleLao-1, CP1133

- Vietnamese

  ```

  ```

  VISCII, TCVN, CP1258

- Platform specifics

  ```

  ```

  HP-ROMAN8, NEXTSTEP

- Full Unicode

  ```

  ```

  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**

  (with machine dependent endianness and alignment)

  ```

  ```

  UCS-2-INTERNAL, UCS-4-INTERNAL

- Locale dependent, in terms of **char** or **wchar\_t**

  (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

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

- Semitic languages

  ```

  ```

  CP864

- Japanese

  ```

  ```

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

- Chinese

  ```

  ```

  BIG5-2003 (experimental)

- Turkmen

  ```

  ```

  TDS565

- Platform specifics

  ```

  ```

  ATARIST, RISCOS-LATIN1

- EBCDIC compatible (not ASCII compatible, very rarely used)

  ```

  ```

  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

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

## ERRORS

The following error can occur, among others:

- **EINVAL**

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

## CONFORMING TO

POSIX:2024

## SEE ALSO

[**iconv**(3)](/iconv/3.md) [**iconvctl**(3)](/iconvctl/3.md) [**iconv\_close**(3)](/iconv_close/3.md)