iconv_open(3)

✨ iconv_open(3) — the Library Functions Manual glow-up ✨

okay bestie, we're in <iconv.h> land and this is the Library Functions Manual page for iconv_open, so buckle up 🎀

---

💖 NAME 💖

iconv_open — allocate descriptor for character set conversion

like. it literally just sets you up so you can convert text from one character encoding to another. she's the plug. 👑

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

🌸 SYNOPSIS 🌸

#include <iconv.h>

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

---

🦋 DESCRIPTION 🦋

So what iconv_open() does is she allocates a conversion descriptor — a little handle — that's suitable for converting byte sequences from the character encoding fromcode to the character encoding tocode. no cap, that's the whole job 💅

The values that are allowed for fromcode and tocode, and which combinations of them actually work, are system-dependent. Like, nobody's promising you the same menu everywhere. For the GNU C library though, the permitted values are listed by the iconv --list command, and ngl, all combinations of the listed values are supported. every single one. slay.

On top of that, the GNU C library and the GNU libiconv library both support the following two suffixes:

• //TRANSLIT — when you append the string "//TRANSLIT" to tocode, transliteration gets activated. What that means is: when some character can't be represented in the target character set, it can be approximated through one or several similarly looking characters. it's giving "close enough, we ball" 🫶
• //IGNORE — when you append the string "//IGNORE" to tocode, characters that can't be represented in the target character set get silently discarded. gone. no warning, no note, just. gone. 💀

The conversion descriptor you get back can be used with iconv(3) any number of times. She stays valid until you deallocate her using iconv_close(3).

Also important: a conversion descriptor contains a conversion state. After creation using iconv_open(), that state is in the initial state. Using iconv(3) modifies the descriptor's conversion state. And if you wanna bring the state back to the initial state, you use iconv(3) with NULL as the 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.

"among others" is doing a LOT of heavy lifting in that sentence btw. don't assume this is the only one that can hit you 🙈

---

🧚 ATTRIBUTES 🧚

For an explanation of the terms used in this section, see attributes(7).

• Interface: iconv_open()
• Attribute: Thread safety
• Value: MT-Safe locale

so yeah, thread-safe, but she's reading locale info, iykyk 🌍

---

⭐ STANDARDS ⭐

POSIX.1-2008.

---

👑 HISTORY 👑

glibc 2.1. POSIX.1-2001, SUSv2.

---

🎀 SEE ALSO 🎀

iconv(1), iconv(3), iconv_close(3)

---

and that's the whole page, bestie 💜 this was the Linux man-pages 6.20 version, dated 2026-02-08, and honestly? iconic. go convert something. periodt 🦋✨