← Back to branch summary

~ubuntu-branches/ubuntu/trusty/libidn/trusty

« back to all changes in this revision

Viewing changes to doc/libidn.info

  • Committer: Bazaar Package Importer
  • Author(s): Simon Josefsson
  • Date: 2011-03-01 16:14:24 UTC
  • mfrom: (1.2.14 upstream) (3.1.7 sid)
  • Revision ID: james.westby@ubuntu.com-20110301161424-6vh7822t8aderzap
Tags: 1.20-1
* New upstream release.
* Moved from experimental to unstable after testing.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/libidn.info
1
1
This is libidn.info, produced by makeinfo version 4.13 from libidn.texi.
2
2
 
3
 
This manual is last updated 5 February 2010 for version 1.18 of GNU
4
 
Libidn.
 
3
This manual is last updated 1 March 2011 for version 1.20 of GNU Libidn.
5
4
 
6
 
   Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
7
 
Simon Josefsson.
 
5
   Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
 
6
2011 Simon Josefsson.
8
7
 
9
8
     Permission is granted to copy, distribute and/or modify this
10
9
     document under the terms of the GNU Free Documentation License,
34
33
GNU Libidn
35
34
**********
36
35
 
37
 
This manual is last updated 5 February 2010 for version 1.18 of GNU
38
 
Libidn.
 
36
This manual is last updated 1 March 2011 for version 1.20 of GNU Libidn.
39
37
 
40
 
   Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
41
 
Simon Josefsson.
 
38
   Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
 
39
2011 Simon Josefsson.
42
40
 
43
41
     Permission is granted to copy, distribute and/or modify this
44
42
     document under the terms of the GNU Free Documentation License,
174
172
 
175
173
It's thread-safe
176
174
     No global state is kept in the library.  All functions are
177
 
     reentrant.
 
175
     re-entrant.
178
176
 
179
177
It's portable
180
178
     The code is intended to be written in pure ANSI C89.  It has been
223
221
=======================
224
222
 
225
223
Libidn has at some point in time been tested on the following
226
 
platforms.  Online build reports for each platforms and Libidn version
227
 
is available at `http://autobuild.josefsson.org/libidn/'.
 
224
platforms.  Build reports for each platforms and Libidn version is
 
225
available at `http://autobuild.josefsson.org/libidn/'.
228
226
 
229
227
  1. Debian GNU/Linux 3.0 (Woody) 
230
228
 
394
392
 
395
393
   If you are interested, please write to:
396
394
 
397
 
Simon Josefsson Datakonsult
 
395
Simon Josefsson Datakonsult AB
398
396
Hagagatan 24
399
397
113 47 Stockholm
400
398
Sweden
414
412
 
415
413
   `ftp://alpha.gnu.org/pub/gnu/libidn/'
416
414
 
417
 
   The latest version is stored in a file, e.g., `libidn-1.18.tar.gz'
418
 
where the `1.18' value is the highest version number in the directory.
 
415
   The latest version is stored in a file, e.g., `libidn-1.20.tar.gz'
 
416
where the `1.20' value is the highest version number in the directory.
419
417
 
420
418
   The package is then extracted, configured and built like many other
421
419
packages that use Autoconf.  For detailed information on configuring
426
424
and install the package.  You will need a few basic tools, such as
427
425
`sh', `make' and `cc'.
428
426
 
429
 
     $ wget -q ftp://alpha.gnu.org/pub/gnu/libidn/libidn-1.18.tar.gz
430
 
     $ tar xfz libidn-1.18.tar.gz
431
 
     $ cd libidn-1.18/
 
427
     $ wget -q ftp://alpha.gnu.org/pub/gnu/libidn/libidn-1.20.tar.gz
 
428
     $ tar xfz libidn-1.20.tar.gz
 
429
     $ cd libidn-1.20/
432
430
     $ ./configure
433
431
     ...
434
432
     $ make
763
761
path (via the `-L' option).  For this, the option `--libs' to
764
762
`pkg-config libidn' can be used.  For convenience, this option also
765
763
outputs all other options that are required to link the program with
766
 
the `libidn' libarary.  The example shows how to link `foo.o' with the
 
764
the `libidn' library.  The example shows how to link `foo.o' with the
767
765
`libidn' library to a program `foo'.
768
766
 
769
767
     gcc -o foo foo.o `pkg-config libidn --libs`
1568
1566
strings (i.e., Unicode code points encoded in a 32-bit unsigned integer
1569
1567
type) of the specified length.  The `i' indicate that the data is
1570
1568
written "inline" into the buffer.  This means the caller is responsible
1571
 
for allocating (and deallocating) the string, and providing the library
1572
 
with the allocated length of the string.  The output length is written
1573
 
in the output length variable.  The remaining functions all contain the
1574
 
`z' indicator, which means the strings are zero terminated.  All output
1575
 
strings are allocated by the library, and must be deallocated by the
1576
 
caller.  The `4' indicator again means that the string is UCS-4, the
1577
 
`8' means the strings are UTF-8 and the `l' indicator means the strings
1578
 
are encoded in the encoding used by the current locale.
 
1569
for allocating (and de-allocating) the string, and providing the
 
1570
library with the allocated length of the string.  The output length is
 
1571
written in the output length variable.  The remaining functions all
 
1572
contain the `z' indicator, which means the strings are zero terminated.
 
1573
All output strings are allocated by the library, and must be
 
1574
de-allocated by the caller.  The `4' indicator again means that the
 
1575
string is UCS-4, the `8' means the strings are UTF-8 and the `l'
 
1576
indicator means the strings are encoded in the encoding used by the
 
1577
current locale.
1579
1578
 
1580
1579
   The functions provided are the following entry points:
1581
1580
 
1883
1882
Libidn also ship some tables from TLDs that we have managed to get
1884
1883
permission to use them from.  Because these tables are even less static
1885
1884
than Unicode or StringPrep tables, it is likely that they will be
1886
 
updated from time to time (even in backwards incompatibe ways).  The
 
1885
updated from time to time (even in backwards incompatible ways).  The
1887
1886
Libidn interface provide a "version" field for each TLD table, which
1888
1887
can be compared for equality to guarantee the same operation over time.
1889
1888
 
1890
 
   From a design point of view, you can regard the TLD tables for IDN
1891
 
as the "localization" step that come after the "internationalization"
1892
 
step provided by the IETF standards.
 
1889
   From a design point of view, you can regard the TLD tables for IDN as
 
1890
the "localization" step that come after the "internationalization" step
 
1891
provided by the IETF standards.
1893
1892
 
1894
1893
   The TLD functionality rely on up-to-date tables.  The latest version
1895
1894
of Libidn aim to provide these, but tables with unclear copying
2333
2332
This example demonstrates how the stringprep functions are used.
2334
2333
 
2335
2334
/* example.c --- Example code showing how to use stringprep().
2336
 
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
2337
 
 * Simon Josefsson
 
2335
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
 
2336
 * 2011 Simon Josefsson
2338
2337
 *
2339
2338
 * This file is part of GNU Libidn.
2340
2339
 *
2428
2427
This example demonstrates how the punycode functions are used.
2429
2428
 
2430
2429
/* example2.c --- Example code showing how to use punycode.
2431
 
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
2432
 
 * Simon Josefsson
 
2430
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
 
2431
 * 2011 Simon Josefsson
2433
2432
 * Copyright (C) 2002  Adam M. Costello
2434
2433
 *
2435
2434
 * This file is part of GNU Libidn.
2672
2671
internationalized domain names into ASCII compatible names.
2673
2672
 
2674
2673
/* example3.c --- Example ToASCII() code showing how to use Libidn.
2675
 
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Simon Josefsson
 
2674
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
 
2675
 * 2011 Simon Josefsson
2676
2676
 *
2677
2677
 * This file is part of GNU Libidn.
2678
2678
 *
2758
2758
compatible names to internationalized domain names.
2759
2759
 
2760
2760
/* example4.c --- Example ToUnicode() code showing how to use Libidn.
2761
 
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Simon Josefsson
 
2761
 * Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010,
 
2762
 * 2011 Simon Josefsson
2762
2763
 *
2763
2764
 * This file is part of GNU Libidn.
2764
2765
 *
2844
2845
invalid characters within a specific TLD.
2845
2846
 
2846
2847
/* example5.c --- Example TLD checking.
2847
 
 * Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010 Simon
 
2848
 * Copyright (C) 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Simon
2848
2849
 * Josefsson
2849
2850
 *
2850
2851
 * This file is part of GNU Libidn.
3122
3123
 
3123
3124
   Another explanation is that the error is correct and you are feeding
3124
3125
`idn' invalid data.  This can happen inadvertently if you are not
3125
 
careful with the character set encodings you use.  For example, if your
 
3126
careful with the character set encoding you use.  For example, if your
3126
3127
shell run in a `ISO-8859-1' environment, and you invoke `idn' with the
3127
3128
`CHARSET' environment variable as follows, you will feed it
3128
3129
`ISO-8859-1' characters but force it to believe they are `UTF-8'.
3129
3130
Naturally this will lead to an error, unless the byte sequences happen
3130
 
to be parsable as `UTF-8'.  Note that even if you don't get an error,
3131
 
the output may be incorrect in this situation, because `ISO-8859-1' and
 
3131
to be valid `UTF-8'.  Note that even if you don't get an error, the
 
3132
output may be incorrect in this situation, because `ISO-8859-1' and
3132
3133
`UTF-8' does not in general encode the same characters as the same byte
3133
3134
sequences.
3134
3135
 
3255
3256
 
3256
3257
   The Java library, if Libidn has been built with Java support (*note
3257
3258
Downloading and Installing::), will be placed in
3258
 
`java/libidn-1.18.jar'.  The source code is located in
 
3259
`java/libidn-1.20.jar'.  The source code is located in
3259
3260
`java/gnu/inet/encoding/'.
3260
3261
 
3261
3262
12.1 Overview
3321
3322
   The test vectors can be found at the Libidn homepage,
3322
3323
`http://www.gnu.org/software/libidn/'.
3323
3324
 
3324
 
   To test the tranformation manually, use:
 
3325
   To test the transformation manually, use:
3325
3326
 
3326
3327
     $ java -cp .:../libidn.jar TestIDNA -a <string to test>
3327
3328
     Input: <string to test>
3373
3374
12.4 A Note on Java and Unicode
3374
3375
===============================
3375
3376
 
3376
 
This library uses Java's builtin 'char' datatype. Up to Java 1.4, this
 
3377
This library uses Java's built-in 'char' datatype. Up to Java 1.4, this
3377
3378
datatype only supports 16-bit Unicode code points, also called the
3378
3379
Basic Multilingual Plane. For this reason, this library doesn't work
3379
3380
for Supplementary Characters (i.e. characters from U+10000 to
5410
5411
                                                              (line  31)
5411
5412
* idna-to-ascii:                         Emacs API.           (line  65)
5412
5413
* idna-to-unicode:                       Emacs API.           (line  70)
5413
 
* idna_strerror:                         IDNA Functions.      (line 310)
5414
 
* idna_to_ascii_4i:                      IDNA Functions.      (line  68)
5415
 
* idna_to_ascii_4z:                      IDNA Functions.      (line 152)
5416
 
* idna_to_ascii_8z:                      IDNA Functions.      (line 170)
5417
 
* idna_to_ascii_lz:                      IDNA Functions.      (line 188)
5418
 
* idna_to_unicode_44i:                   IDNA Functions.      (line 106)
5419
 
* idna_to_unicode_4z4z:                  IDNA Functions.      (line 210)
5420
 
* idna_to_unicode_8z4z:                  IDNA Functions.      (line 229)
5421
 
* idna_to_unicode_8z8z:                  IDNA Functions.      (line 248)
5422
 
* idna_to_unicode_8zlz:                  IDNA Functions.      (line 267)
5423
 
* idna_to_unicode_lzlz:                  IDNA Functions.      (line 287)
 
5414
* idna_strerror:                         IDNA Functions.      (line 311)
 
5415
* idna_to_ascii_4i:                      IDNA Functions.      (line  69)
 
5416
* idna_to_ascii_4z:                      IDNA Functions.      (line 153)
 
5417
* idna_to_ascii_8z:                      IDNA Functions.      (line 171)
 
5418
* idna_to_ascii_lz:                      IDNA Functions.      (line 189)
 
5419
* idna_to_unicode_44i:                   IDNA Functions.      (line 107)
 
5420
* idna_to_unicode_4z4z:                  IDNA Functions.      (line 211)
 
5421
* idna_to_unicode_8z4z:                  IDNA Functions.      (line 230)
 
5422
* idna_to_unicode_8z8z:                  IDNA Functions.      (line 249)
 
5423
* idna_to_unicode_8zlz:                  IDNA Functions.      (line 268)
 
5424
* idna_to_unicode_lzlz:                  IDNA Functions.      (line 288)
5424
5425
* pr29_4:                                PR29 Functions.      (line  55)
5425
5426
* pr29_4z:                               PR29 Functions.      (line  75)
5426
5427
* pr29_8z:                               PR29 Functions.      (line  90)
5547
5548
 
5548
5549
 
5549
5550
Tag Table:
5550
 
Node: Top1063
5551
 
Node: Introduction2836
5552
 
Node: Getting Started5317
5553
 
Node: Features6424
5554
 
Node: Library Overview7823
5555
 
Node: Supported Platforms8621
 
5551
Node: Top1066
 
5552
Node: Introduction2842
 
5553
Node: Getting Started5323
 
5554
Node: Features6430
 
5555
Node: Library Overview7830
 
5556
Node: Supported Platforms8628
5556
5557
Node: Getting help12200
5557
5558
Node: Commercial Support12663
5558
 
Node: Downloading and Installing13594
5559
 
Node: Installing under Windows15477
5560
 
Node: Bug Reports16857
5561
 
Node: Contributing18247
5562
 
Node: Preparation20219
5563
 
Node: Header20933
5564
 
Node: Initialization23948
5565
 
Node: Version Check24145
5566
 
Ref: stringprep_check_version24680
5567
 
Node: Building the source25645
5568
 
Node: Autoconf tests27506
5569
 
Node: Memory handling under Windows29872
5570
 
Ref: idn_free30820
5571
 
Node: Utility Functions31356
5572
 
Ref: stringprep_unichar_to_utf832020
5573
 
Ref: stringprep_utf8_to_unichar32444
5574
 
Ref: stringprep_ucs4_to_utf832832
5575
 
Ref: stringprep_utf8_to_ucs433710
5576
 
Ref: stringprep_ucs4_nfkc_normalize34463
5577
 
Ref: stringprep_utf8_nfkc_normalize34911
5578
 
Ref: stringprep_locale_charset36069
5579
 
Ref: stringprep_convert37102
5580
 
Ref: stringprep_locale_to_utf837658
5581
 
Ref: stringprep_utf8_to_locale38038
5582
 
Node: Stringprep Functions38386
5583
 
Ref: stringprep_4i40297
5584
 
Ref: stringprep_4zi41885
5585
 
Ref: stringprep43097
5586
 
Ref: stringprep_profile44422
5587
 
Ref: stringprep_strerror45529
5588
 
Node: Punycode Functions49128
5589
 
Ref: punycode_encode50867
5590
 
Ref: punycode_decode53062
5591
 
Ref: punycode_strerror55174
5592
 
Node: IDNA Functions55936
5593
 
Ref: idna_to_ascii_4i58500
5594
 
Ref: idna_to_unicode_44i60130
5595
 
Ref: idna_to_ascii_4z62096
5596
 
Ref: idna_to_ascii_8z62687
5597
 
Ref: idna_to_ascii_lz63272
5598
 
Ref: idna_to_unicode_4z4z64000
5599
 
Ref: idna_to_unicode_8z4z64649
5600
 
Ref: idna_to_unicode_8z8z65292
5601
 
Ref: idna_to_unicode_8zlz65929
5602
 
Ref: idna_to_unicode_lzlz66651
5603
 
Ref: idna_strerror67456
5604
 
Node: TLD Functions69073
5605
 
Ref: tld_check_4t70703
5606
 
Ref: tld_check_4tz71603
5607
 
Ref: tld_get_472457
5608
 
Ref: tld_get_4z72963
5609
 
Ref: tld_get_z73374
5610
 
Ref: tld_get_table73872
5611
 
Ref: tld_default_table74405
5612
 
Ref: tld_check_475130
5613
 
Ref: tld_check_4z76379
5614
 
Ref: tld_check_8z77545
5615
 
Ref: tld_check_lz78812
5616
 
Ref: tld_strerror80150
5617
 
Node: PR29 Functions80973
5618
 
Ref: pr29_483261
5619
 
Ref: pr29_4z83892
5620
 
Ref: pr29_8z84416
5621
 
Ref: pr29_strerror85075
5622
 
Node: Examples85801
5623
 
Node: Example 186250
5624
 
Node: Example 288780
5625
 
Node: Example 395422
5626
 
Node: Example 497956
5627
 
Node: Example 5100499
5628
 
Node: Invoking idn103955
5629
 
Node: Emacs API111277
5630
 
Node: Java API114034
5631
 
Node: C# API118938
5632
 
Node: Acknowledgements119403
5633
 
Node: History120505
5634
 
Node: PR29 discussion122149
5635
 
Node: On Label Separators126017
5636
 
Ref: On Label Separators-Footnote-1128491
5637
 
Node: Copying Information128584
5638
 
Node: GNU Free Documentation License128991
5639
 
Node: GNU LGPL154141
5640
 
Node: GNU GPL182316
5641
 
Node: Function and Variable Index219860
5642
 
Node: Concept Index224846
 
5559
Node: Downloading and Installing13597
 
5560
Node: Installing under Windows15480
 
5561
Node: Bug Reports16860
 
5562
Node: Contributing18250
 
5563
Node: Preparation20222
 
5564
Node: Header20936
 
5565
Node: Initialization23951
 
5566
Node: Version Check24148
 
5567
Ref: stringprep_check_version24683
 
5568
Node: Building the source25648
 
5569
Node: Autoconf tests27508
 
5570
Node: Memory handling under Windows29874
 
5571
Ref: idn_free30822
 
5572
Node: Utility Functions31358
 
5573
Ref: stringprep_unichar_to_utf832022
 
5574
Ref: stringprep_utf8_to_unichar32446
 
5575
Ref: stringprep_ucs4_to_utf832834
 
5576
Ref: stringprep_utf8_to_ucs433712
 
5577
Ref: stringprep_ucs4_nfkc_normalize34465
 
5578
Ref: stringprep_utf8_nfkc_normalize34913
 
5579
Ref: stringprep_locale_charset36071
 
5580
Ref: stringprep_convert37104
 
5581
Ref: stringprep_locale_to_utf837660
 
5582
Ref: stringprep_utf8_to_locale38040
 
5583
Node: Stringprep Functions38388
 
5584
Ref: stringprep_4i40299
 
5585
Ref: stringprep_4zi41887
 
5586
Ref: stringprep43099
 
5587
Ref: stringprep_profile44424
 
5588
Ref: stringprep_strerror45531
 
5589
Node: Punycode Functions49130
 
5590
Ref: punycode_encode50869
 
5591
Ref: punycode_decode53064
 
5592
Ref: punycode_strerror55176
 
5593
Node: IDNA Functions55938
 
5594
Ref: idna_to_ascii_4i58503
 
5595
Ref: idna_to_unicode_44i60133
 
5596
Ref: idna_to_ascii_4z62099
 
5597
Ref: idna_to_ascii_8z62690
 
5598
Ref: idna_to_ascii_lz63275
 
5599
Ref: idna_to_unicode_4z4z64003
 
5600
Ref: idna_to_unicode_8z4z64652
 
5601
Ref: idna_to_unicode_8z8z65295
 
5602
Ref: idna_to_unicode_8zlz65932
 
5603
Ref: idna_to_unicode_lzlz66654
 
5604
Ref: idna_strerror67459
 
5605
Node: TLD Functions69076
 
5606
Ref: tld_check_4t70707
 
5607
Ref: tld_check_4tz71607
 
5608
Ref: tld_get_472461
 
5609
Ref: tld_get_4z72967
 
5610
Ref: tld_get_z73378
 
5611
Ref: tld_get_table73876
 
5612
Ref: tld_default_table74409
 
5613
Ref: tld_check_475134
 
5614
Ref: tld_check_4z76383
 
5615
Ref: tld_check_8z77549
 
5616
Ref: tld_check_lz78816
 
5617
Ref: tld_strerror80154
 
5618
Node: PR29 Functions80977
 
5619
Ref: pr29_483265
 
5620
Ref: pr29_4z83896
 
5621
Ref: pr29_8z84420
 
5622
Ref: pr29_strerror85079
 
5623
Node: Examples85805
 
5624
Node: Example 186254
 
5625
Node: Example 288790
 
5626
Node: Example 395438
 
5627
Node: Example 497981
 
5628
Node: Example 5100533
 
5629
Node: Invoking idn103995
 
5630
Node: Emacs API111310
 
5631
Node: Java API114067
 
5632
Node: C# API118973
 
5633
Node: Acknowledgements119438
 
5634
Node: History120540
 
5635
Node: PR29 discussion122184
 
5636
Node: On Label Separators126052
 
5637
Ref: On Label Separators-Footnote-1128526
 
5638
Node: Copying Information128619
 
5639
Node: GNU Free Documentation License129026
 
5640
Node: GNU LGPL154176
 
5641
Node: GNU GPL182351
 
5642
Node: Function and Variable Index219895
 
5643
Node: Concept Index224881
5643
5644
 
5644
5645
End Tag Table
5645
5646