path: root/contrib/idn/mdnkit/man/libmdn.3.in

.\" $Id: libmdn.3.in,v 1.1.2.1 2002/02/08 12:14:42 marka Exp $
.\"
.\" Copyright (c) 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) Japan Network Information Center.  All rights reserved."
.\" 
.\" 4. Neither the name of JPNIC may 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.
.\" 
.\" 6. Indemnification by Licensee
.\"    Any person or entities using and/or redistributing this Software under
.\"    this License Terms and Conditions shall defend indemnify and hold
.\"    harmless JPNIC from and against any and all judgements damages,
.\"    expenses, settlement liabilities, cost and other liabilities of any
.\"    kind as a result of use and redistribution of this Software or any
.\"    claim, suite, action, litigation or proceeding by any third party
.\"    arising out of or relates to this License Terms and Conditions.
.\" 
.\" 7. Governing Law, Jurisdiction and Venue
.\"    This License Terms and Conditions shall be governed by and and
.\"    construed in accordance with the law of Japan. Any person or entities
.\"    using and/or redistributing this Software under this License Terms and
.\"    Conditions hereby agrees and consent to the personal and exclusive
.\"    jurisdiction and venue of Tokyo District Court of Japan.
.\"
.TH libmdn 3 "Apr 23, 2001"
.\"
.SH NAME
libmdn \- Mulitilingual Domain Name Handling Library
.\"
.SH SYNOPSIS
.nf
#include <mdn/api.h>

mdn_result_t
\fBmdn_nameinit\fP(void)

mdn_result_t
\fBmdn_encodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen)

mdn_result_t
\fBmdn_decodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen)

char *
\fBmdn_result_tostring\fP(mdn_result_t\ result)

.\"
.SH OVERVIEW
The
.B libmdn
library supports various manipulations of multilingual domain names,
including:
.RS 2
.IP \- 2
encoding convesion
.IP \- 2
normalization
.RE
.PP
.B Libmdn
is designed according to IDNA framework where each application must do
necessary preparations for the multilingual domain names before passing them
to the resolver.
.PP
To help applications do the preparation, libmdn provides easy-to-use,
high-level interface for the work.
.PP
This manual describes only a small subset of the API that libmdn provides,
most important functions for application programmers.  For other API,
please refer to the mDNkit's specification document (which is not yet
available) or the libmdn's header files typically found under
`/usr/local/include/mdn/' on your system.
.\"
.SH DESCRIPTION
.PP
The
.B mdn_nameinit
function initializes the whole library, and reads the default
configuration file
.BR mdn.conf ,
which includes configuration parameters for multilingual domain name
preparation.
If
.B mdn_nameinit
is called more than once, the library initialization will take place
only at the first call while the configuration file will be (re)read
at every call.
.PP
If there are no errors,
.B mdn_nameinit
returns
.BR mdn_success .
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
.B mdn_encodename
or
.B mdn_decodename
is first called without prior calling of
.BR mdn_nameinit .
.\"
.PP
.B mdn_encodename
function performs normalization and encoding conversion on the 
multilingual domain name specified by
.IR from ,
and stores the result to
.IR to ,
whose length is specified by 
.IR tolen .
.I actions
is a bitwise-OR of the following flags, specifying which subprocesses in
the encoding process are to be employed.
.RS 2
.nf
.ft CW
#define MDN_LOCALCONV 0x0001 /* Local encoding <-> UTF-8 conversion */
#define MDN_IDNCONV   0x0002 /* UTF-8 <-> ACE conversion */
#define MDN_NAMEPREP  0x0004 /* NAMEPREP */
#define MDN_UNASCHECK 0x0008 /* Unassigned code point check */
#define MDN_DELIMMAP  0x0100 /* Delimiter mapping */
#define MDN_LOCALMAP  0x0200 /* Local mapping */
.ft R
.fi
.RE
.PP
Details of this encoding process can be found in the section ``NAME ENCODING''.
.PP
For ordinary application, the following macro is provided for the convenience.
.RS 2
.nf
.ft CW
#define MDN_ENCODE_APP \e
  (MDN_LOCALCONV|MDN_DELIMMAP|MDN_LOCALMAP|MDN_NAMEPREP|MDN_IDNCONV)
.ft R
.fi
.RE
.PP
.B mdn_decodename
function performs the reverse of
.BR mdn_encodename .
It converts the multilingual domain name given by
.IR from ,
which is represented in a special encoding called ACE,
to the application's local codeset and stores into
.IR to ,
whose length is specified by
.IR tolen .
.I actions
specifies which subprocesses in decoding process take place, as in
.BR mdn_encodename ,
except that only \f(CWMDN_IDNCONV\fP, \f(CWMDN_NAMEPREP\fP and
\f(CWMDN_LOCALCONV\fP are allowed.
Details of this decoding process can be found in the section ``NAME DECODING''.
.PP
For ordinary application, the following macro is provided for the convenience.
.RS 2
.nf
.ft CW
#define MDN_DECODE_APP    (MDN_IDNCONV|MDN_NAMEPREP|MDN_LOCALCONV)
.ft R
.fi
.RE
.PP
All of the functions above return error code of type
.BR mdn_result_t .
All codes other than
.B mdn_success
indicates some kind of failure.
.B mdn_result_tostring
function takes an error code
.I result
and returns a pointer to the corresponding message string.
.\"
.SH "NAME ENCODING"
Name encoding is a process that transforms the specified
multilingual domain name to a certain string suitable for name
resolution.
.BR libmdn 's
name encoding process consists of the following steps.
.IP "(1) Encoding conversion (local codeset to UCS)"
Convert the encoding of the given domain name to
Unicode/ISO10646 UTF-8 format string.
The source encoding must be one of the two encodings below:
.RS 2
.IP \- 2
The application's local encoding (codeset).
.IP \- 2
ACE specified by the configuration file.
.RE
The latter is suppored because name decoding process may produce
ACE strings when its attempt to convert to the local encoding fails.
See the section ``NAME DECODING'' for details.
.IP "(2) Local mapping"
Apply any locale/language-specific mapping.  This process is
further divided into two subprocesses:
.RS 2
.IP "(2-1) Delimiter mapping"
Map certain characters to the domain name delimiter (U+002E).
.IP "(2-2) Local mapping based on TLD"
Apply character mapping whose rule is determined by the TLD of the name.
.RE
.IP "(3) NAMEPREP"
Perform name preparation (NAMEPREP), which is a standard process for
normalizing multilingual domain names.  This process includes checking
of characters which are not allowed in multilingual domain names.
.IP "(4) Encoding conversion (UCS to ACE)"
Convert the NAMEPREPed name to a special encoding designed for representing
multilingual 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.
.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 mDNkit's configuration file,
.BR mdn.conf .
See mdn.conf(5) for details.
.PP
The libmdn API allows to skip some of these subprocesses.
For example step (1) can be skipped if you have names already in
UTF-8 format.
.\"
.SH "NAME DECODING"
Name decoding is a reverse process of the name encoding.
It transforms the specified
multilingual 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.
Name decoding doesn't perform local mapping.
Both name encoding and decoding do NAMEPREP, but decoding does
it to verfiy a name, while encoding does it to normalize a name.
.PP
.BR libmdn 's
name decoding process consists of the following steps.
.IP "(1) Encoding conversion (ACE to UCS)"
Convert the encoding of the given domain name
from a special one designed for representing
multilingual domain names (ACE) to Unicode/ISO10646 UTF-8.
.IP "(2) NAMEPREP check"
Perform name preparation (NAMEPREP) as also done in name encoding,
and compare the result of NAMEPREP and the given UCS name.
If the NAMEPREP is failed or the names are different, the given
name is considered as invalid domain name.
It contains a character which is never seen in a NAMEPREPed domain
name.
.IP "(3) Encoding conversion (UCS to local codeset)"
Convert the encoding of the name from UTF-8 to
the application's local codeset.
The local codeset is determined by the application's locale.
.br
However, it is possible that the conversion to the application's
local codeset fails because the name includes some characters
which don't have mappings to the local codeset.
In this case, libmdn tries instead to convert to ACE specified by
the configuration file.  
.PP
The configuration parameters for this process,
are also read from the configuration file
.BR mdn.conf .
.PP
The libmdn API allows to skip some of these subprocesses.
For example step (2) can be skipped if you want a name in
UTF-8 format.
.\"
.SH "RETURN VALUES"
Most of the
.B libmdn
API functions return values of type
.B mdn_result_t
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 mdn_success
Not an error.  The call succeeded.
.TP
.SB mdn_notfound
Specified information does not exist.
.TP
.SB mdn_invalid_encoding
The encoding of the specified string is invalid.
.TP
.SB mdn_invalid_syntax
There is a syntax error in the configuration file.
.TP
.SB mdn_invalid_name
The specified name is not valid.
.TP
.SB mdn_invalid_message
The specified DNS message is not valid.
.TP
.SB mdn_invalid_action
The specified action contains invalid flags.
.TP
.SB mdn_invalid_codepoint
The specified Unicode code point value is not valid.
.TP
.SB mdn_buffer_overflow
The specified buffer is too small to hold the result.
.TP
.SB mdn_noentry
The specified key does not exist in the hash table.
.TP
.SB mdn_nomemory
Memory allocation using malloc failed.
.TP
.SB mdn_nofile
The specified file could not be opened.
.TP
.SB mdn_nomapping
Some characters do not have the mapping to the target character set.
.TP
.SB mdn_context_required
Context information is required.
.TP
.SB mdn_prohibited
The specified string contains some prohibited characters.
.TP
.SB mdn_failure
Generic error which is not covered by the above codes.
.\"
.SH EXAMPLES
To get the address of a multilingual domain name in the application's
local codeset, use
.B mdn_encodename
to convert the name to the format suitable for passing to resolver functions.
.RS 4
.nf
.ft CW
mdn_result_t r;
char ace_name[256];
struct hostent *hp;

\&...
r = mdn_encodename(MDN_ENCODE_APP, name, ace_name,
                   sizeof(ace_name));
if (r != mdn_success) {
    fprintf(stderr, "mdn_encodename failed: %s\en",
            mdn_result_tostring(r));
    exit(1);
}

hp = gethostbyname(ace_name);
\&...
.ft R
.fi
.RE
.PP
To decode the multilingual domain name returned from a resolver function,
use
.BR mdn_decodename .
.RS 4
.nf
.ft CW
mdn_result_t r;
char local_name[256];
struct hostent *hp;

\&...
hp = gethostbyname(name);
r = mdn_decodename(MDN_DECODE_APP, hp->h_name, local_name,
                   sizeof(local_name));
if (r != mdn_success) {
    fprintf(stderr, "mdn_decodename failed: %s\en",
            mdn_result_tostring(r));
    exit(1);
}
printf("name: %s\en", local_name);
\&...
.ft R
.fi
.RE
.\"
.SH FILES
.I @sysconfdir@/mdn.conf
.\"
.SH "SEE ALSO"
mdn.conf(5)