diff options
author | Martin Nagy <mnagy@redhat.com> | 2009-02-11 20:37:59 +0100 |
---|---|---|
committer | Martin Nagy <mnagy@redhat.com> | 2009-02-11 20:37:59 +0100 |
commit | f50ae72ec3417cae55dd4e085991c01af9fdc5f1 (patch) | |
tree | 0e36c9a3320f6d068df93d3ff6d84b821d23db40 /contrib/idn/idnkit-1.0-src/man/libidnkit.3.in | |
download | bind_dynamic-f50ae72ec3417cae55dd4e085991c01af9fdc5f1.tar.gz bind_dynamic-f50ae72ec3417cae55dd4e085991c01af9fdc5f1.tar.xz bind_dynamic-f50ae72ec3417cae55dd4e085991c01af9fdc5f1.zip |
Initial commitstart
Diffstat (limited to 'contrib/idn/idnkit-1.0-src/man/libidnkit.3.in')
-rw-r--r-- | contrib/idn/idnkit-1.0-src/man/libidnkit.3.in | 480 |
1 files changed, 480 insertions, 0 deletions
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) |