diff options
Diffstat (limited to 'contrib/idn/idnkit-1.0-src/man')
| -rw-r--r-- | contrib/idn/idnkit-1.0-src/man/Makefile.in | 116 | ||||
| -rw-r--r-- | contrib/idn/idnkit-1.0-src/man/idn.conf.5.in | 312 | ||||
| -rw-r--r-- | contrib/idn/idnkit-1.0-src/man/libidnkit.3.in | 480 |
3 files changed, 908 insertions, 0 deletions
diff --git a/contrib/idn/idnkit-1.0-src/man/Makefile.in b/contrib/idn/idnkit-1.0-src/man/Makefile.in new file mode 100644 index 0000000..a85a793 --- /dev/null +++ b/contrib/idn/idnkit-1.0-src/man/Makefile.in @@ -0,0 +1,116 @@ +# $Id: Makefile.in,v 1.1.1.1 2003/06/04 00:27:14 marka Exp $ +# +# Copyright (c) 2000 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 documentation 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 PROVIDED BY JPNIC +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE +# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 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 LIABILITY, 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. + +top_builddir = .. + +srcdir = @srcdir@ +VPATH = @srcdir@ + +prefix = @prefix@ +exec_prefix = @exec_prefix@ + +sysconfdir = @sysconfdir@ +mandir = @mandir@ +man3dir = $(mandir)/man3 +man5dir = $(mandir)/man5 + +INSTALL = @INSTALL@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_DATA = @INSTALL_DATA@ +MKINSTALLDIRS = @top_srcdir@/mkinstalldirs +SHELL = @SHELL@ + +@LITEONLY_TRUE@all: libidnkitlite.3 idn.conf.5 idnrc.5 idnalias.conf.5 +@LITEONLY_FALSE@all: libidnkitlite.3 idn.conf.5 idnrc.5 idnalias.conf.5 libidnkit.3 + +libidnkit.3: libidnkit.3.in + sed 's%[@]sysconfdir[@]%$(sysconfdir)%' < $(srcdir)/libidnkit.3.in > $@ +libidnkitlite.3: libidnkit.3.in + sed 's%[@]sysconfdir[@]%$(sysconfdir)%' < $(srcdir)/libidnkit.3.in > $@ +idn.conf.5: idn.conf.5.in + sed 's%[@]sysconfdir[@]%$(sysconfdir)%' < $(srcdir)/idn.conf.5.in > $@ +idnrc.5: idn.conf.5.in + sed 's%[@]sysconfdir[@]%$(sysconfdir)%' < $(srcdir)/idn.conf.5.in > $@ +idnalias.conf.5: idn.conf.5.in + sed 's%[@]sysconfdir[@]%$(sysconfdir)%' < $(srcdir)/idn.conf.5.in > $@ + +@LITEONLY_TRUE@@COMPAT_TRUE@install: all install-common install-compat-common +@LITEONLY_FALSE@@COMPAT_TRUE@install: all install-common install-nolite install-compat-common install-compat-nolite +@LITEONLY_TRUE@@COMPAT_FALSE@install: all install-common +@LITEONLY_FALSE@@COMPAT_FALSE@install: all install-common install-nolite + +install-common: + $(MKINSTALLDIRS) $(DESTDIR)$(man3dir) + $(INSTALL_DATA) libidnkitlite.3 $(DESTDIR)$(man3dir)/libidnkitlite.3 + $(MKINSTALLDIRS) $(DESTDIR)$(man5dir) + $(INSTALL_DATA) idn.conf.5 $(DESTDIR)$(man5dir)/idn.conf.5 + $(INSTALL_DATA) idnrc.5 $(DESTDIR)$(man5dir)/idnrc.5 + $(INSTALL_DATA) idnalias.conf.5 $(DESTDIR)$(man5dir)/idnalias.conf.5 + +install-nolite: + $(MKINSTALLDIRS) $(DESTDIR)$(man3dir) + $(INSTALL_DATA) libidnkit.3 $(DESTDIR)$(man3dir)/libidnkit.3 + +install-compat-common: + src=$(DESTDIR)$(man3dir)/libidnkitlite.3; \ + dst=$(DESTDIR)$(man3dir)/libmdnlite.3; \ + rm -f $$dst; \ + ln $$src $$dst || cp $$src $$dst + src=$(DESTDIR)$(man5dir)/idn.conf.5; \ + dst=$(DESTDIR)$(man5dir)/mdn.conf.5; \ + rm -f $$dst; \ + ln $$src $$dst || cp $$src $$dst + +install-compat-nolite: + src=$(DESTDIR)$(man3dir)/libidnkit.3; \ + dst=$(DESTDIR)$(man3dir)/libmdn.3; \ + rm -f $$dst; \ + ln $$src $$dst || cp $$src $$dst + +clean: + rm -f idn.conf.5 idnrc.5 idnalias.conf.5 libidnkit.3 libidnkitlite.3 + rm -f *~ + +distclean: clean + rm -f Makefile + +test check: diff --git a/contrib/idn/idnkit-1.0-src/man/idn.conf.5.in b/contrib/idn/idnkit-1.0-src/man/idn.conf.5.in new file mode 100644 index 0000000..cbc2248 --- /dev/null +++ b/contrib/idn/idnkit-1.0-src/man/idn.conf.5.in @@ -0,0 +1,312 @@ +.\" $Id: idn.conf.5.in,v 1.1.1.1 2003/06/04 00:27:16 marka Exp $" +.\" +.\" Copyright (c) 2000,2001 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 documentation 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 PROVIDED BY JPNIC +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 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 LIABILITY, 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. +.\" +.TH idn.conf 5 "Mar 8, 2002" +.\" +.SH NAME +idn.conf, .idnrc, idnalias.conf \- configuration files for idnkit library +.\" +.SH SYNOPSIS +@sysconfdir@/idn.conf +.br +~/.idnrc +.br +@sysconfdir@/idnalias.conf +.\" +.SH DESCRIPTION +\fBidn.conf\fR and \fB.idnrc\fR are configuration files for idnkit +library which is a toolkit for handling internationalized domain names. +.PP +idnkit library tries to load the user's configuration file ~/.idnrc +first, and then tries the system configutation file +@sysconfdir@/idn.conf. +Note that idnkit library loads either, not both. +.PP +To use internationalized domain names in DNS or other protocols, they +must be converted to an appropriate format before further processing. +In idnkit, this conversion process is comprised of the following tasks. +.IP 1. 3 +Convert the given domain name in application's local codeset to Unicode, +and vice versa. +.IP 2. 3 +Map certain characters in the name to period character so that they are +treated as the domain name +delimiter (\fIdelimiter mapping\fR). +.IP 3. 3 +Map certain characters in the name to other characters or chracter sequences, +according to a mapping rule determined by its top level domain (TLD). +.IP 4. 3 +Perform NAMEPREP, which is a starndard name preparation process for +internationalized domain names. This process is composed of +the tree steps called mapping, normalization, prohibited character +checking and bidirectional string checking. +.IP 5. 3 +Convert the nameprepped name to IDN encoding, which is the standard encoding +for internationalized domain names (also known as ASCII-compatible encoding, +ACE), and vice versa. +.PP +The configuration file specifies the parameters for these tasks, such as: +.RS 2 +.IP \- 2 +the encoding of internationalized domain names (IDN encoding). +.IP \- 2 +NAMEPREP schemes. +.RE +.\" +.SH SYNTAX +The configuration file is a simple text files, and each line in the file +(other than comment lines, which begin with ``#'', and empty lines) +forms an entry of the following format: +.PP +.RS 4 +.nf +\fIkeyword\fP\ \fIvalue..\fP +.fi +.RE +\." +.SH "IDN-ENCODING ENTRY" +IDN encoding entry specifies the encoding name (codeset name) which +is used as the encoding of internationalized domain names. +.PP +The syntax of this entry is: +.PP +.RS 4 +.nf +\f(CWidn-encoding \fP\fIencoding\fP +.fi +.RE +.PP +\fIencoding\fP is the encoding name to be used, and any of the following +names can be specified. +.RS 2 +.IP "\(bu" 2 +``Punycode'' +.IP "\(bu" 2 +``UTF-8'' +.IP "\(bu" 2 +Codeset names which iconv_open() library function accepts. Please +consult iconv() documentation for the available codesets. +.IP "\(bu" 2 +Any alias names for the above, defined by the alias file. +(See section ``ENCODING-ALIAS-FILE'') +.RE +.PP +The standard encoding was determined as Punycode. +.\" +.SH "NAMEPREP ENTRY" +Nameprep entry specifies the version of NAMEPREP, which is a specification +of ``canonicalization'' process of internationalized domain name before +it is converted to the IDN encoding. +.PP +The syntax of this entry is: +.PP +.RS 4 +.nf +\f(CWnameprep \fP\fIversion\fP +.fi +.RE +.PP +\fIversion\fR is the version name of NAMEPREP specification, and currently +the following versions can be specified. +.RS 2 +.IP "\(bu" 2 +``RFC3491'' +.br +This version refers to RFC3491 ``rfc-3491.txt''. +.RE +.PP +The NAMEPREP process consists of the following 4 subprocesses. +.IP 1. 3 +mapping, which maps certain characters in a name to other characters, +possibly none. +.IP 2. 3 +normalization, which replaces character variants in a name to +a unique one. +.IP 3. 3 +prohibited character checking, which detects invalid characters in a name. +.IP 4. 3 +unassigned codepoint checking, which also invalid codepoints in a name. +.IP 5. 3 +bidirectional string checking, which detecs invalid string. +.\" +.SH "LOCAL-MAP ENTRY" +This entry specifies localized mapping phase before NAMEPREP takes place. +Different mapping rules can be specified for each TLD (top-level domain). +For example, you can have one mapping for ``.tw'' domain, and another for +``.jp'' domain. +.PP +The syntax of this entry is: +.PP +.RS 4 +.nf +\f(CWlocal-map \fItld\f(CW \fIscheme\fR [\fIscheme\fR..] +.fi +.RE +.PP +\fItld\fR specifies the TLD to which the mapping rule is to be applied, +and \fIscheme\fR specifies the mapping scheme, and currently available +schemes are: +.RS 2 +.TP 4 +\f(CWRFC3491\fP +Specify mapping defined by RFC3491. +.TP 4 +\f(CWfilemap:\fP\fIpathname\fP +Specify mapping defined by the file \fIpathname\fP. +See ``MAPFILE FORMAT'' for the format of this file. +.RE +.PP +There are two special \fItld\fRs for specifying the mapping rule for +local domain names (domain names without any dots in them), and the +default mapping rule. +If +\fItld\fR is ``-'', it matches domain names which do not contain any +dots. +If \fItld\fR is ``.'', it matches any domain names which don't match +to any other mapping rules specified by ``local-map'' entries. +.\" +.SH "MAPFILE FORMAT" +A mapfile defines a set of character mapping rules. It can define +unconditional one-character to N-character-sequence (N can be 0, 1 or more) +mappings. +.PP +A mapfile is a simple text file, and each line specifies a single mapping. +Each line is of the form: +.PP +.RS 4 +.nf +\fIsrc-codepoint\fR\f(CW; \fImapped-codepoint-seq\fR\f(CW;\fR +.fi +.RE +.PP +\fIsrc-codepoint\fR indicates source character of the mapping, and must +be a Unicode codepoint value in hexadecimal string. +\fImapped-codepoint-seq\fR is a sequence of characters which is the +outcome of the mapping, and must be a (possibly empty) list of Unicode +codepoint values in hexadecimal string, separated by spaces. +.PP +Lines which begin with ``#'' are treated as comments and ignored. +.PP +A sample mapfile is shown below. +.PP +.RS 4 +.nf +.ft CW +# map "A" to "a" +0041; 0061; +# map "#" to nothing +0023; ; +# map "@" to "at" +0040; 0061 0074; +.ft R +.fi +.RE +.\" +.SH "LOCAL CODESET" +\fBidn.conf\fR or \fB~/.idnrc\fR doesn't have an entry to specify the +local codeset, since it is determined from the application's current +locale information. +So each application can use different local codeset. +.PP +Although idnkit tries hard to find out the local codeset, sometimes it +fails. For example, there are applications which use non-ASCII codeset +but work in C locale. In this case, you can specify the application's +local codeset by an environment variable ``\fBIDN_LOCAL_CODESET\fR''. +Just set the codeset name (or its alias name) to the variable, and +idnkit will use the codeset as the local one, regardless of the locale +setting. +.\" +.SH "ENCODING-ALIAS-FILE" +Encoding alias file specifies codeset name aliases. It is located on +@sysconfdir@/idnalias.conf and always loaded automatically as idn.conf +and .idnrc. The aliases in this file can be used just as the real names. +.PP +The alias file is a simple text file, consisting of lines of the form: +.PP +.RS 4 +.nf +\fIalias-name\fP\ \fIname\fP +.fi +.RE +.PP +\fIalias-name\fR is the alias name to be defined, and \fIname\fR is +the real name or another alias name. +.\" +.SH "SAMPLE CONFIGURATION" +The following shows a sample configuration file. +.PP +.RS 4 +.ft CW +.nf +# +# a sample configuration. +# + +# Use Punycode as the IDN encoding. +idn-encoding Punycode + +# Use RFC3491 as NAMEPREP. +nameprep RFC3491 + +# Perform Japanese-specific mapping for .jp domain. +# assuming /usr/local/lib/idnkit/jp-map contains the mapping. +local-map .jp filemap:/usr/local/lib/idnkit/jp-map +.fi +.ft R +.RE +.\" +.SH FILES +.I @sysconfdir@/idn.conf +.br +.I ~/.idnrc +.br +.I @sysconfdir@/idnalias.conf +.br +.I @sysconfdir@/idn.conf.sample +\- sample configuration with comments +.br +.I @sysconfdir@/idnalias.conf.sample +\- sample alias file +.\" +.SH "SEE ALSO" +iconv(3) diff --git a/contrib/idn/idnkit-1.0-src/man/libidnkit.3.in b/contrib/idn/idnkit-1.0-src/man/libidnkit.3.in new file mode 100644 index 0000000..12bca54 --- /dev/null +++ b/contrib/idn/idnkit-1.0-src/man/libidnkit.3.in @@ -0,0 +1,480 @@ +.\" $Id: libidnkit.3.in,v 1.1.1.1 2003/06/04 00:27:15 marka Exp $ +.\" +.\" Copyright (c) 2001,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 documentation 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 PROVIDED BY JPNIC +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +.\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 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 LIABILITY, 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. +.\" +.TH libidnkit 3 "Mar 11, 2002" +.\" +.SH NAME +libidnkit, libidnkitlite \- Internationalized Domain Name Handling Libraries +.\" +.SH SYNOPSIS +.nf +#include <idn/api.h> + +idn_result_t +\fBidn_nameinit\fP(int\ load_file) + +idn_result_t +\fBidn_encodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen) + +idn_result_t +\fBidn_decodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen) + +idn_result_t +\fBidn_decodename2\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen, + const\ char\ *auxencoding) + +idn_result_t +\fBidn_enable\fP(int\ on_off) + +#include <idn/result.h> + +char * +\fBidn_result_tostring\fP(idn_result_t\ result) + +.\" +.SH OVERVIEW +The +\fBlibidnkit\fR and \fBlibidnkitlite\fR libraries support various +manipulations of internationalized domain names, including: +.RS 2 +.IP \- 2 +encoding convesion +.IP \- 2 +name preparation +.RE +.PP +They are designed according to IDNA framework where each application must +do necessary preparations for the internationalized domain names before +passing them to the resolver. +.PP +To help applications do the preparation, the libraries provide easy-to-use, +high-level interface for the work. +.PP +Both libraries provide almost the same API. +The difference between them is that \fBlibidnkit\fR internally uses +\fIiconv\fR function to provide encoding conversion from UTF-8 to the +local encoding +(such as iso-8859-1, usually determined by the current locale), and vise +versa. +\fBlibidnkitlite\fR is lightweight version of libidnkit. +It assumes local encoding is UTF-8 so that it never uses \fIiconv\fR. +.PP +This manual describes only a small subset of the API that the libraries +provide, most important functions for application programmers. +For other API, please refer to the idnkit's specification document +(which is not yet available) or the header files typically found under +`/usr/local/include/idn/' on your system. +.\" +.SH DESCRIPTION +.PP +The \fBidn_nameinit\fR function initializes the library. +It also sets default configuration if \fIload_file\fR is 0, otherwise +it tries to read a configuration file. +If \fBidn_nameinit\fR 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. +.PP +If there are no errors, \fBidn_nameinit\fR returns \fBidn_success\fR. +Otherwise, the returned value indicates the cause of the error. +See the section ``RETURN VALUES'' below for the error codes. +.PP +Usually you don't have to call this function explicitly because +it is implicitly called when \fBidn_encodename\fR or \fBidn_decodename\fR +is first called without prior calling of \fBidn_nameinit\fR. +In such case, initialization without the configuration file +takes place. +.\" +.PP +\fBidn_encodename\fR function performs name preparation and encoding +conversion on the internationalized domain name specified by \fIfrom\fR, +and stores the result to \fIto\fR, whose length is specified by +\fItolen\fR. +\fIactions\fR is a bitwise-OR of the following macros, specifying which +subprocesses in the encoding process are to be employed. +.RS 2 +.nf +.ft CW +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 +.ft R +.fi +.RE +.PP +Details of this encoding process can be found in the section ``NAME ENCODING''. +.PP +For convenience, also \fBIDN_ENCODE_QUERY\fR, \fBIDN_ENCODE_APP\fR +and \fBIDN_ENCODE_STORED\fR macros are provided. +\fBIDN_ENCODE_QUERY\fR is used to encode a ``query string'' +(see the IDNA specification). +It is equal to +.RS 4 +.nf +.ft CW +(IDN_LOCALCONV | IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP + | IDN_IDNCONV | IDN_LENCHECK) +.ft R +.fi +.RE +.PP +if you are using \fBlibidnkit\fR, and equal to +.RS 4 +.nf +.ft CW +(IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP | IDN_IDNCONV + | IDN_LENCHECK) +.ft R +.fi +.RE +.PP +if you are using \fBlibidnkitlite\fR. +.PP +\fBIDN_ENCODE_APP\fR is used for ordinary application to encode a +domain name. +It performs \fBIDN_ASCCHECK\fR in addition with \fBIDN_ENCODE_QUERY\fR. +\fBIDN_ENCODE_STORED\fR is used to encode a ``stored string'' +(see the IDNA specification). +It performs \fBIDN_ENCODE_APP\fR plus \fBIDN_UNASCHECK\fR. +.PP +\fBidn_decodename\fR function performs the reverse of \fBidn_encodename\fR. +It converts the internationalized domain name given by \fIfrom\fR, +which is represented in a special encoding called ACE, +to the application's local codeset and stores into \fIto\fR, +whose length is specified by \fItolen\fR. +As in \fBidn_encodename\fR, \fIactions\fR is a bitwise-OR of the following +macros. +.RS 2 +.nf +.ft CW +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 +.ft R +.fi +.RE +.PP +Details of this decoding process can be found in the section ``NAME DECODING''. +.PP +For convenience, also \fBIDN_DECODE_QUERY\fR, \fBIDN_DECODE_APP\fR +and \fBIDN_DECODE_STORED\fR macros are provided. +\fBIDN_DECODE_QUERY\fR is used to decode a ``qeury string'' +(see the IDNA specification). +It is equal to +.RS 4 +.nf +.ft CW +(IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK + | IDN_LOCALCONV) +.ft R +.fi +.RE +.PP +if you are using \fBlibidnkit\fR, and equal to +.RS 4 +.nf +.ft CW +(IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK) +.ft R +.fi +.RE +.PP +if you are using \fBlibidnkitlite\fR. +.PP +\fBIDN_DECODE_APP\fR is used for ordinary application to decode a +domain name. +It performs \fBIDN_ASCCHECK\fR in addition with \fBIDN_DECODE_QUERY\fR. +\fBIDN_DECODE_STORED\fR is used to decode a ``stored string'' +(see the IDNA specification). +It performs \fBIDN_DECODE_APP\fR plus \fBIDN_UNASCHECK\fR. +.PP +\fBidn_decodename2\fR function provides the same functionality as +\fBidn_decodename\fR except that character encoding of \fIfrom\fR is +supposed to be \fIauxencoding\fR. +If IDN encoding is Punycode and \fIauxencoding\fR is ISO 8859-2 +for example, it is assumed that the Punycode string stored in +\fIfrom\fR is written in ISO 8859-2. +.PP +In the IDN decode procedure, \fBIDN_NAMEPREP\fR is done before +\fBIDN_IDNCONV\fR, and some non-ASCII characters are converted to +ASCII characters as the result of \fBIDN_NAMEPREP\fR. +Therefore, ACE string given by \fBfrom\fR may contains those non-ASCII +characters. +That is the reason \fBdocode_name2\fR exists. +.PP +All of the functions above return error code of type \fBidn_result_t\fR. +All codes other than \fBidn_success\fR indicates some kind of failure. +\fBidn_result_tostring\fR function takes an error code \fIresult\fR +and returns a pointer to the corresponding message string. +.\" +.SH "NAME ENCODING" +Name encoding is a process that transforms the specified +internationalized domain name to a certain string suitable for name +resolution. +For each label in a given domain name, the encoding processor performs: +.\" +.IP "(1) Convert to UTF-8 (IDN_LOCALCONV)" +Convert the encoding of the given domain name from application's local +encoding (e.g. ISO-8859-1) to UTF-8. +Note that \fBlibidnkitlite\fR doesn't support this step. +.\" +.IP "(2) 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). +.\" +.IP "(3) Local mapping (IDN_LOCALMAP)" +Apply character mapping whose rule is determined by the TLD of the name. +.\" +.IP "(4) NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)" +Perform name preparation (NAMEPREP), which is a standard process for +name canonicalizaion of internationalized domain names. +.br +NAMEPREP consists of 5 steps: +mapping, normalization, prohibited character check, bidirectional +text check and unassigned codepoint check. +The first four steps are done by IDN_NAMEPREP, and the last step is +done by IDN_UNASCHECK. +.\" +.IP "(5) ASCII range character check (IDN_ASCCHECK)" +Checks if the domain name contains non-LDH ASCII character (not +alpha-numeric or hyphen), or it begins or end with hyphen. +.\" +.IP "(6) Convert to ACE (IDN_IDNCONV)" +Convert the NAMEPREPed name to a special encoding designed for representing +internationalized domain names. +.br +The encoding is also known as ACE (ASCII Compatible Encoding) since +a string in the encoding is just like a traditional ASCII domain name +consisting of only letters, numbers and hyphens. +.\" +.IP "(7) Label length check (IDN_LENCHECK)" +For each label, check the number of characters in it. +It must be in the range 1 to 63. +.PP +There are many configuration parameters for this process, such as the +ACE or the local mapping rules. These parameters are read from the +default idnkit's configuration file, \fBidn.conf\fR. +See idn.conf(5) for details. +.\" +.SH "NAME DECODING" +Name decoding is a reverse process of the name encoding. +It transforms the specified +internationalized domain name in a special encoding suitable for name +resolution to the normal name string in the application's current codeset. +However, name encoding and name decoding are not symmetric. +.PP +For each label in a given domain name, the decoding processor performs: +.\" +.IP "(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). +.\" +.IP "(2) NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)" +Perform name preparation (NAMEPREP), which is a standard process for +name canonicalizaion of internationalized domain names. +.\" +.IP "(3) Convert to UTF-8 (IDN_IDNCONV)" +Convert the encoding of the given domain name from ACE to UTF-8. +.\" +.IP "(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, also they are +done in the encoding processes. +.\" +.IP "(5) Convert to local encoding" +Convert the result of (3) from UTF-8 to the application's local +encoding (e.g. ISO-8859-1). +Note that \fBlibidnkitlite\fR doesn't support this step. +.PP +If prohibited character check, unassigned codepoint check or +bidirectional text check at step (2) is failed, or round trip check +at step (4) is failed, the original input label is returned. +.PP +The configuration parameters for this process, +are also read from the configuration file \fBidn.conf\fR. +.\" +.SH "IDN_DISABLE" +If the \fBIDN_DISABLE\fR environ variable is defined at run-time, +the libraries disable internationalized domain name support, by default. +In this case, \fBidn_encodename\fR and \fBidn_decodename\fR don't +encode/decode an input name, but instead they simply ouput a copy +of the input name as the result of encoding/decoding. +.PP +If your application should always enable mulitilingual domain name +support regardless of definition of \fBIDN_DISABLE\fR, call +.RS 4 +.nf +.ft CW +idn_enable(1) +.ft R +.fi +.RE +.PP +before performing encoding/decoding. +.\" +.SH "RETURN VALUES" +Most of the API functions return values of type \fBidn_result_t\fR in +order to indicate the status of the call. + +The following is a complete list of the status codes. Note that some +of them are never returned by the functions described in this manual. +.TP 15 +.SB idn_success +Not an error. The call succeeded. +.TP +.SB idn_notfound +Specified information does not exist. +.TP +.SB idn_invalid_encoding +The encoding of the specified string is invalid. +.TP +.SB idn_invalid_syntax +There is a syntax error in the configuration file. +.TP +.SB idn_invalid_name +The specified name is not valid. +.TP +.SB idn_invalid_message +The specified DNS message is not valid. +.TP +.SB idn_invalid_action +The specified action contains invalid flags. +.TP +.SB idn_invalid_codepoint +The specified Unicode code point value is not valid. +.TP +.SB idn_invalid_length +The number of characters in an ACE label is not in the range 1 to 63. +.TP +.SB idn_buffer_overflow +The specified buffer is too small to hold the result. +.TP +.SB idn_noentry +The specified key does not exist in the hash table. +.TP +.SB idn_nomemory +Memory allocation using malloc failed. +.TP +.SB idn_nofile +The specified file could not be opened. +.TP +.SB idn_nomapping +Some characters do not have the mapping to the target character set. +.TP +.SB idn_context_required +Context information is required. +.TP +.SB idn_prohibited +The specified string contains some prohibited characters. +.TP +.SB idn_failure +Generic error which is not covered by the above codes. +.\" +.SH EXAMPLES +To get the address of a internationalized domain name in the application's +local codeset, use \fBidn_encodename\fR to convert the name to the format +suitable for passing to resolver functions. +.RS 4 +.nf +.ft CW +idn_result_t r; +char ace_name[256]; +struct hostent *hp; + +\&... +r = idn_encodename(IDN_ENCODE_APP, name, ace_name, + sizeof(ace_name)); +if (r != idn_success) { + fprintf(stderr, "idn_encodename failed: %s\en", + idn_result_tostring(r)); + exit(1); +} + +hp = gethostbyname(ace_name); +\&... +.ft R +.fi +.RE +.PP +To decode the internationalized domain name returned from a resolver function, +use \fBidn_decodename\fR. +.RS 4 +.nf +.ft CW +idn_result_t r; +char local_name[256]; +struct hostent *hp; + +\&... +hp = gethostbyname(name); +r = idn_decodename(IDN_DECODE_APP, hp->h_name, local_name, + sizeof(local_name)); +if (r != idn_success) { + fprintf(stderr, "idn_decodename failed: %s\en", + idn_result_tostring(r)); + exit(1); +} +printf("name: %s\en", local_name); +\&... +.ft R +.fi +.RE +.\" +.SH "SEE ALSO" +idn.conf(5) |