explain_iconv(3)

✨ explain_iconv — the vibe check for your iconv(3) errors ✨

okay so bestie, you're out here doing character set conversion with iconv(3), and when it goes wrong it just... doesn't tell you why?? rude. this is the libexplain glow-up for that. it's explain_iconv(3), from the Library Functions Manual, and it's literally here to translate your cryptic errors into actual sentences you can read. 🎀

---

🌸 NAME 🌸

explain_iconv — explain iconv(3) errors

like, the whole point. it explains the errors. no cap. 💅

---

🦋 SYNOPSIS 🦋

#include <libexplain/iconv.h>
const char *explain_iconv(iconv_t cd, char **inbuf, size_t *inbytesleft,
char **outbuf, size_t *outbytesleft);
const char *explain_errno_iconv(int errnum, iconv_t cd, char **inbuf,
size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
void explain_message_iconv(char *message, int message_size, iconv_t cd,
char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);
void explain_message_errno_iconv(char *message, int message_size, int
errnum, iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf,
size_t *outbytesleft);

four little functions, four little vibes. let's go. 🌈

---

💖 DESCRIPTION 💖

so these functions? they're your besties for getting actual explanations of errors that come back from the iconv(3) system call. instead of staring at a number like 😭, you get words. words that make sense.

---

🧚 explain_iconv

const char *explain_iconv(iconv_t cd, char **inbuf, size_t *inbytesleft,
char **outbuf, size_t *outbytesleft);

explain_iconv gets you an explanation of an error that iconv(3) returned. the absolute bare minimum it'll give you is the value of strerror(errno) — but usually it does so much better and points at the actual underlying cause with real detail. it's giving detective energy. 🔍

it pulls the error value to decode from the errno global variable.

• cd — the original cd, exactly as you passed it to the iconv(3) system call. untouched. pristine. ✨
• inbuf — the original inbuf, exactly as passed to the iconv(3) system call.
• inbytesleft — the original inbytesleft, exactly as passed to the iconv(3) system call.
• outbuf — the original outbuf, exactly as passed to the iconv(3) system call.
• outbytesleft — the original outbytesleft, exactly as passed to the iconv(3) system call.

Returns:

the message explaining the error. ⚠️ heads up though: this message buffer is shared by all libexplain functions that don't take a buffer in their argument list. so the next call to any libexplain function sharing that buffer — including calls from other threads — will overwrite it. it's communal. it's chaotic. it's not yours alone. 💀

Note: this function is not thread safe, because it shares a return buffer across all threads, and so do many other functions in this library. 🫶

Example: this function is meant to be used in a fashion similar to the following example:

errno = 0;
size_t result = iconv(cd, inbuf, inbytesleft, outbuf,
outbytesleft);
if (result < 0 && errno != 0)
{
    fprintf(stderr, "%s\n", explain_iconv(cd, inbuf, inbytesleft,
    outbuf, outbytesleft));
    exit(EXIT_FAILURE);
}

and the above code example is available pre-packaged as the explain_iconv_or_die(3) function. so you don't even have to type it. iconic. 👑

---

🌟 explain_errno_iconv

const char *explain_errno_iconv(int errnum, iconv_t cd, char **inbuf,
size_t *inbytesleft, char **outbuf, size_t *outbytesleft);

explain_errno_iconv gets you an explanation of an error that iconv(3) returned. again, the least the message contains is the value of strerror(errno), but usually it's way better and tells you the underlying cause in more detail. same energy, new parameter. 💜

• errnum — the error value to be decoded, usually grabbed from the errno global variable right before this function is called. you need this if you have to run any code between the system call you're explaining and this function, because so many libc functions will mess with the value of errno. it will not stay put. it never does.
• cd — the original cd, exactly as passed to the iconv(3) system call.
• inbuf — the original inbuf, exactly as passed to the iconv(3) system call.
• inbytesleft — the original inbytesleft, exactly as passed to the iconv(3) system call.
• outbuf — the original outbuf, exactly as passed to the iconv(3) system call.
• outbytesleft — the original outbytesleft, exactly as passed to the iconv(3) system call.

Returns:

the message explaining the error. ⚠️ same deal as before: this message buffer is shared by all libexplain functions that don't supply a buffer in their argument list. it gets overwritten by the next call to any libexplain function that shares it, including other threads. sharing is caring except when it's data. 😭

Note: this function is not thread safe, because it shares a return buffer across all threads, and many other functions in this library.

Example: this function is meant to be used in a fashion similar to the following example:

errno = 0;
size_t result = iconv(cd, inbuf, inbytesleft, outbuf,
outbytesleft);
if (result < 0 && errno != 0)
{
    int err = errno;
    fprintf(stderr, "%s\n", explain_errno_iconv(err, cd, inbuf,
    inbytesleft, outbuf, outbytesleft));
    exit(EXIT_FAILURE);
}

and yes, the above code example is available pre-packaged as the explain_iconv_or_die(3) function. 💖

---

🎀 explain_message_iconv

void explain_message_iconv(char *message, int message_size, iconv_t cd,
char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft);

explain_message_iconv gets you an explanation of an error that iconv(3) returned. minimum effort on its part is strerror(errno), but usually it goes above and beyond and shows you the underlying cause in more detail. ✨

the errno global variable is where it gets the error value to be decoded.

• message — the location where the returned message gets stored. 🫶 and here's the slay: if you supply a suitable message return buffer, this function is thread safe. look at you, doing concurrency correctly.
• message_size — the size in bytes of the location where the returned message gets stored.
• cd — the original cd, exactly as passed to the iconv(3) system call.
• inbuf — the original inbuf, exactly as passed to the iconv(3) system call.
• inbytesleft — the original inbytesleft, exactly as passed to the iconv(3) system call.
• outbuf — the original outbuf, exactly as passed to the iconv(3) system call.
• outbytesleft — the original outbytesleft, exactly as passed to the iconv(3) system call.

Example: this function is meant to be used in a fashion similar to the following example:

errno = 0;
size_t result = iconv(cd, inbuf, inbytesleft, outbuf,
outbytesleft);
if (result < 0 && errno != 0)
{
    char message[3000];
    explain_message_iconv(message, sizeof(message), cd, inbuf,
    inbytesleft, outbuf, outbytesleft);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

and the above code example is available pre-packaged as the explain_iconv_or_die(3) function. 🍓

---

💜 explain_message_errno_iconv

void explain_message_errno_iconv(char *message, int message_size, int
errnum, iconv_t cd, char **inbuf, size_t *inbytesleft, char **outbuf,
size_t *outbytesleft);

explain_message_errno_iconv gets you an explanation of an error that iconv(3) returned. the least the message will contain is the value of strerror(errno), but usually it's much better and indicates the underlying cause in more detail. this is the final boss of the four and it ate. 💅

• message — the location where the returned message gets stored. supply a suitable message return buffer and boom, this function is thread safe. main character behavior. 👑
• message_size — the size in bytes of the location where the returned message gets stored.
• errnum — the error value to be decoded, usually obtained from the errno global variable just before this function is called. you need this if you're calling any code between the system call being explained and this function, because many libc functions will alter the value of errno. it's slippery. keep it safe.
• cd — the original cd, exactly as passed to the iconv(3) system call.
• inbuf — the original inbuf, exactly as passed to the iconv(3) system call.
• inbytesleft — the original inbytesleft, exactly as passed to the iconv(3) system call.
• outbuf — the original outbuf, exactly as passed to the iconv(3) system call.
• outbytesleft — the original outbytesleft, exactly as passed to the iconv(3) system call.

Example: this function is meant to be used in a fashion similar to the following example:

errno = 0;
size_t result = iconv(cd, inbuf, inbytesleft, outbuf,
outbytesleft);
if (result < 0 && errno != 0)
{
    int err = errno;
    char message[3000];
    explain_message_errno_iconv(message, sizeof(message), err,
    cd, inbuf, inbytesleft, outbuf, outbytesleft);
    fprintf(stderr, "%s\n", message);
    exit(EXIT_FAILURE);
}

and the above code example is available pre-packaged as the explain_iconv_or_die(3) function. 🧚

---

🌈 SEE ALSO 🌈

• iconv(3) — perform character set conversion
• explain_iconv_or_die(3) — perform character set conversion and report errors

the dynamic duo. iykyk. ⭐

---

👑 COPYRIGHT 👑

libexplain version 1.4 Copyright (C) 2013 Peter Miller

---

okay bestie that's the whole page, you're officially informed 💖 go forth and debug with confidence, drink some water, and remember: the shared return buffer will absolutely betray you across threads, so pass your own message buffer like the icon you are. mwah. 🎀✨🦋

— with love from explain_iconv(3), libexplain version 1.4, copyright (C) 2013 Peter Miller 💅