SDL_iconv(3)

💖 SDL_iconv(3) — the SDL3 FUNCTIONS era 💖

okay bestie, sit DOWN, because this is the one that takes text from one encoding and yeets it into another, reading from a buffer and writing to a buffer. it's giving translator energy. it's giving main character. 🦋

---

✨ NAME ✨

SDL_iconv — This function converts text between encodings, reading from and writing to a buffer.

---

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_stdinc.h>

size_t SDL_iconv(SDL_iconv_t cd, const char **inbuf,
             size_t *inbytesleft, char **outbuf,
             size_t *outbytesleft);

#define SDL_ICONV_ERROR     (size_t)-1  /**< Generic error. Check SDL_GetError()? */
#define SDL_ICONV_E2BIG     (size_t)-2  /**< Output buffer was too small. */
#define SDL_ICONV_EILSEQ    (size_t)-3  /**< Invalid input sequence was encountered. */
#define SDL_ICONV_EINVAL    (size_t)-4  /**< Incomplete input sequence was encountered. */

those four #defines? iconic. keep them. they're your little error-code girlies and you will be seeing them again in a sec. 💅

---

🌸 DESCRIPTION 🌸

So here's the tea: on success it returns the number of successful conversions. On error, it hands you back one of the moody little codes:

• SDL_ICONV_E2BIG gets returned when the output buffer is too small 🫠
• SDL_ICONV_EILSEQ gets returned when an invalid input sequence is encountered 💀
• SDL_ICONV_EINVAL gets returned when an incomplete input sequence is encountered 🙈

And then — plot twist — the pointers get mutated on exit. Not me gaslighting you, it literally rewrites your variables:

• inbuf will point to the beginning of the next multibyte sequence. On error, this is the location of the problematic input sequence. On success, this is the end of the input sequence.
• inbytesleft will be set to the number of bytes left to convert, which will be 0 on success.
• outbuf will point to the location where to store the next output byte.
• outbytesleft will be set to the number of bytes left in the output buffer.

like… it's a whole glow-up for your pointers, fr fr. ✨

---

💖 FUNCTION PARAMETERS 💖

• cd — The character set conversion context, created in SDL_iconv_open(). your little conversion passport 🛂
• inbuf — Address of variable that points to the first character of the input sequence.
• inbytesleft — The number of bytes in the input buffer.
• outbuf — Address of variable that points to the output buffer.
• outbytesleft — The number of bytes in the output buffer.

---

⭐ RETURN VALUE ⭐

Returns the number of conversions on success, or a negative error code. that's it. that's the whole vibe check. 👑

---

🔥 THREAD SAFETY 🔥

Do not use the same SDL_iconv_t from two threads at once.

bestie I am BEGGING you. one SDL_iconv_t per thread. share it and you're gonna have a bad time. no cap. 😭

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. so if you're on anything older, this is not the moment, hun. 🧚

---

💜 SEE ALSO 💜

• SDL_iconv_open(3)
• SDL_iconv_close(3)
• SDL_iconv_string(3)

the whole iconv friend group. go say hi. 🫶

---

and that's the page, bestie!! this lil masterpiece came to you from Simple Directmedia Layer, version SDL 3.4.18, dated SDL_iconv(3) — slay, stay encoded, and always free your SDL_iconv_t 💖✨🎀