| blob | 08157de5eee1a4ebd35f60949688163d2cfedb45 |
1 .\" Id: libidnkit.3.in,v 1.1 2003/06/04 00:27:15 marka Exp
2 .\"
3 .\" Copyright (c) 2001,2002 Japan Network Information Center.
4 .\" All rights reserved.
5 .\"
6 .\" By using this file, you agree to the terms and conditions set forth bellow.
7 .\"
8 .\" LICENSE TERMS AND CONDITIONS
9 .\"
10 .\" The following License Terms and Conditions apply, unless a different
11 .\" license is obtained from Japan Network Information Center ("JPNIC"),
12 .\" a Japanese association, Kokusai-Kougyou-Kanda Bldg 6F, 2-3-4 Uchi-Kanda,
13 .\" Chiyoda-ku, Tokyo 101-0047, Japan.
14 .\"
15 .\" 1. Use, Modification and Redistribution (including distribution of any
16 .\" modified or derived work) in source and/or binary forms is permitted
17 .\" under this License Terms and Conditions.
18 .\"
19 .\" 2. Redistribution of source code must retain the copyright notices as they
20 .\" appear in each source code file, this License Terms and Conditions.
21 .\"
22 .\" 3. Redistribution in binary form must reproduce the Copyright Notice,
23 .\" this License Terms and Conditions, in the documentation and/or other
24 .\" materials provided with the distribution. For the purposes of binary
25 .\" distribution the "Copyright Notice" refers to the following language:
26 .\" "Copyright (c) 2000-2002 Japan Network Information Center. All rights reserved."
27 .\"
28 .\" 4. The name of JPNIC may not be used to endorse or promote products
29 .\" derived from this Software without specific prior written approval of
30 .\" JPNIC.
31 .\"
32 .\" 5. Disclaimer/Limitation of Liability: THIS SOFTWARE IS PROVIDED BY JPNIC
33 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
34 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
35 .\" PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JPNIC BE LIABLE
36 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
37 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
38 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
39 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
40 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
41 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
42 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
43 .\"
44 .TH libidnkit 3 "Mar 11, 2002"
45 .\"
46 .SH NAME
47 libidnkit, libidnkitlite \- Internationalized Domain Name Handling Libraries
48 .\"
49 .SH SYNOPSIS
50 .nf
51 #include <idn/api.h>
53 idn_result_t
54 \fBidn_nameinit\fP(int\ load_file)
56 idn_result_t
57 \fBidn_encodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen)
59 idn_result_t
60 \fBidn_decodename\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen)
62 idn_result_t
63 \fBidn_decodename2\fP(int\ actions,\ const\ char\ *from,\ char\ *to,\ size_t\ tolen,
64 const\ char\ *auxencoding)
66 idn_result_t
67 \fBidn_enable\fP(int\ on_off)
69 #include <idn/result.h>
71 char *
72 \fBidn_result_tostring\fP(idn_result_t\ result)
74 .\"
75 .SH OVERVIEW
76 The
77 \fBlibidnkit\fR and \fBlibidnkitlite\fR libraries support various
78 manipulations of internationalized domain names, including:
79 .RS 2
80 .IP \- 2
81 encoding convesion
82 .IP \- 2
83 name preparation
84 .RE
85 .PP
86 They are designed according to IDNA framework where each application must
87 do necessary preparations for the internationalized domain names before
88 passing them to the resolver.
89 .PP
90 To help applications do the preparation, the libraries provide easy-to-use,
91 high-level interface for the work.
92 .PP
93 Both libraries provide almost the same API.
94 The difference between them is that \fBlibidnkit\fR internally uses
95 \fIiconv\fR function to provide encoding conversion from UTF-8 to the
96 local encoding
97 (such as iso-8859-1, usually determined by the current locale), and vise
98 versa.
99 \fBlibidnkitlite\fR is lightweight version of libidnkit.
100 It assumes local encoding is UTF-8 so that it never uses \fIiconv\fR.
101 .PP
102 This manual describes only a small subset of the API that the libraries
103 provide, most important functions for application programmers.
104 For other API, please refer to the idnkit's specification document
105 (which is not yet available) or the header files typically found under
106 `/usr/local/include/idn/' on your system.
107 .\"
108 .SH DESCRIPTION
109 .PP
110 The \fBidn_nameinit\fR function initializes the library.
111 It also sets default configuration if \fIload_file\fR is 0, otherwise
112 it tries to read a configuration file.
113 If \fBidn_nameinit\fR is called more than once, the library initialization
114 will take place only at the first call while the actual configuration
115 procedure will occur at every call.
116 .PP
117 If there are no errors, \fBidn_nameinit\fR returns \fBidn_success\fR.
118 Otherwise, the returned value indicates the cause of the error.
119 See the section ``RETURN VALUES'' below for the error codes.
120 .PP
121 Usually you don't have to call this function explicitly because
122 it is implicitly called when \fBidn_encodename\fR or \fBidn_decodename\fR
123 is first called without prior calling of \fBidn_nameinit\fR.
124 In such case, initialization without the configuration file
125 takes place.
126 .\"
127 .PP
128 \fBidn_encodename\fR function performs name preparation and encoding
129 conversion on the internationalized domain name specified by \fIfrom\fR,
130 and stores the result to \fIto\fR, whose length is specified by
131 \fItolen\fR.
132 \fIactions\fR is a bitwise-OR of the following macros, specifying which
133 subprocesses in the encoding process are to be employed.
134 .RS 2
135 .nf
136 .ft CW
137 IDN_LOCALCONV Local encoding to UTF-8 conversion
138 IDN_DELIMMAP Delimiter mapping
139 IDN_LOCALMAP Local mapping
140 IDN_NAMEPREP NAMEPREP mapping, normalization,
141 prohibited character check and bidirectional
142 string check
143 IDN_UNASCHECK NAMEPREP unassigned codepoint check
144 IDN_ASCCHECK ASCII range character check
145 IDN_IDNCONV UTF-8 to IDN encoding conversion
146 IDN_LENCHECK Label length check
147 .ft R
148 .fi
149 .RE
150 .PP
151 Details of this encoding process can be found in the section ``NAME ENCODING''.
152 .PP
153 For convenience, also \fBIDN_ENCODE_QUERY\fR, \fBIDN_ENCODE_APP\fR
154 and \fBIDN_ENCODE_STORED\fR macros are provided.
155 \fBIDN_ENCODE_QUERY\fR is used to encode a ``query string''
156 (see the IDNA specification).
157 It is equal to
158 .RS 4
159 .nf
160 .ft CW
161 (IDN_LOCALCONV | IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP
162 | IDN_IDNCONV | IDN_LENCHECK)
163 .ft R
164 .fi
165 .RE
166 .PP
167 if you are using \fBlibidnkit\fR, and equal to
168 .RS 4
169 .nf
170 .ft CW
171 (IDN_DELIMMAP | IDN_LOCALMAP | IDN_NAMEPREP | IDN_IDNCONV
172 | IDN_LENCHECK)
173 .ft R
174 .fi
175 .RE
176 .PP
177 if you are using \fBlibidnkitlite\fR.
178 .PP
179 \fBIDN_ENCODE_APP\fR is used for ordinary application to encode a
180 domain name.
181 It performs \fBIDN_ASCCHECK\fR in addition with \fBIDN_ENCODE_QUERY\fR.
182 \fBIDN_ENCODE_STORED\fR is used to encode a ``stored string''
183 (see the IDNA specification).
184 It performs \fBIDN_ENCODE_APP\fR plus \fBIDN_UNASCHECK\fR.
185 .PP
186 \fBidn_decodename\fR function performs the reverse of \fBidn_encodename\fR.
187 It converts the internationalized domain name given by \fIfrom\fR,
188 which is represented in a special encoding called ACE,
189 to the application's local codeset and stores into \fIto\fR,
190 whose length is specified by \fItolen\fR.
191 As in \fBidn_encodename\fR, \fIactions\fR is a bitwise-OR of the following
192 macros.
193 .RS 2
194 .nf
195 .ft CW
196 IDN_DELIMMAP Delimiter mapping
197 IDN_NAMEPREP NAMEPREP mapping, normalization,
198 prohibited character check and bidirectional
199 string check
200 IDN_UNASCHECK NAMEPREP unassigned codepoint check
201 IDN_IDNCONV UTF-8 to IDN encoding conversion
202 IDN_RTCHECK Round trip check
203 IDN_ASCCHECK ASCII range character check
204 IDN_LOCALCONV Local encoding to UTF-8 conversion
205 .ft R
206 .fi
207 .RE
208 .PP
209 Details of this decoding process can be found in the section ``NAME DECODING''.
210 .PP
211 For convenience, also \fBIDN_DECODE_QUERY\fR, \fBIDN_DECODE_APP\fR
212 and \fBIDN_DECODE_STORED\fR macros are provided.
213 \fBIDN_DECODE_QUERY\fR is used to decode a ``qeury string''
214 (see the IDNA specification).
215 It is equal to
216 .RS 4
217 .nf
218 .ft CW
219 (IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK
220 | IDN_LOCALCONV)
221 .ft R
222 .fi
223 .RE
224 .PP
225 if you are using \fBlibidnkit\fR, and equal to
226 .RS 4
227 .nf
228 .ft CW
229 (IDN_DELIMMAP | IDN_NAMEPREP | IDN_IDNCONV | IDN_RTCHECK)
230 .ft R
231 .fi
232 .RE
233 .PP
234 if you are using \fBlibidnkitlite\fR.
235 .PP
236 \fBIDN_DECODE_APP\fR is used for ordinary application to decode a
237 domain name.
238 It performs \fBIDN_ASCCHECK\fR in addition with \fBIDN_DECODE_QUERY\fR.
239 \fBIDN_DECODE_STORED\fR is used to decode a ``stored string''
240 (see the IDNA specification).
241 It performs \fBIDN_DECODE_APP\fR plus \fBIDN_UNASCHECK\fR.
242 .PP
243 \fBidn_decodename2\fR function provides the same functionality as
244 \fBidn_decodename\fR except that character encoding of \fIfrom\fR is
245 supposed to be \fIauxencoding\fR.
246 If IDN encoding is Punycode and \fIauxencoding\fR is ISO 8859-2
247 for example, it is assumed that the Punycode string stored in
248 \fIfrom\fR is written in ISO 8859-2.
249 .PP
250 In the IDN decode procedure, \fBIDN_NAMEPREP\fR is done before
251 \fBIDN_IDNCONV\fR, and some non-ASCII characters are converted to
252 ASCII characters as the result of \fBIDN_NAMEPREP\fR.
253 Therefore, ACE string given by \fBfrom\fR may contains those non-ASCII
254 characters.
255 That is the reason \fBdocode_name2\fR exists.
256 .PP
257 All of the functions above return error code of type \fBidn_result_t\fR.
258 All codes other than \fBidn_success\fR indicates some kind of failure.
259 \fBidn_result_tostring\fR function takes an error code \fIresult\fR
260 and returns a pointer to the corresponding message string.
261 .\"
262 .SH "NAME ENCODING"
263 Name encoding is a process that transforms the specified
264 internationalized domain name to a certain string suitable for name
265 resolution.
266 For each label in a given domain name, the encoding processor performs:
267 .\"
268 .IP "(1) Convert to UTF-8 (IDN_LOCALCONV)"
269 Convert the encoding of the given domain name from application's local
270 encoding (e.g. ISO-8859-1) to UTF-8.
271 Note that \fBlibidnkitlite\fR doesn't support this step.
272 .\"
273 .IP "(2) Delimiter mapping (IDN_DELIMMAP)"
274 Map domain name delimiters to `.' (U+002E).
275 The recoginzed delimiters are: U+3002 (ideographic full stop),
276 U+FF0E (fullwidth full stop), U+FF61 (halfwidth ideographic full stop).
277 .\"
278 .IP "(3) Local mapping (IDN_LOCALMAP)"
279 Apply character mapping whose rule is determined by the TLD of the name.
280 .\"
281 .IP "(4) NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)"
282 Perform name preparation (NAMEPREP), which is a standard process for
283 name canonicalizaion of internationalized domain names.
284 .br
285 NAMEPREP consists of 5 steps:
286 mapping, normalization, prohibited character check, bidirectional
287 text check and unassigned codepoint check.
288 The first four steps are done by IDN_NAMEPREP, and the last step is
289 done by IDN_UNASCHECK.
290 .\"
291 .IP "(5) ASCII range character check (IDN_ASCCHECK)"
292 Checks if the domain name contains non-LDH ASCII character (not
293 alpha-numeric or hyphen), or it begins or end with hyphen.
294 .\"
295 .IP "(6) Convert to ACE (IDN_IDNCONV)"
296 Convert the NAMEPREPed name to a special encoding designed for representing
297 internationalized domain names.
298 .br
299 The encoding is also known as ACE (ASCII Compatible Encoding) since
300 a string in the encoding is just like a traditional ASCII domain name
301 consisting of only letters, numbers and hyphens.
302 .\"
303 .IP "(7) Label length check (IDN_LENCHECK)"
304 For each label, check the number of characters in it.
305 It must be in the range 1 to 63.
306 .PP
307 There are many configuration parameters for this process, such as the
308 ACE or the local mapping rules. These parameters are read from the
309 default idnkit's configuration file, \fBidn.conf\fR.
310 See idn.conf(5) for details.
311 .\"
312 .SH "NAME DECODING"
313 Name decoding is a reverse process of the name encoding.
314 It transforms the specified
315 internationalized domain name in a special encoding suitable for name
316 resolution to the normal name string in the application's current codeset.
317 However, name encoding and name decoding are not symmetric.
318 .PP
319 For each label in a given domain name, the decoding processor performs:
320 .\"
321 .IP "(1) Delimiter mapping (IDN_DELIMMAP)"
322 Map domain name delimiters to `.' (U+002E).
323 The recoginzed delimiters are: U+3002 (ideographic full stop),
324 U+FF0E (fullwidth full stop), U+FF61 (halfwidth ideographic full stop).
325 .\"
326 .IP "(2) NAMEPREP (IDN_NAMEPREP, IDN_UNASCHECK)"
327 Perform name preparation (NAMEPREP), which is a standard process for
328 name canonicalizaion of internationalized domain names.
329 .\"
330 .IP "(3) Convert to UTF-8 (IDN_IDNCONV)"
331 Convert the encoding of the given domain name from ACE to UTF-8.
332 .\"
333 .IP "(4) Round trip check (IDN_RTCHECK)"
334 Encode the result of (3) using the ``NAME ENCODING'' scheme, and then
335 compare it with the result of the step (2).
336 If they are different, the check is failed.
337 If IDN_UNASCHECK, IDN_ASCCHECK or both are specified, also they are
338 done in the encoding processes.
339 .\"
340 .IP "(5) Convert to local encoding"
341 Convert the result of (3) from UTF-8 to the application's local
342 encoding (e.g. ISO-8859-1).
343 Note that \fBlibidnkitlite\fR doesn't support this step.
344 .PP
345 If prohibited character check, unassigned codepoint check or
346 bidirectional text check at step (2) is failed, or round trip check
347 at step (4) is failed, the original input label is returned.
348 .PP
349 The configuration parameters for this process,
350 are also read from the configuration file \fBidn.conf\fR.
351 .\"
352 .SH "IDN_DISABLE"
353 If the \fBIDN_DISABLE\fR environ variable is defined at run-time,
354 the libraries disable internationalized domain name support, by default.
355 In this case, \fBidn_encodename\fR and \fBidn_decodename\fR don't
356 encode/decode an input name, but instead they simply ouput a copy
357 of the input name as the result of encoding/decoding.
358 .PP
359 If your application should always enable mulitilingual domain name
360 support regardless of definition of \fBIDN_DISABLE\fR, call
361 .RS 4
362 .nf
363 .ft CW
364 idn_enable(1)
365 .ft R
366 .fi
367 .RE
368 .PP
369 before performing encoding/decoding.
370 .\"
371 .SH "RETURN VALUES"
372 Most of the API functions return values of type \fBidn_result_t\fR in
373 order to indicate the status of the call.
375 The following is a complete list of the status codes. Note that some
376 of them are never returned by the functions described in this manual.
377 .TP 15
378 .SB idn_success
379 Not an error. The call succeeded.
380 .TP
381 .SB idn_notfound
382 Specified information does not exist.
383 .TP
384 .SB idn_invalid_encoding
385 The encoding of the specified string is invalid.
386 .TP
387 .SB idn_invalid_syntax
388 There is a syntax error in the configuration file.
389 .TP
390 .SB idn_invalid_name
391 The specified name is not valid.
392 .TP
393 .SB idn_invalid_message
394 The specified DNS message is not valid.
395 .TP
396 .SB idn_invalid_action
397 The specified action contains invalid flags.
398 .TP
399 .SB idn_invalid_codepoint
400 The specified Unicode code point value is not valid.
401 .TP
402 .SB idn_invalid_length
403 The number of characters in an ACE label is not in the range 1 to 63.
404 .TP
405 .SB idn_buffer_overflow
406 The specified buffer is too small to hold the result.
407 .TP
408 .SB idn_noentry
409 The specified key does not exist in the hash table.
410 .TP
411 .SB idn_nomemory
412 Memory allocation using malloc failed.
413 .TP
414 .SB idn_nofile
415 The specified file could not be opened.
416 .TP
417 .SB idn_nomapping
418 Some characters do not have the mapping to the target character set.
419 .TP
420 .SB idn_context_required
421 Context information is required.
422 .TP
423 .SB idn_prohibited
424 The specified string contains some prohibited characters.
425 .TP
426 .SB idn_failure
427 Generic error which is not covered by the above codes.
428 .\"
429 .SH EXAMPLES
430 To get the address of a internationalized domain name in the application's
431 local codeset, use \fBidn_encodename\fR to convert the name to the format
432 suitable for passing to resolver functions.
433 .RS 4
434 .nf
435 .ft CW
436 idn_result_t r;
437 char ace_name[256];
438 struct hostent *hp;
440 \&...
441 r = idn_encodename(IDN_ENCODE_APP, name, ace_name,
442 sizeof(ace_name));
443 if (r != idn_success) {
444 fprintf(stderr, "idn_encodename failed: %s\en",
445 idn_result_tostring(r));
446 exit(1);
447 }
449 hp = gethostbyname(ace_name);
450 \&...
451 .ft R
452 .fi
453 .RE
454 .PP
455 To decode the internationalized domain name returned from a resolver function,
456 use \fBidn_decodename\fR.
457 .RS 4
458 .nf
459 .ft CW
460 idn_result_t r;
461 char local_name[256];
462 struct hostent *hp;
464 \&...
465 hp = gethostbyname(name);
466 r = idn_decodename(IDN_DECODE_APP, hp->h_name, local_name,
467 sizeof(local_name));
468 if (r != idn_success) {
469 fprintf(stderr, "idn_decodename failed: %s\en",
470 idn_result_tostring(r));
471 exit(1);
472 }
473 printf("name: %s\en", local_name);
474 \&...
475 .ft R
476 .fi
477 .RE
478 .\"
479 .SH "SEE ALSO"
480 idn.conf(5)