ICONV(3)

💅 ICONV(3) — codeset conversion, but make it cute

okay bestie so this page lives in the Library Functions Manual section of the Standard C Library (libc, -lc) and it's literally all about iconv_open, iconv_open_into, iconv_close, and iconv — the codeset conversion girlies. let's go 🦋

---

✨ NAME ✨

iconv_open, iconv_open_into, iconv_close, iconv — codeset conversion functions. that's the whole vibe, no cap 🎀

---

📚 LIBRARY 📚

Standard C Library (libc, -lc). iconic. 👑

---

🌸 SYNOPSIS 🌸

#include <iconv.h>

iconv_t
iconv_open(const char *dstname, const char *srcname);

int
iconv_open_into(const char *dstname, const char *srcname,
    iconv_allocation_t *ptr);

int
iconv_close(iconv_t cd);

size_t
iconv(iconv_t cd, char ** restrict src, size_t * restrict srcleft,
    char ** restrict dst, size_t * restrict dstleft);

size_t
__iconv(iconv_t cd, char ** restrict src, size_t * restrict srcleft,
    char ** restrict dst, size_t * restrict dstleft, uint32_t flags,
    size_t * invalids);

---

💜 DESCRIPTION 💜

🫶 the opening moves

iconv_open() opens a converter from the codeset srcname to the codeset dstname and hands you back its descriptor. and yes, the arguments srcname and dstname accept "" and "char" — both of those refer to the current locale encoding. cute right? 🥰

🧚 iconv_open_into

iconv_open_into() creates a conversion descriptor on a preallocated space. the iconv_allocation_t is used as a spaceholder type when you're allocating that space. the dstname and srcname arguments are exactly the same as in the case of iconv_open(). and ptr is a pointer of iconv_allocation_t to the preallocated space. no extra shopping trips to malloc, we love efficiency ✨

🎀 iconv_close

iconv_close() closes the specified converter cd. say bye bestie 👋

🦋 iconv, the main character

iconv() converts the string in the buffer *src of length *srcleft bytes and stores the converted string in the buffer *dst of size *dstleft bytes. after calling iconv(), the values pointed to by src, srcleft, dst, and dstleft get updated like this:

• *src — pointer to the byte just after the last character fetched.
• *srcleft — number of remaining bytes in the source buffer.
• *dst — pointer to the byte just after the last character stored.
• *dstleft — number of remainder bytes in the destination buffer.

😭 when things don't convert

if the string pointed to by *src contains a byte sequence which is not a valid character in the source codeset, the conversion stops just after the last successful conversion. and if the output buffer is too small to store the converted character, the conversion also stops in the same way. in these cases, the values pointed to by src, srcleft, dst, and dstleft are updated to the state just after the last successful conversion. so like, everyone's on the same page about where we gave up 🫠

💀 "invalid character" behaviour

if the string pointed to by *src contains a character which is valid under the source codeset but can not be converted to the destination codeset, that character is replaced by an "invalid character" which depends on the destination codeset, e.g., '?', and the conversion just continues. iconv() returns the number of such "invalid conversions". not me counting the casualties 💅

🍓 two special cases of iconv()

• src == NULL || *src == NULL

if the source and/or destination codesets are stateful, iconv() places these into their initial state.

if both dst and *dst are non-NULL, iconv() stores the shift sequence for the destination switching to the initial state in the buffer pointed to by *dst. the buffer size is specified by the value pointed to by dstleft as above. iconv() will fail if the buffer is too small to store the shift sequence.

on the other hand, dst or *dst may be NULL. in this case, the shift sequence for the destination switching to the initial state is discarded.

🌈 __iconv, the non-standard bonus track

__iconv() works just like iconv() but if iconv() fails, the invalid character count is lost there. this is a not bug rather a limitation of IEEE Std 1003.1-2008 ("POSIX.1"), so __iconv() is provided as an alternative but non-standard interface. it also has a flags argument, where currently the following flags can be passed:

• __ICONV_F_HIDE_INVALID — skip invalid characters, instead of returning with an error. gaslight, gatekeep, girlboss 🙈

---

🔥 RETURN VALUES 🔥

• upon successful completion of iconv_open(), it returns a conversion descriptor. otherwise, iconv_open() returns (iconv_t)-1 and sets errno to indicate the error.
• upon successful completion of iconv_open_into(), it returns 0. otherwise, iconv_open_into() returns -1, and sets errno to indicate the error.
• upon successful completion of iconv_close(), it returns 0. otherwise, iconv_close() returns -1 and sets errno to indicate the error.
• upon successful completion of iconv(), it returns the number of "invalid" conversions. otherwise, iconv() returns (size_t)-1 and sets errno to indicate the error.

---

💀 ERRORS 💀

iconv_open()

the iconv_open() function may cause an error in the following cases:

• [ENOMEM] — memory is exhausted. 😵
• [EINVAL] — there is no converter specified by srcname and dstname.

iconv_open_into()

the iconv_open_into() function may cause an error in the following cases:

• [EINVAL] — there is no converter specified by srcname and dstname.

iconv_close()

the iconv_close() function may cause an error in the following case:

• [EBADF] — the conversion descriptor specified by cd is invalid.

iconv()

the iconv() function may cause an error in the following cases:

• [EBADF] — the conversion descriptor specified by cd is invalid.
• [EILSEQ] — the string pointed to by *src contains a byte sequence which does not describe a valid character of the source codeset.
• [E2BIG] — the output buffer pointed to by *dst is too small to store the result string.
• [EINVAL] — the string pointed to by *src terminates with an incomplete character or shift sequence.

---

🌟 SEE ALSO 🌟

iconv(1), mkcsmapper(1), mkesdb(1), __iconv_get_list(3), iconv_canonicalize(3), iconvctl(3), iconvlist(3)

go read the whole friend group, iykyk 💖

---

👑 STANDARDS 👑

the iconv_open(), iconv_close(), and iconv() functions conform to IEEE Std 1003.1-2008 ("POSIX.1"). periodt ✨

the iconv_open_into() function is a GNU-specific extension and it is not part of any standard, thus its use may break portability. the __iconv() function is an own extension and it is not part of any standard, thus its use may break portability. so like, portability-wise? tread carefully bestie 🫶

---

fr fr the only rule is: keep every byte, every flag, every errno. the vibes are mine, the facts are POSIX's. 🧚

---

and that's the whole page, mwah 💋 — this one's from Debian, dated August 4, 2014, and it's ICONV(3) through and through. slay 🎀