NAME

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() converts a domain name from and writes the result on to, at most tolen bytes. Note that from must be terminated by NUL, and tolen includes room for a NUL character.

The argument actions specifies which steps in the entire encoding process should be performed. The following list shows action names corresponding with steps of the encoding process. The function performs the steps in that order.

1. IDN_UNICODECONV: Convert a domain name from local encoding (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_RTCONV: 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_IDNCONV: Convert labels in UTF-8 to Punycode.
16. IDN_LENCHECK: Check length of each label.
17. IDN_RTCHECK: Perform round trip check for each label.

Between the step 2 and 3, the domain name is split into labels. The step 3 through 17 are applied to each label. After the step 17, labels are joined with a separator ``.''.

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

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

Also the following actions are provided for convenience:

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.

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);
...

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

SEE ALSO