DragonFly On-Line Manual Pages

idn_encodename(3)     DragonFly Library Functions Manual     idn_encodename(3)

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

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

                              September 21, 2012             idn_encodename(3)