idn_decodename(3)

💖 idn_decodename(3) 💖

okay so this is a page from the Library Functions Manual (yes, the section-3 girlies 🫶) and it's literally all about turning internationalized domain names back into something your local machine can read. buckle up bestie, it's giving encoding-nerd main character energy ✨

---

✨ NAME ✨

idn_decodename, idn_decodename2 — decode an internationalized domain name 💅

---

🦋 SYNOPSIS 🦋

#include <idn/api.h>

idn_result_t
idn_decodename(idn_action_t actions, const char *from, char *to,
    size_t tolen);

idn_result_t
idn_decodename2(idn_action_t actions, const char *from, char *to,
    size_t tolen, const char *auxencoding);

---

🌸 DESCRIPTION 🌸

So idn_decodename() takes a domain name in from and decodes it, dropping the result into to, writing at most tolen bytes. heads up though: from has to be NUL-terminated, and tolen includes room for that NUL character. no sneaky off-by-ones, bestie 😭

The actions argument is the vibe check — it says which steps of the whole decoding process should actually run. here's the full lineup of action names matching each decoding step, and the function does them in this exact order 👑

• 1. IDN_UNICODECONV — convert a domain name from local decoding (e.g. ISO-8859-1) to UTF-8.
• 2. IDN_MAP — perform mappings (NFC, Lowercase conversion, etc.).
• 3. IDN_ASCLOWER — convert ASCII uppercase letters (A..Z) to lowercase (a..z).
• 4. IDN_IDNCONV — convert A-labels to U-labels.
• 5. IDN_PROHCHECK — check prohibited code points.
• 6. IDN_UNASCHECK — check unassigned code points.
• 7. IDN_NFCCHECK — check labels are in NFC.
• 8. IDN_PREFCHECK — check labels containing -- in the 3rd and 4th characters.
• 9. IDN_HYPHCHECK — check labels beginning/ending with -.
• 10. IDN_COMBCHECK — check labels beginning with a combining mark.
• 11. IDN_CTXJCHECK — check CONTEXTJ code points.
• 12a. IDN_CTXOCHECK — check CONTEXTO code points for the registration protocol.
• 12b. IDN_CTXOLITECHECK — check CONTEXTO code points for the lookup protocol.
• 13. IDN_BIDICHECK — check requirements specified in [IDNA2008-BIDI].
• 14. IDN_LOCALCHECK — perform local check (optional).
• 15. IDN_RTCHECK — perform round trip check for each label.
• 16. IDN_LOCALCONV — convert a domain name from UTF-8 to local encoding (e.g. ISO-8859-1).

between step 2 and step 3, the domain name gets split into labels 🎀 and steps 3 through 15 are applied to each label. then after step 15, the labels get joined back up with a separator, which is literally "." (that's two dots in the manpage's own quoting, iykyk).

you can bitwise-OR a bunch of actions together, like this:

r = idn_decodename(IDN_IDNCONV | IDN_LOCALCONV, from, to, tolen);

💜 the sequel: idn_decodename2()

idn_decodename2() works the same as idn_decodename(), except it does an encoding conversion from auxencoding to UTF-8 before the actual decoding process kicks in. the tradeoff? it ignores the IDN_UNICODECONV action. and if auxencoding is NULL, then from is treated as UTF-8. slay 💅

🎀 convenience actions (you're welcome)

also, these actions exist purely to make your life easier:

• IDN_DECODE_REGIST — decode a domain name with the IDNA2008 registration protocol. libidnkit performs steps 1..11, 12a, 13, 15 and 16. libidnkitlite performs steps 2..11, 12a, 13 and 15.
• IDN_DECODE_LOOKUP — decode a domain name with the IDNA2008 lookup protocol. libidnkit performs steps 1..8, 10, 11, 12b, 13, 15 and 16. libidnkitlite performs steps 2..8, 10, 11, 12b, 13 and 15.

⭐ return values ⭐

on success, the functions return idn_success 🥳 otherwise you get an error code back. for the complete list of error codes, go check idn_result_tostring(3) — she has the receipts.

---

🔥 EXAMPLE 🔥

say you've got an internationalized domain name coming back from a resolver function and you need to decode it — that's a job for idn_decodename():

idn_result_t r;
char ace_name[256];
struct hostent *hp;

...
hp = gethostbyname(name);
r = idn_decodename(IDN_DECODE_LOOKUP, hp->h_name, local_name,
                   sizeof(local_name));
if (r != idn_success) {
    fprintf(stderr, "idn_decodename failed: %s\n",
            idn_result_tostring(r));
    exit(1);
}
printf("name: %s\n", local_name);
...

---

👑 SEE ALSO 👑

idnconv(1), libidnkit(3), idn_nameinit(3), idn_result_tostring(3), idn2.conf(5)

---

okay that's the whole page, no cap 💖 this beauty was dated Sep 21, 2012 (an icon, an absolute legend) and it comes to you straight from the Library Functions Manual — now go decode something and live your truth 🌈✨🎀🦋