libidnkit.3.in

package of develop dns

.\" $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.