explain_iconv_or_die(3)

✨ NAME ✨

okay so bestie, welcome to explain_iconv_or_die — it's a 3 manual page from the Library Functions Manual, and it does exactly what it says on the tin: it performs character set conversion and reports errors 💖 no cap.

---

🌸 SYNOPSIS 🌸

#include <libexplain/iconv.h>
size_t explain_iconv_or_die(iconv_t cd, char **inbuf, size_t
*inbytesleft, char **outbuf, size_t *outbytesleft);
size_t explain_iconv_on_error(iconv_t cd, char **inbuf, size_t
*inbytesleft, char **outbuf, size_t *outbytesleft);

like, two functions, both iconic, both yours 🫶

---

💅 DESCRIPTION 💅

so the explain_iconv_or_die function is the one you call to call the iconv(3) system call. and here's the drama: on failure, an explanation gets printed to stderr (obtained from the explain_iconv(3) function), and then the process just... terminates by calling exit(EXIT_FAILURE). it's giving main character exit. it does not come back 💀

the explain_iconv_on_error function is the chill sibling. it also calls the iconv(3) system call, and on failure it also prints an explanation to stderr (again, obtained from the explain_iconv(3) function), BUT it still returns to the caller. no dramatic exit, just vibes ✨

now the parameters, one by one, no skips:

• cd — the cd, exactly as to be passed to the iconv(3) system call.
• inbuf — the inbuf, exactly as to be passed to the iconv(3) system call.
• inbytesleft — the inbytesleft, exactly as to be passed to the iconv(3) system call.
• outbuf — the outbuf, exactly as to be passed to the iconv(3) system call.
• outbytesleft — the outbytesleft, exactly as to be passed to the iconv(3) system call.

periodt. every single one gets passed through untouched, bestie 💖

---

🦋 RETURN VALUE 🦋

the explain_iconv_or_die function only returns on success — see iconv(3) for more information. on failure, it prints an explanation and exits. it does not return. like, at all. it's gone. 🙈

the explain_iconv_on_error function always returns the value return by the wrapped iconv(3) system call. always. it stays. loyal. 🫶

---

🎀 EXAMPLE 🎀

the explain_iconv_or_die function is intended to be used in a fashion similar to the following example:

size_t result = explain_iconv_or_die(cd, inbuf, inbytesleft, outbuf,
    outbytesleft);

literally copy that energy and you're set ✨

---

🌈 SEE ALSO 🌈

• iconv(3) — perform character set conversion
• explain_iconv(3) — explain iconv(3) errors
• exit(2) — terminate the calling process

all the besties, in one place 💜

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2013 Peter Miller

---

okay that's the whole page bestie, and the little sign-off at the bottom of the original says libexplain version 1.4, Copyright (C) 2013 Peter Miller — go forth and convert those character sets, you absolute icon 💅💖