idn_decodename(3EXT) Extended Library Functions idn_decodename(3EXT)NAME
idn_decodename, idn_decodename2, idn_enable, idn_encodename,
idn_nameinit - IDN (Internationalized Domain Name) conversion functions
SYNOPSIS
cc [ flag... ] file... -lidnkit [ library... ]
#include <idn/api.h>
idn_result_t idn_decodename(int actions, const char *from, char *to,
size_t tolen);
idn_result_t idn_decodename2(int actions, const char *from, char *to,
size_t tolen, const char *auxencoding);
idn_result_t idn_encodename(int actions, const char *from, char *to,
size_t tolen);
void idn_enable(int on_off);
idn_result_t idn_nameinit(int load_file);
DESCRIPTION
The idn_nameinit() function initializes the library. It also sets
default configuration if load_file is 0, otherwise it tries to read a
configuration file. If idn_nameinit() is called more than once, the
library initialization will take place only at the first call while the
actual configuration procedure will occur at every call.
If there are no errors, idn_nameinit() returns idn_success. Otherwise,
the returned value indicates the cause of the error. See the section
RETURN VALUES below for the error codes.
It is usually not necessary to call this function explicitly because it
is implicitly called when idn_encodename(), idn_decodename(), or
idn_decodename2() is first called without prior calling of
idn_nameinit().
The idn_encodename() function performs name preparation and encoding
conversion on the internationalized domain name specified by from, and
stores the result to to, whose length is specified by tolen. The
actions argument is a bitwise-OR of the following macros, specifying
which subprocesses in the encoding process are to be employed.
IDN_LOCALCONV Local encoding to UTF-8 conversion
IDN_DELIMMAP Delimiter mapping
IDN_LOCALMAP Local mapping
IDN_NAMEPREP NAMEPREP mapping, normalization, prohibited character
check, and bidirectional string check
IDN_UNASCHECK NAMEPREP unassigned codepoint check
IDN_ASCCHECK ASCII range character check
IDN_IDNCONV UTF-8 to IDN encoding conversion
IDN_LENCHECK Label length check
Details of this encoding process can be found in the section Name
Encoding
For convenience, also IDN_ENCODE_QUERY, IDN_ENCODE_APP, and
IDN_ENCODE_STORED macros are provided. IDN_ENCODE_QUERY is used to
encode a ``query string'' (see the IDNA specification). It is equal to:
(IDN_LOCALCONV | IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP |
IDN_IDNCONV | IDN_LENCHECK)
IDN_ENCODE_APP is used for ordinary application to encode a domain
name. It performs IDN_ASCCHECK in addition with IDN_ENCODE_QUERY.
IDN_ENCODE_STORED is used to encode a ``stored string'' (see the IDNA
specification). It performs IDN_ENCODE_APP plus IDN_UNASCHECK.
The idn_decodename() function performs the reverse of idn_encodename().
It converts the internationalized domain name given by from, which is
represented in a special encoding called ACE (ASCII Compatible Encod‐
ing), to the application's local codeset and stores in to, whose length
is specified by tolen. As in idn_encodename(), actions is a bitwise-OR
of the following macros.
IDN_DELIMMAP Delimiter mapping
IDN_NAMEPREP NAMEPREP mapping, normalization, prohibited character
check and bidirectional string check
IDN_UNASCHECK NAMEPREP unassigned codepoint check
IDN_IDNCONV UTF-8 to IDN encoding conversion
IDN_RTCHECK Round trip check
IDN_ASCCHECK ASCII range character check
IDN_LOCALCONV Local encoding to UTF-8 conversion
Details of this decoding process can be found in the section Name
Decoding.
For convenience, IDN_DECODE_QUERY, IDN_DECODE_APP, and
IDN_DECODE_STORED macros are also provided. IDN_DECODE_QUERY is used to
decode a ``query string'' (see the IDNA specification). It is equal to
(IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK | IDN_LOCALCONV)
IDN_DECODE_APP is used for ordinary application to decode a domain
name. It performs IDN_ASCCHECK in addition to IDN_DECODE_QUERY.
IDN_DECODE_STORED is used to decode a ``stored string'' (see the IDNA
specification). It performs IDN_DECODE_APP plus IDN_UNASCHECK.
The idn_decodename2() function provides the same functionality as
idn_decodename() except that character encoding of from is supposed to
be auxencoding. If IDN encoding is Punycode and auxencoding is
ISO8859-2, for example, it is assumed that the Punycode string stored
in from is written in ISO8859-2.
In the IDN decode procedure, IDN_NAMEPREP is done before IDN_IDNCONV,
and some non-ASCII characters are converted to ASCII characters as the
result of IDN_NAMEPREP. Therefore, ACE string specified by from might
contains those non-ASCII characters. That is the reason docode_name2()
exists.
All of thsee functions return an error value of type idn_result_t. All
values other than idn_success indicates some kind of failure.
Name Encoding
Name encoding is a process that transforms the specified international‐
ized domain name to a certain string suitable for name resolution. For
each label in a given domain name, the encoding processor performs:
1. Convert to UTF-8 (IDN_LOCALCONV)
Convert the encoding of the given domain name from applica‐
tion's local encoding (for example, ISO8859-1) to UTF-8.
2. Delimiter mapping (IDN_DELIMMAP)
Map domain name delimiters to `.' (U+002E). The reco- ginzed
delimiters are: U+3002 (ideographic full stop), U+FF0E
(fullwidth full stop), U+FF61 (halfwidth ideographic full
stop).
3. Local mapping (IDN_LOCALMAP)
Apply character mapping whose rule is determined by the top-
level domain name.
4. NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)
Perform name preparation (NAMEPREP), which is a standard
process for name canonicalizaion of internationalized domain
names.
NAMEPREP consists of 5 steps: mapping, normalization, pro‐
hibited character check, bidirectional text check, and unas‐
signed codepoint check. The first four steps are done by
IDN_NAMEPREP, and the last step is done by IDN_UNASCHECK.
5. ASCII range character check (IDN_ASCCHECK)
Checks if the domain name contains non-LDH ASCII characters
(not letter, digit, or hyphen characters), or it begins or
end with hyphen.
6. Convert to ACE (IDN_IDNCONV)
Convert the NAMEPREPed name to a special encoding designed
for representing internationalized domain names.
The encoding is known as ACE (ASCII Compatible Encoding)
since a string in the encoding is just like a traditional
ASCII domain name consisting of only letters, digits and
hyphens.
7. Label length check (IDN_LENCHECK)
For each label, check the number of characters in it. It
must be in the range of 1 to 63.
Name Decoding
Name decoding is a reverse process of the name encoding. It transforms
the specified internationalized domain name in a special encoding suit‐
able for name resolution to the normal name string in the application's
current codeset. However, name encoding and name decoding are not sym‐
metric.
For each label in a given domain name, the decoding processor performs:
1. Delimiter mapping (IDN_DELIMMAP)
Map domain name delimiters to `.' (U+002E). The recoginzed
delimiters are: U+3002 (ideographic full stop), U+FF0E
(fullwidth full stop), U+FF61 (halfwidth ideographic full
stop).
2. NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)
Perform name preparation (NAMEPREP), which is a standard
process for name canonicalizaion of internationalized domain
names.
3. Convert to UTF-8 (IDN_IDNCONV)
Convert the encoding of the given domain name from ACE to
UTF-8.
4. Round trip check (IDN_RTCHECK)
Encode the result of (3) using the Name Encoding scheme,
and then compare it with the result of the step (2). If they
are different, the check is failed. If IDN_UNASCHECK,
IDN_ASCCHECK or both are specified, they are also done in
the encoding processes.
5. Convert to local encoding
Convert the result of (3) from UTF-8 to the application's
local encoding (for example, ISO8859-1).
If prohibited character check, unassigned codepoint check or bidirec‐
tional text check at step (2) failed, or if round trip check at step
(4) failed, the original input label is returned.
Disabling IDN
If your application should always disable internationalized domain name
support for some reason, call
(void) idn_enable(0);
before performing encoding/decoding. Afterward, you can enable the sup‐
port by calling
(void) idn_enable(1);
RETURN VALUES
These functions return values of type idn_result_t to indicate the sta‐
tus of the call. The following is a complete list of the status codes.
idn_success Not an error. The call succeeded.
idn_notfound Specified information does not exist.
idn_invalid_encoding The encoding of the specified string is
invalid.
idn_invalid_syntax There is a syntax error in internal configura‐
tion file(s).
idn_invalid_name The specified name is not valid.
idn_invalid_message The specified message is not valid.
idn_invalid_action The specified action contains invalid flags.
idn_invalid_codepoint The specified Unicode code point value is not
valid.
idn_invalid_length The number of characters in an ACE label is
not in the range of 1 to 63.
idn_buffer_overflow The specified buffer is too small to hold the
result.
idn_noentry The specified key does not exist in the hash
table.
idn_nomemory Memory allocation using malloc failed.
idn_nofile The specified file could not be opened.
idn_nomapping Some characters do not have the mapping to the
target character set.
idn_context_required Context information is required.
idn_prohibited The specified string contains some prohibited
characters.
idn_failure Generic error which is not covered by the
above codes.
EXAMPLES
Example 1 Get the address of an internationalized domain name.
To get the address of an internationalized domain name in the applica‐
tion's local codeset, use idn_encodename() to convert the name to the
format suitable for passing to resolver functions.
#include <idn/api.h>
#include <sys/socket.h>
#include <netdb.h>
...
idn_result_t r;
char ace_name[256];
struct hostent *hp;
int error_num;
...
r = idn_encodename(IDN_ENCODE_APP, name, ace_name,
sizeof(ace_name));
if (r != idn_success) {
fprintf(stderr, gettext("idn_encodename failed.\n"));
exit(1);
}
hp = getipnodebyname(ace_name, AF_INET6, AI_DEFAULT, &error_num);
...
Example 2 Decode the internationalized domain name.
To decode the internationalized domain name returned from a resolver
function, use idn_decodename().
#include <idn/api.h>
#include <sys/socket.h>
#include <netdb.h>
...
idn_result_t r;
char local_name[256];
struct hostent *hp;
int error_num;
...
hp = getipnodebyname(name, AF_INET, AI_DEFAULT, &error_num);
if (hp != (struct hostent *)NULL) {
r = idn_decodename(IDN_DECODE_APP, hp->h_name, local_name,
sizeof(local_name));
if (r != idn_success) {
fprintf(stderr, gettext("idn_decodename failed.\n"));
exit(1);
}
printf(gettext("name: %s\n"), local_name);
}
...
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWidnl, SUNWidnd │
├─────────────────────────────┼─────────────────────────────┤
│CSI │Enabled │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Unsafe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOintro(3), libidnkit(3LIB), setlocale(3C), hosts(4), attributes(5), env‐
iron(5)
RFC 3490 Internationalizing Domain Names in Applications
(IDNA)
RFC 3491 Nameprep: A Stringprep Profile for Internationalized
Domain Names (IDN)
RFC 3492 Punycode: A Bootstring encoding of Unicode for
Internationalized Domain Names in Applications
(IDNA)
RFC 3454 Preparation of Internationalized Strings ("string‐
prep")
RFC 952 DoD Internet Host Table Specification
RFC 921 Domain Name System Implementation Schedule - Revised
STD 3, RFC 1122 Requirements for Internet Hosts -- Communication
Layers
STD 3, RFC 1123 Requirements for Internet Hosts -- Applications and
Support
Unicode Standard Annex #15: Unicode Normalization Forms, Version 3.2.0.
http://www.unicode.org
International Language Environments Guide (for this version of Solaris)
COPYRIGHT AND LICENSE
Copyright (c) 2000-2002 Japan Network Information Center. All rights
reserved.
By using this file, you agree to the terms and conditions set forth
bellow.
LICENSE TERMS AND CONDITIONS
The following License Terms and Conditions apply, unless a different
license is obtained from Japan Network Information Center ("JPNIC"), a
Japanese association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda,
Chiyoda-ku, Tokyo 101-0047, Japan.
1. Use, Modification and Redistribution (including distribution
of any modified or derived work) in source and/or binary
forms is permitted under this License Terms and Conditions.
2. Redistribution of source code must retain the copyright
notices as they appear in each source code file, this
License Terms and Conditions.
3. Redistribution in binary form must reproduce the Copyright
Notice, this License Terms and Conditions, in the documenta‐
tion and/or other materials provided with the distribution.
For the purposes of binary distribution the "Copyright
Notice" refers to the following language: "Copyright (c)
2000-2002 Japan Network Information Center. All rights
reserved."
4. The name of JPNIC may not be used to endorse or promote
products derived from this Software without specific prior
written approval of JPNIC.
5. Disclaimer/Limitation of Liability: THIS SOFTWARE IS PRO‐
VIDED BY JPNIC "AS IS" AND ANY EXPRESS OR IMPLIED WAR‐
RANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WAR‐
RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PUR‐
POSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PRO‐
CUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABIL‐
ITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES.
NOTES
The idn_nameinit() function checks internal system configuration files
such as /etc/idn/idn.conf and /etc/idn/idnalias.conf if they are in the
proper access mode and owership. If they are not in the proper access
mode or ownership, the function will not read and use the configura‐
tions defined in the files but use default values. In this case the
function will also issue a warning message such as:
idn_nameinit: warning: config file (/etc/idn/idn.conf) not in proper
access mode or ownership - the file ignored.
The proper access mode and the ownership are described in the package
prototype file of SUNWidnl. It is also recommended not to change the
system configuration files.
SunOS 5.10 15 Aug 2003 idn_decodename(3EXT)