UNICODE_CONVERT(3)

✨ UNICODE_CONVERT(3) ✨

okay so bestie 💖 welcome to the Courier Unicode Library page for all the unicode character set conversion girlies. this one's a whole squad of functions, so grab a snack and let's get into it 🍓

---

🌸 NAME 🌸

unicode_u_ucs4_native, unicode_u_ucs2_native, unicode_convert_init, unicode_convert, unicode_convert_deinit, unicode_convert_tocbuf_init, unicode_convert_tou_init, unicode_convert_fromu_init, unicode_convert_uc, unicode_convert_tocbuf_toutf8_init, unicode_convert_tocbuf_fromutf8_init, unicode_convert_toutf8, unicode_convert_fromutf8, unicode_convert_tobuf, unicode_convert_tou_tobuf, unicode_convert_fromu_tobuf — that's right, unicode character set conversion 👑

---

🦋 SYNOPSIS 🦋

#include <courier-unicode.h>

extern const char unicode_u_ucs4_native[];

extern const char unicode_u_ucs2_native[];

unicode_convert_handle_t unicode_convert_init(const char *src_chset,
                                              const char *dst_chset,
                                              void *cb_arg);

int unicode_convert(unicode_convert_handle_t handle, const char *text,
                    size_t cnt);

int unicode_convert_deinit(unicode_convert_handle_t handle,
                           int *errptr);

unicode_convert_handle_t
unicode_convert_tocbuf_init(const char *src_chset,
                            const char *dst_chset,
                            char **cbufptr_ret,
                            size_t *cbufsize_ret,
                            int nullterminate);

unicode_convert_handle_t
unicode_convert_tocbuf_toutf8_init(const char *src_chset,
                                   char **cbufptr_ret,
                                   size_t *cbufsize_ret,
                                   int nullterminate);

unicode_convert_handle_t
unicode_convert_tocbuf_fromutf8_init(const char *dst_chset,
                                     char **cbufptr_ret,
                                     size_t *cbufsize_ret,
                                     int nullterminate);

unicode_convert_handle_t unicode_convert_tou_init(const char *src_chset,
                                                  char32_t **ucptr_ret,
                                                  size_t *ucsize_ret,
                                                  int nullterminate);

unicode_convert_handle_t
unicode_convert_fromu_init(const char *dst_chset,
                           char **cbufptr_ret,
                           size_t *cbufsize_ret,
                           int nullterminate);

int unicode_convert_uc(unicode_convert_handle_t handle,
                       const char32_t *text, size_t cnt);

char *unicode_convert_toutf8(const char *text, const char *charset,
                             int *error);

char *unicode_convert_fromutf8(const char *text, const char *charset,
                               int *error);

char *unicode_convert_tobuf(const char *text, const char *charset,
                            const char *dstcharset, int *error);

int unicode_convert_toubuf(const char *text, size_t text_l,
                           const char *charset, char32_t **uc,
                           size_t *ucsize, int *error);

int unicode_convert_fromu_tobuf(const char32_t *utext, size_t utext_l,
                                const char *charset, char **c,
                                size_t *csize, int *error);

---

💅 DESCRIPTION 💅

unicode_u_ucs4_native[] is holding the string "UCS-4BE" or "UCS-4LE", whichever one matches the native char32_t endianness. it's giving "i know what endianness you are bestie" 😌

unicode_u_ucs2_native[] is the same deal but for "UCS-2BE" or "UCS-2LE" — again matching the native char32_t endianness. 🎀

unicode_convert_init(), unicode_convert(), and unicode_convert_deinit() are basically an adaption of the iconv(3) API, using the same calling convention as all the other algorithms in this unicode library, but with some value-added features on top. and fr fr, these functions use iconv(3) underneath to do the actual character set conversion. no cap. ✨

unicode_convert_init() hands you back a non-NULL handle for the conversion you asked for, or NULL if that conversion isn't available. it takes a pointer to the output function that receives the converted character text. that output function gets a pointer to the converted character text plus the number of characters in the converted text, and it gets called repeatedly until it has received the entire converted text. iconic behavior honestly. 🫶

the character text you wanna convert gets passed to unicode_convert() over and over. every call to unicode_convert() makes the output function get invoked zero or more times, each time with the next successive part of the converted text. and finally, unicode_convert_deinit() stops the conversion and deallocates the conversion handle. periodt. 💅

heads up: it's possible that a call to unicode_convert_deinit() triggers some additional calls to the output function, passing along the remaining final parts of the converted text, before unicode_convert_deinit() deallocates the handle and returns. so don't be surprised, bestie 🙈

the output function should return 0 normally. a non-0 return indicates an error condition. unicode_convert_deinit() returns non-zero if any previous invocation of the output function returned non-zero (and yes, that includes any invocations resulting from this call, or from prior unicode_convert() calls), or 0 if every single invocation of the output function returned 0. 🌈

if errptr isn't NULL, then *errptr gets set to non-zero when there were any conversion errors — like, if there was any text that straight up could not be converted to the destination character text. 😭

unicode_convert() also returns non-zero if it calls the output function and that returns non-zero. but listen — the conversion handle is still allocated, so you still have to call unicode_convert_deinit() to clean it up. don't leave it hanging. 🧚

---

🎀 Collecting converted text into a buffer 🎀

call unicode_convert_tocbuf_init() instead of unicode_convert_init(), then call unicode_convert() and unicode_convert_deinit() like normal. the parameters to unicode_convert_init() specify the source and the destination character sets. unicode_convert_tocbuf_toutf8_init() is just an alias that specifies UTF-8 as the destination character set, and unicode_convert_tocbuf_fromutf8_init() is just an alias that specifies UTF-8 as the source character set.

these functions supply an output function that collects all the converted text into a malloc()ed buffer. if unicode_convert_deinit() returns 0, *cbufptr_ret gets initialized to a malloc()ed buffer, and the number of converted characters — that is, the size of the malloc()ed buffer — gets placed into *cbufsize_ret. 💖

Note 🫧 if the converted string is an empty string, *cbufsize_ret gets set to 0, but *cbufptr_ret still gets initialized (to a dummy malloced buffer). she's empty but she's still there bestie 🥲

a non-zero nullterminate places a trailing \0 character after the converted string — and yep, that trailing character is included in *cbufsize_ret. ✨

---

🦋 Converting between character sets and unicode 🦋

unicode_convert_tou_init() converts character text into a char32_t buffer. it works just like unicode_convert_tocbuf_init(), except only the source character set gets specified, and the output buffer is a char32_t buffer. nullterminate terminates the converted unicode characters with a U+0000. 👑

unicode_convert_fromu_init() converts char32_ts to the output character set, and it also works just like unicode_convert_tocbuf_init(). and additionally, in this case, unicode_convert_uc() works just like unicode_convert() except that the input sequence is a char32_t sequence, and the count parameter is the number of unicode characters. slay. 💅

---

🌈 One-shot conversions 🌈

unicode_convert_toutf8() converts the specified text (in the specified character set) into a UTF-8 string, returning a malloced buffer. if error is not NULL, then even if unicode_convert_toutf8() returns a non-NULL value, *error gets set to a non-zero value if a character conversion error has occurred and some characters could not be converted. 😭

unicode_convert_fromutf8() does a similar conversion, going from UTF-8 text to the specified character set.

unicode_convert_tobuf() does a similar conversion between two different character sets. 🎀

unicode_convert_tou_tobuf() calls unicode_convert_tou_init(), feeds the character string through unicode_convert(), then calls unicode_convert_deinit(). if this function returns 0, *uc and *ucsize are set to a malloced buffer + size holding the unicode char array. 🫶

unicode_convert_fromu_tobuf() calls unicode_convert_fromu_init(), feeds the unicode array through unicode_convert_uc(), then calls unicode_convert_deinit(). if this function returns 0, *c and *csize are set to a malloced buffer + size holding the char array. ⭐

---

👑 SEE ALSO 👑

courier-unicode(7), unicode_convert_tocase(3), unicode_default_chset(3).

---

💜 AUTHOR 💜

Sam Varshavchik — Author 🫡

---

and that's the whole page bestie 💖 this was UNICODE_CONVERT(3) from the Courier Unicode Library, dated 04/12/2026. go convert some character sets, you've absolutely got this. mwah 💅✨🎀