iconv_open - allocate descriptor for character set conversion
iconv_t iconv_open(const char *tocode, const char *fromcode);
() function allocates a conversion descriptor suitable for
converting byte sequences from character encoding fromcode
The values permitted for fromcode
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:
- 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.
- 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)
of times. It remains valid until deallocated using iconv_close(3)
A conversion descriptor contains a conversion state. After creation using
(), the state is in the initial state. Using iconv(3)
modifies the descriptor's conversion state. To bring the state back to the
initial state, use iconv(3)
with NULL as inbuf
() function returns a freshly allocated conversion
descriptor. In case of error, it sets errno
The following error can occur, among others:
- The conversion from fromcode to tocode is not
supported by the implementation.
This function is available in glibc since version 2.1.
For an explanation of the terms used in this section, see attributes(7)
POSIX.1-2001, POSIX.1-2008, SUSv2.
This page is part of release 4.16 of the Linux man-pages
description of the project, information about reporting bugs, and the latest
version of this page, can be found at