idn_decodename(3)idn_decodename(3)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
The function idn_decodename() decodes 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 decoding
process should be performed. The following list shows action names cor‐
responding with steps of the decoding process. The function performs
the steps in that 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 the step 2 and 3, the domain name is split into labels. The
step 3 through 15 are applied to each label. After the step 15, labels
are joined with a separator ``.''.
A value of bitwise-OR of some actions can be specified, like:
r = idn_decodename(IDN_IDNCONV | IDN_LOCALCONV, from, to, tolen);
The function idn_decodename2() works same as idn_decodename(), but an
encoding conversion from auxencoding to UTF-8 is performed prior to the
actual decoding process. Instead, idn_decodename2() ignores IDN_UNI‐
CODECONV action. If auxencoding is NULL, from is treated as UTF-8.
Also the following actions are provided for convenience:
IDN_DECODE_REGIST
Decode a domain name with IDNA2008 registration protocol.
libidnkit performs the step 1..11, 12a, 13, 15 and 16.
libidnkitlite performs the step 2..11, 12a, 13 and 15.
IDN_DECODE_LOOKUP
Decode a domain name with IDNA2008 lookup protocol.
libidnkit performs the step 1..8, 10, 11, 12b, 13, 15 and
16. libidnkitlite performs the step 2..8, 10, 11, 12b, 13
and 15.
Upon success, the functions returns idn_success. Otherwise, it returns
an error code. See idn_result_tostring(3) for the complete list of
error codes.
EXAMPLE
To decode an internationalized domain name returned from a resolver
function, use 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 ALSOidnconv(1), libidnkit(3), idn_nameinit(3), idn_result_tostring(3),
idn2.conf(5)
Sep 21, 2012 idn_decodename(3)
