iconv(3)

💫 iconv(3) — the glow-up where your bytes change outfits 💫

okay bestie, pull up a chair 🫶 this is iconv(3) from the Library Functions Manual, living in the Standard C library (libc, -lc). She converts your characters from one encoding to another, and honestly? iconic behaviour. no cap.

---

🌸 NAME 🌸

iconv — perform character set conversion ✨

📚 LIBRARY 📚

Standard C library (libc, -lc) 💖

🎀 SYNOPSIS 🎀

#include <iconv.h>

size_t iconv(iconv_t cd,
             char **restrict inbuf, size_t *restrict inbytesleft,
             char **restrict outbuf, size_t *restrict outbytesleft);

---

🦋 DESCRIPTION 🦋

so like, the iconv() function converts a sequence of characters in one character encoding into a sequence of characters in a different character encoding. she's a translator, she's multilingual, she's giving main character energy 💅

• cd — the conversion descriptor. this is something you already made by calling iconv_open(3) earlier. it's the one that defines which two encodings iconv() is using for the conversion. no cd, no vibes.
• inbuf — the address of a variable that points to the first character of the input sequence. yes, address-of-a-pointer, we love a double pointer moment 🙈
• inbytesleft — how many bytes are chillin' in that input buffer.
• outbuf — the address of a variable pointing to the first byte available in the output buffer.
• outbytesleft — how many bytes are available in the output buffer.

✨ the main case (the one you'll actually use) ✨

this is when inbuf is not NULL and *inbuf is not NULL. in this case iconv() converts the multibyte sequence starting at *inbuf into a multibyte sequence starting at *outbuf.

• at most *inbytesleft bytes, starting at *inbuf, will be read 📖
• at most *outbytesleft bytes, starting at *outbuf, will be written ✍️

she converts one multibyte character at a time, and for each character conversion she does the lil bookkeeping dance:

• increments *inbuf and decrements *inbytesleft by the number of converted input bytes
• increments *outbuf and decrements *outbytesleft by the number of converted output bytes
• updates the conversion state contained inside cd

and here's a fun one: if the input's character encoding is stateful, iconv() can also convert a sequence of input bytes into an update to the conversion state without producing any output bytes at all. that kind of input is called a shift sequence. sneaky. love that for her.

the conversion can stop for five reasons, and bestie you gotta know all five:

• 😭 an invalid multibyte sequence shows up in the input. she sets errno to EILSEQ and returns (size_t) -1. *inbuf is left pointing at the beginning of the invalid multibyte sequence.
• 😭 a multibyte sequence shows up that's valid but can't be translated into the output's character encoding. this one depends on the implementation and on the conversion descriptor. in the GNU C library and GNU libiconv, if cd was created without the suffix //TRANSLIT or //IGNORE, the conversion is strict: lossy conversions produce this condition. if the suffix //TRANSLIT was specified, transliteration can avoid this condition in some cases. in the musl C library, this condition can't occur at all, because a conversion to '*' is used as a fallback. in the FreeBSD, NetBSD, and Solaris implementations of iconv(), this condition can't occur either, because a conversion to '?' is used as a fallback. when this condition is met, iconv() sets errno to EILSEQ and returns (size_t) -1. *inbuf is left pointing at the beginning of the unconvertible multibyte sequence.
• ✅ the input byte sequence has been entirely converted, i.e. *inbytesleft has gone down to 0. in this case iconv() returns the number of nonreversible conversions performed during this call. slay.
• 😭 an incomplete multibyte sequence shows up in the input, and the input byte sequence terminates right after it. she sets errno to EINVAL and returns (size_t) -1. *inbuf is left pointing at the beginning of the incomplete multibyte sequence.
• 😭 the output buffer has no more room for the next converted character. she sets errno to E2BIG and returns (size_t) -1.

🌀 the second case (the reset/flush moment) 🌀

different scenario: inbuf is NULL or *inbuf is NULL, but outbuf is not NULL and *outbuf is not NULL.

here, iconv() tries to set cd's conversion state back to the initial state and store a corresponding shift sequence at *outbuf. at most *outbytesleft bytes, starting at *outbuf, will be written.

if the output buffer has no more room for this reset sequence, she sets errno to E2BIG and returns (size_t) -1. otherwise she increments *outbuf and decrements *outbytesleft by the number of bytes written. ✨ clean slate energy ✨

🧘 the third case (the quiet one) 🧘

third case: inbuf is NULL or *inbuf is NULL, and outbuf is NULL or *outbuf is NULL.

in this case iconv() just sets cd's conversion state to the initial state. that's it. no output, no drama, just vibes.

---

🔥 RETURN VALUE 🔥

iconv() returns the number of characters converted in a nonreversible way during this call — reversible conversions don't get counted, they're just out here living rent-free 😌

in case of error, iconv() returns (size_t) -1 and sets errno to indicate the error.

---

💀 ERRORS 💀

the following errors can occur, among others (so this is not an exhaustive list, okay?):

• E2BIG — there isn't sufficient room at *outbuf. your output buffer said "no more room bestie" 🚫
• EILSEQ — an invalid multibyte sequence has been encountered in the input.
• EINVAL — an incomplete multibyte sequence has been encountered in the input.

---

👑 ATTRIBUTES 👑

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

• Interface: iconv()
  • Attribute: Thread safety
  • Value: MT-Safe race:cd

the iconv() function is MT-Safe, as long as callers arrange for mutual exclusion on the cd argument. so like, thread-safe but only if y'all take turns with cd, okay?? no fighting over the descriptor 🤝

---

🌈 STANDARDS 🌈

POSIX.1-2008.

---

🕰️ HISTORY 🕰️

glibc 2.1. POSIX.1-2001.

---

📝 NOTES 📝

• in each series of calls to iconv(), the last one should be a call with inbuf or *inbuf equal to NULL, so you can flush out any partially converted input. don't skip the flush, bestie, it's not optional in spirit 🚿
• even though inbuf and outbuf are typed as char **, that does not mean the objects they point to can be interpreted as C strings or as arrays of characters. the interpretation of character byte sequences is handled internally by the conversion functions. in some encodings, a zero byte may be a valid part of a multibyte character. so do NOT go treating them as cute lil strings, that's a trap 🙈
• the caller of iconv() must ensure that the pointers passed to the function are suitable for accessing characters in the appropriate character set. this includes ensuring correct alignment on platforms that have tight restrictions on alignment. alignment matters, periodt.

---

🫶 SEE ALSO 🫶

iconv_close(3), iconv_open(3), iconvconfig(8)

---

💖 that's the whole page! go convert something and remember: flush your state, check your errno, and never assume char ** means "string" 💖

and that's a wrap on iconv(3), straight from Linux man-pages 6.20, dated 2026-02-08. mwah 💅✨