This is libidn.info, produced by makeinfo version 4.13 from libidn.texi.
This manual is last updated 28 May 2009 for version 1.15 of GNU Libidn.
Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Simon
Josefsson.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Software libraries
START-INFO-DIR-ENTRY
* libidn: (libidn). Internationalized string processing library.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Localization
START-INFO-DIR-ENTRY
* idn: (libidn)Invoking idn. Internationalized Domain Name (IDN) string conversion.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Emacs
START-INFO-DIR-ENTRY
* IDN Library: (libidn)Emacs API. Emacs API for IDN functions.
END-INFO-DIR-ENTRY
File: libidn.info, Node: Top, Next: Introduction, Up: (dir)
GNU Libidn
**********
This manual is last updated 28 May 2009 for version 1.15 of GNU Libidn.
Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Simon
Josefsson.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.3 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License".
* Menu:
* Introduction:: How to use this manual.
* Preparation:: What you should do before using the library.
* Utility Functions:: Unicode transformation utility functions.
* Stringprep Functions:: Stringprep functions.
* Punycode Functions:: Punycode functions.
* IDNA Functions:: IDNA functions.
* TLD Functions:: TLD functions.
* PR29 Functions:: Detect strings non-idempotent under NFKC.
* Examples:: Demonstrate how to use the library.
* Invoking idn:: Command line interface to the library.
* Emacs API:: Emacs Lisp API for Libidn.
* Java API:: Notes on the Java port of Libidn.
* C# API:: Notes on the C# port of Libidn.
* Acknowledgements:: Whom to blame.
* History:: Rough outline of development history.
Appendices
* PR29 discussion:: Implementation aspects of the PR29 flaw.
* On Label Separators:: Discussions of a flaw in the IDNA spec.
* Copying Information:: License text covering the Libidn library.
Indices
* Function and Variable Index::
* Concept Index::
File: libidn.info, Node: Introduction, Next: Preparation, Prev: Top, Up: Top
1 Introduction
**************
GNU Libidn is a fully documented implementation of the Stringprep,
Punycode and IDNA specifications. Libidn's purpose is to encode and
decode internationalized domain names. The native C, C# and Java
libraries are available under the GNU Lesser General Public License
version 2.1 or later (*note GNU LGPL::).
The library contains a generic Stringprep implementation. Profiles
for Nameprep, iSCSI, SASL, XMPP and Kerberos V5 are included. Punycode
and ASCII Compatible Encoding (ACE) via IDNA are supported. A
mechanism to define Top-Level Domain (TLD) specific validation tables,
and to compare strings against those tables, is included. Default
tables for some TLDs are also included.
The Stringprep API consists of two main functions, one for converting
data from the system's native representation into UTF-8, and one
function to perform the Stringprep processing. Adding a new Stringprep
profile for your application within the API is straightforward. The
Punycode API consists of one encoding function and one decoding
function. The IDNA API consists of the ToASCII and ToUnicode
functions, as well as an high-level interface for converting entire
domain names to and from the ACE encoded form. The TLD API consists of
one set of functions to extract the TLD name from a domain string, one
set of functions to locate the proper TLD table to use based on the TLD
name, and core functions to validate a string against a TLD table, and
some utility wrappers to perform all the steps in one call.
The library is used by, e.g., GNU SASL and Shishi to process user
names and passwords. Libidn can be built into GNU Libc to enable a new
system-wide getaddrinfo flag for IDN processing.
Libidn is developed for the GNU/Linux system, but runs on over 20
Unix platforms (including Solaris, IRIX, AIX, and Tru64) and Windows.
The library is written in C and (parts of) the API is also accessible
from C++, Emacs Lisp, Python and Java. A native Java and C# port is
included.
Also included is a command line tool, several self tests, code
examples, and more, all licensed under the GNU General Public License
version 3.0 or later (*note GNU GPL::).
* Menu:
* Getting Started::
* Features::
* Library Overview::
* Supported Platforms::
* Getting help::
* Commercial Support::
* Downloading and Installing::
* Bug Reports::
* Contributing::
File: libidn.info, Node: Getting Started, Next: Features, Up: Introduction
1.1 Getting Started
===================
This manual documents the library programming interface. All functions
and data types provided by the library are explained. Included are
also examples, and documentation for the command line tool `idn' that
provide a quick interface to the library. The Emacs Lisp bindings for
the library is also discussed.
The reader is assumed to possess basic familiarity with
internationalization concepts and network programming in C or C++.
This manual can be used in several ways. If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application. Forward references are included where
necessary. Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library. Experienced programmers might want to start looking at the
examples at the end of the manual (*note Examples::), and then only
read up those parts of the interface which are unclear.
File: libidn.info, Node: Features, Next: Library Overview, Prev: Getting Started, Up: Introduction
1.2 Features
============
This library might have a couple of advantages over other libraries
doing a similar job.
It's Free Software
Anybody can use, modify, and redistribute it under the terms of the
GNU Lesser General Public License version 2.1 or later (*note GNU
LGPL::).
It's thread-safe
No global state is kept in the library. All functions are
reentrant.
It's portable
The code is intended to be written in pure ANSI C89. It has been
tested on many Unix like operating systems, and Windows.
It's modularized
The library is composed of several modules, and the only
interaction between modules is through each modules' public API.
If you only need one piece of functionality, it is possible to
take the files you need and incorporate them into your own project.
It's not bloated
The design of the library is based on the smallest API necessary to
implement the basic functionality. It has been carefully extended
with a small number of high-level wrappers to make it comfortable
to use the library. However, it does not implement additional
functionality just for the sake of completeness.
It's documented
Sadly, not all software comes with documentation these days. This
one does.
File: libidn.info, Node: Library Overview, Next: Supported Platforms, Prev: Features, Up: Introduction
1.3 Library Overview
====================
The following illustration show the components that make up Libidn, and
how your application relates to the library. In the illustration,
various components are shown as boxes. You see the generic StringPrep
component, the various StringPrep profiles including Nameprep, the
Punycode component, the IDNA component, and the TLD component. The
arrows indicate aggregation, e.g., IDNA uses Punycode and Nameprep, and
in turn Nameprep uses the generic StringPrep interface. The interfaces
to all components are available for applications, no component within
the library is hidden from the application.
| 