---
name: "iconv_open"
section: "3"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/iconv_open"
---

# iconv\_open(3)

allocate descriptor for character set conversion

## NAME

iconv\_open - allocate descriptor for character set conversion

## LIBRARY

Standard C library (*libc*, *-lc*)

## 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 GNU C library, the permitted values are listed by the *iconv --list* command, and all combinations of the listed values are supported. Furthermore the GNU C library and the GNU libiconv library support the following two suffixes:

- //TRANSLIT

  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 similarly looking characters.

- //IGNORE

  When the string "//IGNORE" 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**(3)](/iconv/3.md) any number of times. It remains valid until deallocated using [**iconv\_close**(3)](/iconv_close/3.md).

A conversion descriptor contains a conversion state. After creation using **iconv\_open**(), the state is in the initial state. Using [**iconv**(3)](/iconv/3.md) modifies the descriptor's conversion state. To bring the state back to the initial state, use [**iconv**(3)](/iconv/3.md) with NULL as *inbuf* argument.

## RETURN VALUE

On success, **iconv\_open**() returns a freshly allocated conversion descriptor. On failure, it returns *(iconv\_t) -1* and sets *errno* to indicate the error.

## ERRORS

The following error can occur, among others:

- **EINVAL**

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

## ATTRIBUTES

For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md).

| | | |
| --- | --- | --- |
| **Interface** | **Attribute** | **Value** |
| **iconv\_open**() | Thread safety | MT-Safe locale |

## STANDARDS

POSIX.1-2008.

## HISTORY

glibc 2.1. POSIX.1-2001, SUSv2.

## SEE ALSO

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