1 \input texinfo @c -*- mode: texinfo; coding: us-ascii; -*-
2 @c This file is part of GNU Libidn.
3 @c See below for copyright and license.
5 @setfilename libidn.info
13 This manual is last updated @value{UPDATED} for version
14 @value{VERSION} of GNU Libidn.
16 Copyright @copyright{} 2002, 2003, 2004 Simon Josefsson.
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.2 or
21 any later version published by the Free Software Foundation; with the
22 Invariant Sections being "Commercial Support", no Front-Cover Texts,
23 and no Back-Cover Texts. A copy of the license is included in the
24 section entitled "GNU Free Documentation License".
28 @dircategory GNU Libraries
30 * libidn: (libidn). Internationalized string processing library.
33 @dircategory GNU utilities
35 * idn: (libidn)Invoking idn. Command line interface to GNU Libidn.
40 * IDN Library: (libidn)Emacs API. Emacs API for IDN functions.
45 @subtitle Internationalized string processing for the GNU system
46 @subtitle for version @value{VERSION}, @value{UPDATED}
47 @author Simon Josefsson
49 @vskip 0pt plus 1filll
63 * Introduction:: How to use this manual.
64 * Preparation:: What you should do before using the library.
65 * Utility Functions:: Unicode transformation utility functions.
66 * Stringprep Functions:: Stringprep functions.
67 * Punycode Functions:: Punycode functions.
68 * IDNA Functions:: IDNA functions.
69 * TLD Functions:: TLD functions.
70 * Examples:: Demonstrate how to use the library.
71 * Invoking idn:: Command line interface to the library.
72 * Emacs API:: Emacs Lisp API for Libidn.
73 * Acknowledgements:: Whom to blame.
78 * Function and Variable Index::
82 * Library Copying:: How you can copy and share GNU Libidn.
83 * Copying This Manual:: How you can copy and share this manual.
91 GNU Libidn is an implementation of the Stringprep, Punycode and IDNA
92 specifications defined by the IETF Internationalized Domain Names
93 (IDN) working group, used for internationalized domain names. The
94 package is available under the GNU Lesser General Public License.
96 The library contains a generic Stringprep implementation that does
97 Unicode 3.2 NFKC normalization, mapping and prohibitation of
98 characters, and bidirectional character handling. Profiles for
99 Nameprep, iSCSI, SASL and XMPP are included. Punycode and ASCII
100 Compatible Encoding (ACE) via IDNA are supported. A mechanism to
101 define Top-Level Domain (TLD) specific validation tables, and to
102 compare strings against those tables, is included. Default tables for
103 some TLDs are also included.
105 The Stringprep API consists of two main functions, one for converting
106 data from the system's native representation into UTF-8, and one
107 function to perform the Stringprep processing. Adding a new
108 Stringprep profile for your application within the API is
109 straightforward. The Punycode API consists of one encoding function
110 and one decoding function. The IDNA API consists of the ToASCII and
111 ToUnicode functions, as well as an high-level interface for converting
112 entire domain names to and from the ACE encoded form. The TLD API
113 consists of one set of functions to extract the TLD name from a domain
114 string, one set of functions to locate the proper TLD table to use
115 based on the TLD name, and core functions to validate a string against
116 a TLD table, and some utility wrappers to perform all the steps in one
119 The library is used by, e.g., GNU SASL and Shishi to process user
120 names and passwords. Libidn can be built into GNU Libc to enable a
121 new system-wide getaddrinfo flag for IDN processing.
123 Libidn is developed for the GNU/Linux system, but runs on over 20 Unix
124 platforms (including Solaris, IRIX, AIX, and Tru64) and Windows.
125 Libidn is written in C and (parts of) the API is accessible from C,
126 C++, Emacs Lisp, Python and Java.
132 * Supported Platforms::
133 * Commercial Support::
134 * Downloading and Installing::
139 @node Getting Started
140 @section Getting Started
142 This manual documents the library programming interface. All
143 functions and data types provided by the library are explained.
144 Included are also examples, and documentation for the command line
145 tool @file{idn} that provide a quick interface to the library. The
146 Emacs Lisp bindings for the library is also discussed.
148 The reader is assumed to possess basic familiarity with
149 internationalization concepts and network programming in C or C++.
151 This manual can be used in several ways. If read from the beginning
152 to the end, it gives a good introduction into the library and how it
153 can be used in an application. Forward references are included where
154 necessary. Later on, the manual can be used as a reference manual to
155 get just the information needed about any particular interface of the
156 library. Experienced programmers might want to start looking at the
157 examples at the end of the manual (@pxref{Examples}), and then only
158 read up those parts of the interface which are unclear.
163 This library might have a couple of advantages over other libraries
167 @item It's Free Software
168 Anybody can use, modify, and redistribute it under the terms of the
169 GNU Lesser General Public License.
171 @item It's thread-safe
172 No global state is kept in the library. All functions are reentrant.
175 The code is intended to be written in pure ANSI C89. It has been
176 tested on many Unix like operating systems, and Windows.
178 @item It's modularized
179 The library is composed of several modules, and the only interaction
180 between modules is through each modules' public API. If you only need
181 one piece of functionality, it is possible to take the files you need
182 and incorporate them into your own project.
184 @item It's not bloated
185 The design of the library is based on the smallest API necessary to
186 implement the basic functionality. It has been carefully extended
187 with a small number of high-level wrappers to make it comfortable to
188 use the library. However, it does not implement additional
189 functionality just for the sake of completeness.
191 @item It's documented
192 Sadly, not all software comes with documentation these days. This one
197 @node Library Overview
198 @section Library Overview
200 The following illustration show the components that make up Libidn,
201 and how your application relates to the library. In the illustration,
202 various components are shown as boxes. You see the generic StringPrep
203 component, the various StringPrep profiles including Nameprep, the
204 Punycode component, the IDNA component, and the TLD component. The
205 arrows indicate aggregation, e.g., IDNA uses Punycode and Nameprep,
206 and in turn Nameprep uses the generic StringPrep interface. The
207 interfaces to all components are available for applications, no
208 component within the library is hidden from the application.
212 @node Supported Platforms
213 @section Supported Platforms
215 Libidn has at some point in time been tested on the following
220 @item Debian GNU/Linux 3.0 (Woody)
223 GCC 2.95.4 and GNU Make. This is the main development platform.
224 @code{alphaev67-unknown-linux-gnu}, @code{alphaev6-unknown-linux-gnu},
225 @code{arm-unknown-linux-gnu}, @code{armv4l-unknown-linux-gnu},
226 @code{hppa-unknown-linux-gnu}, @code{hppa64-unknown-linux-gnu},
227 @code{i686-pc-linux-gnu}, @code{ia64-unknown-linux-gnu},
228 @code{m68k-unknown-linux-gnu}, @code{mips-unknown-linux-gnu},
229 @code{mipsel-unknown-linux-gnu}, @code{powerpc-unknown-linux-gnu},
230 @code{s390-ibm-linux-gnu}, @code{sparc-unknown-linux-gnu},
231 @code{sparc64-unknown-linux-gnu}.
233 @item Debian GNU/Linux 2.1
236 GCC 2.95.1 and GNU Make. @code{armv4l-unknown-linux-gnu}.
241 Tru64 UNIX C compiler and Tru64 Make. @code{alphaev67-dec-osf5.1},
242 @code{alphaev68-dec-osf5.1}.
247 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
248 @code{alphaev67-unknown-linux-gnu}.
250 @item SuSE Linux 7.2a
253 GCC 3.0 and GNU Make. @code{ia64-unknown-linux-gnu}.
258 GCC 3.2.2 and GNU Make. @code{x86_64-unknown-linux-gnu} (AMD64
261 @item RedHat Linux 7.2
264 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
265 @code{alphaev67-unknown-linux-gnu}, @code{ia64-unknown-linux-gnu}.
267 @item RedHat Linux 8.0
270 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
272 @item RedHat Advanced Server 2.1
273 @cindex RedHat Advanced Server
275 GCC 2.96 and GNU Make. @code{i686-pc-linux-gnu}.
277 @item Slackware Linux 8.0.01
280 GCC 2.95.3 and GNU Make. @code{i686-pc-linux-gnu}.
282 @item Mandrake Linux 9.0
285 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
290 MIPS C compiler, IRIX Make. @code{mips-sgi-irix6.5}.
295 IBM C for AIX compiler, AIX Make. @code{rs6000-ibm-aix4.3.2.0}.
297 @item Microsoft Windows 2000 (Cygwin)
300 GCC 3.2, GNU make. @code{i686-pc-cygwin}.
305 HP-UX C compiler and HP Make. @code{ia64-hp-hpux11.22},
306 @code{hppa2.0w-hp-hpux11.11}.
308 @item SUN Solaris 2.8
311 Sun WorkShop Compiler C 6.0 and SUN Make. @code{sparc-sun-solaris2.8}.
313 @item SUN Solaris 2.9
316 Sun Forte Developer 7 C compiler and GNU
317 Make. @code{sparc-sun-solaris2.9}.
322 GCC 2.95.3 and GNU Make. @code{alpha-unknown-netbsd1.6},
323 @code{i386-unknown-netbsdelf1.6}.
325 @item OpenBSD 3.1 and 3.2
328 GCC 2.95.3 and GNU Make. @code{alpha-unknown-openbsd3.1},
329 @code{i386-unknown-openbsd3.1}.
331 @item FreeBSD 4.7 and 4.8
334 GCC 2.95.4 and GNU Make. @code{alpha-unknown-freebsd4.7},
335 @code{alpha-unknown-freebsd4.8}, @code{i386-unknown-freebsd4.7},
336 @code{i386-unknown-freebsd4.8}.
338 @item MacOS X 10.2 Server Edition
341 GCC 3.1 and GNU Make. @code{powerpc-apple-darwin6.5}.
345 If you use Libidn on, or port Libidn to, a new platform please report
348 @node Commercial Support
349 @section Commercial Support
351 Commercial support is available for users of GNU Libidn. The kind of
352 support that can be purchased may include:
356 @item Implement new features.
357 Such as country code specific profiling to support a restricted subset
360 @item Port Libidn to new platforms.
361 This could include porting Libidn to an embedded platforms that may
362 need memory or size optimization.
364 @item Integrating IDN support in your existing project.
366 @item System design of components related to IDN.
370 If you are interested, please write to:
373 Simon Josefsson Datakonsult
378 E-mail: simon@josefsson.org
381 If your company provide support related to GNU Libidn and would like
382 to be mentioned here, contact the author (@pxref{Bug Reports}).
384 @node Downloading and Installing
385 @section Downloading and Installing
389 The package can be downloaded from several places, including
390 @url{http://josefsson.org/libidn/releases/}. The latest version is
391 stored in a file, e.g., @samp{libidn-@value{VERSION}.tar.gz} where the
392 @samp{@value{VERSION}} indicate the highest version number.
394 The package is then extracted, configured and built like many other
395 packages that use Autoconf. For detailed information on configuring
396 and building it, refer to the @file{INSTALL} file that is part of the
397 distribution archive.
399 Here is an example terminal session that download, configure, build
400 and install the package. You will need a few basic tools, such as
401 @samp{sh}, @samp{make} and @samp{cc}.
404 $ wget -q http://josefsson.org/libidn/releases/libidn-@value{VERSION}.tar.gz
405 $ tar xfz libidn-@value{VERSION}.tar.gz
406 $ cd libidn-@value{VERSION}/
415 After that Libidn should be properly installed and ready for use.
419 @cindex Reporting Bugs
421 If you think you have found a bug in Libidn, please investigate it and
426 @item Please make sure that the bug is really in Libidn, and
427 preferably also check that it hasn't already been fixed in the latest
430 @item You have to send us a test case that makes it possible for us to
433 @item You also have to explain what is wrong; if you get a crash, or
434 if the results printed are not good and in that case, in what way.
435 Make sure that the bug report includes all information you would need
436 to fix this kind of bug for someone else.
440 Please make an effort to produce a self-contained report, with
441 something definite that can be tested or debugged. Vague queries or
442 piecemeal messages are difficult to act on and don't help the
445 If your bug report is good, we will do our best to help you to get a
446 corrected version of the software; if the bug report is poor, we won't
447 do anything about it (apart from asking you to send better bug
450 If you think something in this manual is unclear, or downright
451 incorrect, or if the language needs to be improved, please also send a
454 Send your bug report to:
456 @center @samp{bug-libidn@@gnu.org}
460 @section Contributing
464 If you want to submit a patch for inclusion -- from solve a typo you
465 discovered, up to adding support for a new feature -- you should
466 submit it as a bug report (@pxref{Bug Reports}). There are some
467 things that you can do to increase the chances for it to be included
468 in the official package.
470 Unless your patch is very small (say, under 10 lines) we require that
471 you assign the copyright of your work to the Free Software Foundation.
472 This is to protect the freedom of the project. If you have not
473 already signed papers, we will send you the necessary information when
474 you submit your contribution.
476 For contributions that doesn't consist of actual programming code, the
477 only guidelines are common sense. Use it.
479 For code contributions, a number of style guides will help you:
484 Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
487 If you normally code using another coding standard, there is no
488 problem, but you should use @samp{indent} to reformat the code
489 (@pxref{top, GNU Indent,, indent}) before submitting your work.
491 @item Use the unified diff format @samp{diff -u}.
494 No reason whatsoever should abort the execution of the library. Even
495 memory allocation errors, e.g. when malloc return NULL, should work
496 although result in an error code.
498 @item Design with thread safety in mind.
499 Don't use global variables and the like.
501 @item Avoid using the C math library.
502 It causes problems for embedded implementations, and in most
503 situations it is very easy to avoid using it.
505 @item Document your functions.
506 Use comments before each function headers, that, if properly
507 formatted, are extracted into GTK-DOC web pages. Don't forget to
508 update the Texinfo manual as well.
510 @item Supply a ChangeLog and NEWS entries, where appropriate.
514 @c **********************************************************
515 @c ******************* Preparation ************************
516 @c **********************************************************
520 To use `Libidn', you have to perform some changes to your sources and
521 the build system. The necessary changes are small and explained in
522 the following sections. At the end of this chapter, it is described
523 how the library is initialized, and how the requirements of the
524 library are verified.
526 A faster way to find out how to adapt your application for use with
527 `Libidn' may be to look at the examples at the end of this manual
534 * Building the source::
541 The library contains a few independent parts, and each part export the
542 interfaces (data types and functions) in a header file. You must
543 include the appropriate header files in all programs using the
544 library, either directly or through some other header file, like this:
547 #include <stringprep.h>
550 The header files and the functions they define are categorized as
556 The low-level stringprep API entry point. For IDN applications, this
557 is usually invoked via IDNA. Some applications, specifically non-IDN
558 ones, may want to prepare strings directly though, and should include
561 The name space of the stringprep part of Libidn is @code{stringprep*}
562 for function names, @code{Stringprep*} for data types and
563 @code{STRINGPREP_*} for other symbols. In addition the same name
564 prefixes with one prepended underscore are reserved for internal use
565 and should never be used by an application.
569 The entry point to Punycode encoding and decoding functions. Normally
570 punycode is used via the idna.h interface, but some application may
571 want to perform raw punycode operations.
573 The name space of the punycode part of Libidn is @code{punycode_*} for
574 function names, @code{Punycode*} for data types and @code{PUNYCODE_*}
575 for other symbols. In addition the same name prefixes with one
576 prepended underscore are reserved for internal use and should never be
577 used by an application.
581 The entry point to the IDNA functions. This is the normal entry point
582 for applications that need IDN functionality.
584 The name space of the IDNA part of Libidn is @code{idna_*} for
585 function names, @code{Idna*} for data types and @code{IDNA_*} for
586 other symbols. In addition the same name prefixes with one prepended
587 underscore are reserved for internal use and should never be used by
592 The entry point to the TLD functions. Normal applications are not
593 expected to need this functionality, but it is present for
594 applications that are used by TLDs to validate customer input.
596 The name space of the TLD part of Libidn is @code{tld_*} for function
597 names, @code{Tld_*} for data types and @code{TLD_*} for other symbols.
598 In addition the same name prefixes with one prepended underscore are
599 reserved for internal use and should never be used by an application.
604 @section Initialization
606 Libidn is stateless and does not need any initialization.
609 @section Version Check
611 It is often desirable to check that the version of `Libidn' used is
612 indeed one which fits all requirements. Even with binary
613 compatibility new features may have been introduced but due to problem
614 with the dynamic linker an old version is actually used. So you may
615 want to check that the version is okay right after program startup.
617 @include texi/stringprep_check_version.texi
619 The normal way to use the function is to put something similar to the
620 following first in your @code{main}:
623 if (!stringprep_check_version (STRINGPREP_VERSION))
625 printf ("stringprep_check_version() failed:\n"
626 "Header file incompatible with shared library.\n");
631 @node Building the source
632 @section Building the source
633 @cindex Compiling your application
635 If you want to compile a source file including e.g. the `idna.h' header
636 file, you must make sure that the compiler can find it in the
637 directory hierarchy. This is accomplished by adding the path to the
638 directory in which the header file is located to the compilers include
639 file search path (via the @option{-I} option).
641 However, the path to the include file is determined at the time the
642 source is configured. To solve this problem, `Libidn' uses the
643 external package @command{pkg-config} that knows the path to the
644 include file and other configuration options. The options that need
645 to be added to the compiler invocation at compile time are output by
646 the @option{--cflags} option to @command{pkg-config libidn}. The
647 following example shows how it can be used at the command line:
650 gcc -c foo.c `pkg-config libidn --cflags`
653 Adding the output of @samp{pkg-config libidn --cflags} to the
654 compilers command line will ensure that the compiler can find e.g. the
657 A similar problem occurs when linking the program with the library.
658 Again, the compiler has to find the library files. For this to work,
659 the path to the library files has to be added to the library search
660 path (via the @option{-L} option). For this, the option
661 @option{--libs} to @command{pkg-config libidn} can be used. For
662 convenience, this option also outputs all other options that are
663 required to link the program with the `libidn' libarary. The example
664 shows how to link @file{foo.o} with the `libidn' library to a program
668 gcc -o foo foo.o `pkg-config libidn --libs`
671 Of course you can also combine both examples to a single command by
672 specifying both options to @command{pkg-config}:
675 gcc -o foo foo.c `pkg-config libidn --cflags --libs`
679 @section Autoconf tests
680 @cindex Autoconf tests
681 @cindex Configure tests
683 If your project uses Autoconf (@pxref{top, GNU Autoconf,, autoconf})
684 to check for installed libraries, you might find the following snippet
685 illustrative. It add a new @file{configure} parameter
686 @code{--with-libidn}, and check for @file{idna.h} and @samp{-lidn}
687 (possibly below the directory specified as the optional argument to
688 @code{--with-libidn}), and define the @acronym{CPP} symbol
689 @code{LIBIDN} if the library is found. The default behaviour is to
690 search for the library and enable the functionality (that is, define
691 the symbol) when the library is found, but if you wish to make the
692 default behaviour of your package be that Libidn is not used (even if
693 it is installed on the system), change @samp{libidn=yes} to
694 @samp{libidn=no} on the third line.
697 AC_ARG_WITH(libidn, AC_HELP_STRING([--with-libidn=[DIR]],
698 [Support IDN (needs GNU Libidn)]),
699 libidn=$withval, libidn=yes)
700 if test "$libidn" != "no"; then
701 if test "$libidn" != "yes"; then
702 LDFLAGS="$@{LDFLAGS@} -L$libidn/lib"
703 CPPFLAGS="$@{CPPFLAGS@} -I$libidn/include"
705 AC_CHECK_HEADER(idna.h,
706 AC_CHECK_LIB(idn, stringprep_check_version,
707 [libidn=yes LIBS="$@{LIBS@} -lidn"], libidn=no),
710 if test "$libidn" != "no" ; then
711 AC_DEFINE(LIBIDN, 1, [Define to 1 if you want IDN support.])
713 AC_MSG_WARN([Libidn not found])
715 AC_MSG_CHECKING([if Libidn should be used])
716 AC_MSG_RESULT($libidn)
719 If you require that your users have installed @code{pkg-config} (which
720 I cannot recommend generally), the above can be done more easily as
724 AC_ARG_WITH(libidn, AC_HELP_STRING([--with-libidn=[DIR]],
725 [Support IDN (needs GNU Libidn)]),
726 libidn=$withval, libidn=yes)
727 if test "$libidn" != "no" ; then
728 PKG_CHECK_MODULES(LIBIDN, libidn >= 0.0.0, [libidn=yes], [libidn=no])
729 if test "$libidn" != "yes" ; then
731 AC_MSG_WARN([Libidn not found])
734 AC_DEFINE(LIBIDN, 1, [Define to 1 if you want Libidn.])
737 AC_MSG_CHECKING([if Libidn should be used])
738 AC_MSG_RESULT($libidn)
741 @c **********************************************************
742 @c ******************** Utility Functions ******************
743 @c **********************************************************
744 @node Utility Functions
745 @chapter Utility Functions
746 @cindex Utility Functions
748 The rest of this library makes extensive use of Unicode characters.
749 In order to interface this library with the outside world, your
750 application may need to make various Unicode transformations.
752 @section Header file @code{stringprep.h}
754 To use the functions explained in this chapter, you need to include
755 the file @file{stringprep.h} using:
758 #include <stringprep.h>
761 @section Unicode Encoding Transformation
763 @include texi/stringprep_unichar_to_utf8.texi
764 @include texi/stringprep_utf8_to_unichar.texi
765 @include texi/stringprep_ucs4_to_utf8.texi
766 @include texi/stringprep_utf8_to_ucs4.texi
768 @section Unicode Normalization
770 @include texi/stringprep_ucs4_nfkc_normalize.texi
771 @include texi/stringprep_utf8_nfkc_normalize.texi
773 @section Character Set Conversion
775 @include texi/stringprep_locale_charset.texi
776 @include texi/stringprep_convert.texi
777 @include texi/stringprep_locale_to_utf8.texi
778 @include texi/stringprep_utf8_to_locale.texi
781 @c **********************************************************
782 @c ****************** Stringprep Functions *****************
783 @c **********************************************************
784 @node Stringprep Functions
785 @chapter Stringprep Functions
786 @cindex Stringprep Functions
788 Stringprep describes a framework for preparing Unicode text strings in
789 order to increase the likelihood that string input and string
790 comparison work in ways that make sense for typical users throughout
791 the world. The stringprep protocol is useful for protocol identifier
792 values, company and personal names, internationalized domain names,
793 and other text strings.
795 @section Header file @code{stringprep.h}
797 To use the functions explained in this chapter, you need to include
798 the file @file{stringprep.h} using:
801 #include <stringprep.h>
804 @section Defining A Stringprep Profile
806 Further types and structures are defined for applications that want to
807 specify their own stringprep profile. As these are fairly obscure,
808 and by necessity tied to the implementation, we do not document them
809 here. Look into the @file{stringprep.h} header file, and the
810 @file{profiles.c} source code for the details.
812 @section Return Codes
814 All functions return a code of the @code{Stringprep_rc}
817 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_OK = 0}
818 Successful operation. This value is guaranteed to always be zero, the
819 remaining ones are only guaranteed to hold non-zero values, for
820 logical comparison purposes.
823 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_CONTAINS_UNASSIGNED}
824 String contain unassigned Unicode code points, which is forbidden by
828 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_CONTAINS_PROHIBITED}
829 String contain code points prohibited by the profile.
832 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_BIDI_BOTH_L_AND_RAL}
833 String contain code points with conflicting bidirection category.
836 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_BIDI_LEADTRAIL_NOT_RAL}
837 Leading and trailing character in string not of proper bidirectional
841 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_BIDI_CONTAINS_PROHIBITED}
842 Contains prohibited code points detected by bidirectional code.
845 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_TOO_SMALL_BUFFER}
846 Buffer handed to function was too small. This usually indicate a
847 problem in the calling application.
850 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_PROFILE_ERROR}
851 The stringprep profile was inconsistent. This usually indicate an
852 internal error in the library.
855 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_FLAG_ERROR}
856 The supplied flag conflicted with profile. This usually indicate a
857 problem in the calling application.
860 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_UNKNOWN_PROFILE}
861 The supplied profile name was not known to the library.
864 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_NFKC_FAILED}
865 The Unicode NFKC operation failed. This usually indicate an internal
866 error in the library.
869 @deftypevr {Return code} {Stringprep_rc} {STRINGPREP_MALLOC_ERROR}
870 The @code{malloc} was out of memory. This is usually a fatal error.
873 @section Control Flags
875 @deftypevr {Stringprep flags} {Stringprep_profile_flags} {STRINGPREP_NO_NFKC}
876 Disable the NFKC normalization, as well as selecting the non-NFKC case
877 folding tables. Usually the profile specifies BIDI and NFKC settings,
878 and applications should not override it unless in special situations.
881 @deftypevr {Stringprep flags} {Stringprep_profile_flags} {STRINGPREP_NO_BIDI}
882 Disable the BIDI step. Usually the profile specifies BIDI and NFKC
883 settings, and applications should not override it unless in special
887 @deftypevr {Stringprep flags} {Stringprep_profile_flags} {STRINGPREP_NO_UNASSIGNED}
888 Make the library return with an error if string contains unassigned
889 characters according to profile.
892 @section Core Functions
894 @include texi/stringprep_4i.texi
895 @include texi/stringprep_4zi.texi
896 @include texi/stringprep.texi
897 @include texi/stringprep_profile.texi
899 @section Stringprep Profile Macros
901 @deftypefun {int} stringprep_nameprep_no_unassigned (char * @var{in}, int @var{maxlen})
903 @var{in}: input/ouput array with string to prepare.
905 @var{maxlen}: maximum length of input/output array.
907 Prepare the input UTF-8 string according to the nameprep profile. The
908 AllowUnassigned flag is false, use @code{stringprep_nameprep} for
909 true AllowUnassigned. Returns 0 iff successful, or an error code.
912 @deftypefun {int} stringprep_iscsi (char * @var{in}, int @var{maxlen})
914 @var{in}: input/ouput array with string to prepare.
916 @var{maxlen}: maximum length of input/output array.
918 Prepare the input UTF-8 string according to the draft iSCSI stringprep
919 profile. Returns 0 iff successful, or an error code.
922 @deftypefun {int} stringprep_plain (char * @var{in}, int @var{maxlen})
924 @var{in}: input/ouput array with string to prepare.
926 @var{maxlen}: maximum length of input/output array.
928 Prepare the input UTF-8 string according to the draft SASL ANONYMOUS
929 profile. Returns 0 iff successful, or an error code.
932 @deftypefun {int} stringprep_xmpp_nodeprep (char * @var{in}, int @var{maxlen})
934 @var{in}: input/ouput array with string to prepare.
936 @var{maxlen}: maximum length of input/output array.
938 Prepare the input UTF-8 string according to the draft XMPP node
939 identifier profile. Returns 0 iff successful, or an error code.
942 @deftypefun {int} stringprep_xmpp_resourceprep (char * @var{in}, int @var{maxlen})
944 @var{in}: input/ouput array with string to prepare.
946 @var{maxlen}: maximum length of input/output array.
948 Prepare the input UTF-8 string according to the draft XMPP resource
949 identifier profile. Returns 0 iff successful, or an error code.
952 @c **********************************************************
953 @c ******************* Punycode Functions ******************
954 @c **********************************************************
955 @node Punycode Functions
956 @chapter Punycode Functions
957 @cindex Punycode Functions
959 Punycode is a simple and efficient transfer encoding syntax designed
960 for use with Internationalized Domain Names in Applications. It
961 uniquely and reversibly transforms a Unicode string into an ASCII
962 string. ASCII characters in the Unicode string are represented
963 literally, and non-ASCII characters are represented by ASCII
964 characters that are allowed in host name labels (letters, digits, and
965 hyphens). A general algorithm called Bootstring allows a string of
966 basic code points to uniquely represent any string of code points
967 drawn from a larger set. Punycode is an instance of Bootstring that
968 uses particular parameter values, appropriate for IDNA.
970 @section Header file @code{punycode.h}
972 To use the functions explained in this chapter, you need to include
973 the file @file{punycode.h} using:
976 #include <punycode.h>
979 @section Return Codes
981 All functions return a code of the @code{Punycode_status} enumerated
984 @deftypevr {Return code} {Punycode_status} {PUNYCODE_SUCCESS = 0}
985 Successful operation. This value is guaranteed to always be zero, the
986 remaining ones are only guaranteed to hold non-zero values, for
987 logical comparison purposes.
990 @deftypevr {Return code} {Punycode_status} {PUNYCODE_BAD_INPUT}
994 @deftypevr {Return code} {Punycode_status} {PUNYCODE_BIG_OUTPUT}
995 Output would exceed the space provided.
998 @deftypevr {Return code} {Punycode_status} {PUNYCODE_OVERFLOW}
999 Input needs wider integers to process.
1002 @section Unicode Code Point Data Type
1004 The punycode function uses a special type to denote Unicode code
1005 points. It is guaranteed to always be a 32 bit unsigned integer.
1007 @deftypevr {Punycode Unicode code point} uint32_t punycode_uint
1008 A unsigned integer that hold Unicode code points.
1011 @section Core Functions
1013 Note that the current implementation will fail if the
1014 @code{input_length} exceed 4294967295 (the size of
1015 @code{punycode_uint}). This restriction may be removed in the future.
1016 Meanwhile applications are encouraged to not depend on this problem,
1017 and use @code{sizeof} to initialize @code{input_length} and
1018 @code{output_length}.
1020 The functions provided are the following two entry points:
1022 @include texi/punycode_encode.texi
1023 @include texi/punycode_decode.texi
1025 @c **********************************************************
1026 @c ********************* IDNA Functions *********************
1027 @c **********************************************************
1028 @node IDNA Functions
1029 @chapter IDNA Functions
1030 @cindex IDNA Functions
1032 Until now, there has been no standard method for domain names to use
1033 characters outside the ASCII repertoire. The IDNA document defines
1034 internationalized domain names (IDNs) and a mechanism called IDNA for
1035 handling them in a standard fashion. IDNs use characters drawn from a
1036 large repertoire (Unicode), but IDNA allows the non-ASCII characters
1037 to be represented using only the ASCII characters already allowed in
1038 so-called host names today. This backward-compatible representation is
1039 required in existing protocols like DNS, so that IDNs can be
1040 introduced with no changes to the existing infrastructure. IDNA is
1041 only meant for processing domain names, not free text.
1043 @section Header file @code{idna.h}
1045 To use the functions explained in this chapter, you need to include
1046 the file @file{idna.h} using:
1052 @section Return Codes
1054 All functions return a exit code:
1056 @deftypevr {Return code} {Idna_rc} {IDNA_SUCCESS = 0}
1057 Successful operation. This value is guaranteed to always be zero, the
1058 remaining ones are only guaranteed to hold non-zero values, for
1059 logical comparison purposes.
1062 @deftypevr {Return code} {Idna_rc} IDNA_STRINGPREP_ERROR
1063 Error during string preparation.
1066 @deftypevr {Return code} {Idna_rc} IDNA_PUNYCODE_ERROR
1067 Error during punycode operation.
1070 @deftypevr {Return code} {Idna_rc} IDNA_CONTAINS_NON_LDH
1071 For IDNA_USE_STD3_ASCII_RULES, indicate that the string contains
1072 non-LDH ASCII characters.
1075 @deftypevr {Return code} {Idna_rc} IDNA_CONTAINS_MINUS
1076 For IDNA_USE_STD3_ASCII_RULES, indicate that the string contains a
1077 leading or trailing hyphen-minus (U+002D).
1080 @deftypevr {Return code} {Idna_rc} IDNA_INVALID_LENGTH
1081 The final output string is not within the (inclusive) range 1 to 63
1085 @deftypevr {Return code} {Idna_rc} IDNA_NO_ACE_PREFIX
1086 The string does not contain the ACE prefix (for ToUnicode).
1089 @deftypevr {Return code} {Idna_rc} IDNA_ROUNDTRIP_VERIFY_ERROR
1090 The ToASCII operation on output string does not equal the input.
1093 @deftypevr {Return code} {Idna_rc} IDNA_CONTAINS_ACE_PREFIX
1094 The input contains the ACE prefix (for ToASCII).
1097 @deftypevr {Return code} {Idna_rc} IDNA_ICONV_ERROR
1098 Could not convert string in locale encoding.
1101 @deftypevr {Return code} {Idna_rc} IDNA_MALLOC_ERROR
1102 Could not allocate buffer (this is typically a fatal error).
1105 @section Control Flags
1107 The IDNA @code{flags} parameter can take on the following values, or a
1108 bit-wise inclusive or of any subset of the parameters:
1110 @deftypevr {Return code} {Idna_flags} IDNA_ALLOW_UNASSIGNED
1111 Allow unassigned Unicode code points.
1114 @deftypevr {Return code} {Idna_flags} IDNA_USE_STD3_ASCII_RULES
1115 Check output to make sure it is a STD3 conforming host name.
1118 @section Prefix String
1120 @deftypevr {Macro} {#define} IDNA_ACE_PREFIX
1121 String with the official IDNA prefix, @code{xn--}.
1124 @section Core Functions
1126 The idea behind the IDNA function names are as follows: the
1127 @code{idna_to_ascii_4i} and @code{idna_to_unicode_44i} functions are
1128 the core IDNA primitives. The @code{4} indicate that the function
1129 takes UCS-4 strings (i.e., Unicode code points encoded in a 32-bit
1130 unsigned integer type) of the specified length. The @code{i} indicate
1131 that the data is written ``inline'' into the buffer. This means the
1132 caller is responsible for allocating (and deallocating) the string,
1133 and providing the library with the allocated length of the string.
1134 The output length is written in the output length variable. The
1135 remaining functions all contain the @code{z} indicator, which means
1136 the strings are zero terminated. All output strings are allocated by
1137 the library, and must be deallocated by the caller. The @code{4}
1138 indicator again means that the string is UCS-4, the @code{8} means the
1139 strings are UTF-8 and the @code{l} indicator means the strings are
1140 encoded in the encoding used by the current locale.
1142 The functions provided are the following entry points:
1144 @include texi/idna_to_ascii_4i.texi
1145 @include texi/idna_to_unicode_44i.texi
1147 @section Simplified ToASCII Interface
1149 @include texi/idna_to_ascii_4z.texi
1150 @include texi/idna_to_ascii_8z.texi
1151 @include texi/idna_to_ascii_lz.texi
1153 @section Simplified ToUnicode Interface
1155 @include texi/idna_to_unicode_4z4z.texi
1156 @include texi/idna_to_unicode_8z4z.texi
1157 @include texi/idna_to_unicode_8z8z.texi
1158 @include texi/idna_to_unicode_8zlz.texi
1159 @include texi/idna_to_unicode_lzlz.texi
1162 @c **********************************************************
1163 @c ********************** TLD Functions *********************
1164 @c **********************************************************
1166 @chapter TLD Functions
1167 @cindex TLD Functions
1169 Organizations that manage some Top Level Domains (@acronym{TLD}s) have
1170 published tables with characters they accept within the domain. The
1171 reason may be to reduce complexity that come from using the full
1172 Unicode range, and to protect themselves from future (backwards
1173 incompatible) changes in the IDN or Unicode specifications. Libidn
1174 implement an infrastructure for defining and checking strings against
1175 such tables. Libidn also ship some tables from @acronym{TLD}s that we
1176 have managed to get permission to use them from. Because these tables
1177 are even less static than Unicode or StringPrep tables, it is likely
1178 that they will be updated from time to time (even in backwards
1179 incompatibe ways). The Libidn interface provide a ``version'' field
1180 for each @acronym{TLD} table, which can be compared for equality to
1181 guarantee the same operation over time.
1183 From a design point of view, you can regard the @acronym{TLD} tables
1184 for IDN as the ``localization'' step that come after the
1185 ``internationalization'' step provided by the IETF standards.
1187 @section Header file @code{tld.h}
1189 To use the functions explained in this chapter, you need to include
1190 the file @file{tld.h} using:
1196 @section Return Codes
1198 Most functions return a exit code:
1200 @deftypevr {Return code} {Tld_rc} {TLD_SUCCESS = 0}
1201 Successful operation. This value is guaranteed to always be zero, the
1202 remaining ones are only guaranteed to hold non-zero values, for
1203 logical comparison purposes.
1206 @deftypevr {Return code} {Tld_rc} TLD_INVALID
1207 Invalid character found.
1210 @deftypevr {Return code} {Tld_rc} TLD_NODATA
1211 No input data was provided.
1214 @deftypevr {Return code} {Tld_rc} TLD_MALLOC_ERROR
1215 Error during memory allocation.
1218 @deftypevr {Return code} {Tld_rc} TLD_ICONV_ERROR
1219 Error during iconv string conversion.
1222 @deftypevr {Return code} {Tld_rc} TLD_NOTLD
1223 No top-level domain found in domain string.
1226 @c @section Data Types
1228 @c @deftp {Data type} {Tld_table_element} @var{start} @var{end}
1230 @c /* Interval of valid code points in the TLD. */
1231 @c struct Tld_table_element
1233 @c uint32_t start; /* Start of range. */
1234 @c uint32_t end; /* End of range, end == start if single. */
1236 @c typedef struct Tld_table_element Tld_table_element;
1238 @c This @code{struct} contain the @var{start} and @var{end} positions
1239 @c (inclusive) of a range. If the range is a single (i.e., starts and
1240 @c ends in the same character), then set @var{end} to the same as
1241 @c @var{start}. This structure is normally used as an array.
1244 @c @deftp {Data type} {Tld_table} @var{name} @var{version} @var{nvalid} @var{valid}
1246 @c /* List valid code points in a TLD. */
1249 @c char *name; /* TLD name, e.g., "no". */
1250 @c char *version; /* Version string from TLD file. */
1251 @c size_t nvalid; /* Number of entries in data. */
1252 @c Tld_table_element *valid[]; /* Sorted array of valid code points. */
1254 @c typedef struct Tld_table Tld_table;
1256 @c In this @code{struct}, the @var{name} field is a string (@samp{char*})
1257 @c indicating the TLD name (e.g., ``no''). The @var{version} field is a
1258 @c string (@samp{char*}) containing a free form humanly readable string
1259 @c that can be used for equality comparison to compare different versions
1260 @c of the table. The @var{nvalid} field indicate how many entries there
1261 @c are in @var{valid}, which brings us finally to @var{valid} that
1262 @c contain the actual code points that are valid for this TLD (see
1263 @c @code{Tld_table_element} above).
1266 @section Core Functions
1268 @include texi/tld_check_4t.texi
1269 @include texi/tld_check_4tz.texi
1271 @section Utility Functions
1273 @include texi/tld_get_4.texi
1274 @include texi/tld_get_4z.texi
1275 @include texi/tld_get_z.texi
1276 @include texi/tld_get_table.texi
1277 @include texi/tld_default_table.texi
1279 @section High-Level Wrapper Functions
1281 @include texi/tld_check_4.texi
1282 @include texi/tld_check_4z.texi
1283 @include texi/tld_check_8z.texi
1284 @include texi/tld_check_lz.texi
1286 @c **********************************************************
1287 @c *********************** Examples ***********************
1288 @c **********************************************************
1293 This chapter contains example code which illustrate how `Libidn' can
1294 be used when writing your own application.
1297 * Example 1:: Example using stringprep.
1298 * Example 2:: Example using punycode.
1299 * Example 3:: Example using IDNA ToASCII.
1300 * Example 4:: Example using IDNA ToUnicode.
1301 * Example 5:: Example using TLD checking.
1307 This example demonstrates how the stringprep functions are used.
1309 @verbatiminclude ../examples/example.c
1314 This example demonstrates how the punycode functions are used.
1316 @verbatiminclude ../examples/example2.c
1321 This example demonstrates how the library is used to convert
1322 internationalized domain names into ASCII compatible names.
1324 @verbatiminclude ../examples/example3.c
1329 This example demonstrates how the library is used to convert ASCII
1330 compatible names to internationalized domain names.
1332 @verbatiminclude ../examples/example4.c
1337 This example demonstrates how the library is used to check a string
1338 for invalid characters within a specific TLD.
1340 @verbatiminclude ../examples/example5.c
1342 @c **********************************************************
1343 @c ********************* Invoking idn *********************
1344 @c **********************************************************
1346 @chapter Invoking idn
1349 @cindex invoking @command{idn}
1350 @cindex command line
1354 GNU Libidn (idn) -- Internationalized Domain Names command line tool
1356 @section Description
1357 @code{idn} allows internationalized string preparation
1358 (@samp{stringprep}), encoding and decoding of punycode data, and IDNA
1359 ToASCII/ToUnicode operations to be performed on the command line.
1361 If strings are specified on the command line, they are used as input
1362 and the computed output is printed to standard output @code{stdout}.
1363 If no strings are specified on the command line, the program read
1364 data, line by line, from the standard input @code{stdin}, and print
1365 the computed output to standard output. What processing is performed
1366 (e.g., ToASCII, or Punycode encode) is indicated by options. If any
1367 errors are encountered, the execution of the applications is aborted.
1369 To process a string that starts with @code{-}, for example
1370 @code{-foo}, use @code{--} to signal the end of parameters, as in
1371 @code{idn --quiet -a -- -foo}.
1374 @code{idn} recognizes these commands:
1377 -h, --help Print help and exit
1379 -V, --version Print version and exit
1381 -s, --stringprep Prepare string according to nameprep profile
1383 -d, --punycode-decode Decode Punycode
1385 -e, --punycode-encode Encode Punycode
1387 -a, --idna-to-ascii Convert to ACE according to IDNA (default)
1389 -u, --idna-to-unicode Convert from ACE according to IDNA
1391 --allow-unassigned Toggle IDNA AllowUnassigned flag (default=off)
1393 --usestd3asciirules Toggle IDNA UseSTD3ASCIIRules flag (default=off)
1395 -t, --tld Check string for TLD specific rules
1396 Only for --idna-to-ascii and --idna-to-unicode
1399 -p, --profile=STRING Use specified stringprep profile instead
1400 Valid stringprep profiles are `Nameprep',
1401 `iSCSI', `Nodeprep', `Resourceprep', `trace', and
1404 --debug Print debugging information (default=off)
1406 --quiet Silent operation (default=off)
1409 @section Environment Variables
1411 The @var{CHARSET} environment variable can be used to override what
1412 character set to be used for decoding incoming data (i.e., on the
1413 command line or on the standard input stream), and to encode data to
1414 the standard output. If your system is set up correctly, however, the
1415 application will guess which character set is used automatically.
1419 $ CHARSET=ISO-8859-1 idn --punycode-encode
1425 Standard usage, reading input from standard input:
1430 Copyright 2002, 2003 Simon Josefsson.
1431 GNU Libidn comes with NO WARRANTY, to the extent permitted by law.
1432 You may redistribute copies of GNU Libidn under the terms of
1433 the GNU Lesser General Public License. For more information
1434 about these matters, see the file named COPYING.LIB.
1435 Type each input string on a line by itself, terminated by a newline character.
1436 r@"aksm@"org@aa{}s.se
1437 xn--rksmrgs-5wao1o.se
1441 Reading input from command line, and disabling copyright and license
1445 jas@@latte:~$ idn --quiet r@"aksm@"org@aa{}s.se bl@aa{}b@ae{}rgr@o{}d.no
1446 xn--rksmrgs-5wao1o.se
1447 xn--blbrgrd-fxak7p.no
1451 Accessing a specific StringPrep profile directly:
1454 jas@@latte:~$ idn --quiet --profile=SASLprep --stringprep te@ss{}t@ordf{}
1459 @section Troubleshooting
1461 Getting character data encoded right, and making sure Libidn use the
1462 same encoding, can be difficult. The reason for this is that most
1463 systems encode character data in more than one character encoding,
1464 i.e., using @code{UTF-8} together with @code{ISO-8859-1} or
1465 @code{ISO-2022-JP}. This problem is likely to continue to exist until
1466 only one character encoding come out as the evolutionary winner, or
1467 (more likely, at least to some extents) forever.
1469 The first step to troubleshooting character encoding problems with
1470 Libidn is to use the @samp{--debug} parameter to find out which
1471 character set encoding @samp{idn} believe your locale uses.
1474 jas@@latte:~$ idn --debug --quiet ""
1475 system locale uses charset `UTF-8'.
1480 If it prints @code{ANSI_X3.4-1968} (i.e., @code{US-ASCII}), this
1481 indicate you have not configured your locale properly. To configure
1482 the locale, you can, for example, use @samp{LANG=sv_SE.UTF-8; export
1483 LANG} at a @code{/bin/sh} prompt, to set up your locale for a Swedish
1484 environment using @code{UTF-8} as the encoding.
1486 Sometimes @samp{idn} appear to be unable to translate from your system
1487 locale into @code{UTF-8} (which is used internally), and you get an
1488 error like the following:
1491 jas@@latte:~$ idn --quiet foo
1492 idn: could not convert from ISO-8859-1 to UTF-8.
1496 The simplest explanation is that you haven't installed the
1497 @samp{iconv} conversion tools. You can find it as a standalone
1498 library in @acronym{GNU} Libiconv
1499 (@uref{http://www.gnu.org/software/libiconv/}). On many
1500 @acronym{GNU}/Linux systems, this library is part of the system, but
1501 you may have to install additional packages (e.g., @samp{glibc-locale}
1502 for Debian) to be able to use it.
1504 Another explanation is that the error is correct and you are feeding
1505 @samp{idn} invalid data. This can happen inadvertently if you are not
1506 careful with the character set encodings you use. For example, if
1507 your shell run in a @code{ISO-8859-1} environment, and you invoke
1508 @samp{idn} with the @samp{CHARSET} environment variable as follows,
1509 you will feed it @code{ISO-8859-1} characters but force it to believe
1510 they are @code{UTF-8}. Naturally this will lead to an error, unless
1511 the byte sequences happen to be parsable as @code{UTF-8}. Note that
1512 even if you don't get an error, the output may be incorrect in this
1513 situation, because @code{ISO-8859-1} and @code{UTF-8} does not in
1514 general encode the same characters as the same byte sequences.
1517 jas@@latte:~$ idn --quiet --debug ""
1518 system locale uses charset `ISO-8859-1'.
1520 jas@@latte:~$ CHARSET=UTF-8 idn --quiet --debug r@"aksm@"org@aa{}s
1521 system locale uses charset `UTF-8'.
1550 The sense moral here is to forget about @samp{CHARSET} (configure your
1551 locales properly instead) unless you know what you are doing, and if
1552 you want to use it, do it carefully, after verifying with
1553 @samp{--debug} that you get the desired results.
1558 Included in Libidn are @file{punycode.el} and @file{idna.el} that
1559 provides an Emacs Lisp API to (a limited set of) the Libidn API. This
1560 section describes the API. Currently the IDNA API always set the
1561 @code{UseSTD3ASCIIRules} flag and clear the @code{AllowUnassigned}
1562 flag, in the future there may be functionality to specify these flags
1565 @section Punycode Emacs API
1567 @defvar punycode-program
1568 Name of the GNU Libidn @file{idn} application. The default is
1569 @samp{idn}. This variable can be customized.
1572 @defvar punycode-environment
1573 List of environment variable definitions prepended to
1574 @samp{process-environment}. The default is @samp{("CHARSET=UTF-8")}.
1575 This variable can be customized.
1578 @defvar punycode-encode-parameters
1579 List of parameters passed to @var{punycode-program} to invoke punycode
1580 encoding mode. The default is @samp{("--quiet" "--punycode-encode")}.
1581 This variable can be customized.
1584 @defvar punycode-decode-parameters
1585 Parameters passed to @var{punycode-program} to invoke punycode
1586 decoding mode. The default is @samp{("--quiet" "--punycode-decode")}.
1587 This variable can be customized.
1590 @defun punycode-encode string
1591 Returns a Punycode encoding of the @var{string}, after converting the
1595 @defun punycode-decode string
1596 Returns a possibly multibyte string which is the decoding of the
1597 @var{string} which is a punycode encoded string.
1600 @section IDNA Emacs API
1602 @defvar idna-program
1603 Name of the GNU Libidn @file{idn} application. The default is
1604 @samp{idn}. This variable can be customized.
1607 @defvar idna-environment
1608 List of environment variable definitions prepended to
1609 @samp{process-environment}. The default is @samp{("CHARSET=UTF-8")}.
1610 This variable can be customized.
1613 @defvar idna-to-ascii-parameters
1614 List of parameters passed to @var{idna-program} to invoke IDNA ToASCII
1615 mode. The default is @samp{("--quiet" "--idna-to-ascii"
1616 "--usestd3asciirules")}. This variable can be customized.
1619 @defvar idna-to-unicode-parameters
1620 Parameters passed @var{idna-program} to invoke IDNA ToUnicode mode.
1621 The default is @samp{("--quiet" "--idna-to-unicode"
1622 "--usestd3asciirules")}. This variable can be customized.
1625 @defun idna-to-ascii string
1626 Returns an ASCII Compatible Encoding (ACE) of the string computed by
1627 the IDNA ToASCII operation on the input @var{string}, after converting
1631 @defun idna-to-unicode string
1632 Returns a possibly multibyte string which is the output of the IDNA
1633 ToUnicode operation computed on the input @var{string}.
1636 @c **********************************************************
1637 @c ******************* Acknowledgements *******************
1638 @c **********************************************************
1639 @node Acknowledgements
1640 @chapter Acknowledgements
1642 The punycode code was taken from the IETF IDN Punycode specification,
1643 by Adam M. Costello. The TLD code was contributed by Thomas Jacob.
1644 Some functions for dealing with Unicode (see nfkc.c and toutf8.c) has
1645 been borrowed from GLib downloaded from www.gtk.org.
1647 Several people reported bugs, sent patches or suggested improvements,
1648 see the file THANKS in the top-level directory of the source code.
1651 @unnumbered Concept Index
1655 @node Function and Variable Index
1656 @unnumbered Function and Variable Index
1662 @node Copying This Manual
1663 @appendix Copying This Manual
1666 * GNU Free Documentation License:: License for copying this manual.