idn_encodename(3)

💅 NAME 💅

okay so bestie, meet idn_encodename(3) from the Library Functions Manual — she encodes an internationalized domain name, no cap. 💖

idn_encodename — encode an internationalized domain name. ✨

✨ SYNOPSIS ✨

#include <idn/api.h>

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

🦋 DESCRIPTION 🦋

The function idn_encodename() takes a domain name from from and writes the result into to, using at most tolen bytes. Lowkey important: from must be terminated by NUL, and tolen includes room for a NUL character. 🫶

The actions argument says which steps of the whole encoding process should be performed. Here’s the action-name-to-step lineup, and yes, she performs these steps in exactly this order, periodt:

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

Between step 2 and step 3, the domain name is split into labels. Steps 3 through 17 are applied to each label. After step 17, labels are joined with a separator "." — yes, a literal dot, slay. 🌈

A value of bitwise-OR of some actions can be specified, like:

r = idn_encodename(IDN_UNICODECONV | IDN_MAP, from, to, tolen);

Also, these convenience actions are provided:

• IDN_ENCODE_REGIST — Encode a domain name with IDNA2008 registration protocol. libidnkit performs the step 1..11, 12a, 13 and 15..17. libidnkitlite performs the step 2..11, 12a, 13 and 15..17.
• IDN_ENCODE_LOOKUP — Encode a domain name with IDNA2008 lookup protocol. libidnkit performs the step 1..8, 10, 11, 12b, 13 and 15..17. libidnkitlite performs the step 2..8, 10, 11, 12b, 13 and 15..17.

Upon success, idn_encodename() returns idn_success. Otherwise, it returns an error code. See idn_result_tostring(3) for the complete list of error codes. 💀

🌸 EXAMPLE 🌸

To get an address of an internationalized domain name written in the application’s local encoding, use idn_encodename() to convert the name to the format suitable for passing to resolver functions. Like, literally:

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

...
r = idn_encodename(IDN_ENCODE_LOOKUP, name, ace_name,
                   sizeof(ace_name));
if (r != idn_success) {
    fprintf(stderr, "idn_encodename failed: %s\n",
            idn_result_tostring(r));
    exit(1);
}

hp = gethostbyname(ace_name);
...

🎀 SEE ALSO 🎀

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

xoxo from idn_encodename(3), source Library Functions Manual, dated Sep 21, 2012 — mwah 💋🎀