Software: Apache. PHP/7.3.33 uname -a: Linux web25.us.cloudlogin.co 5.10.237-xeon-hst #1 SMP Mon May 5 15:10:04 UTC 2025 x86_64 uid=233359(alpastrology) gid=888(tty) groups=888(tty),33(tape) Safe-mode: OFF (not secure) /usr/share/doc/libidn2-devel/ drwxr-xr-x | |
| Viewing file: Select action/file-type: Libidn2 2.2.0Table of ContentsNext: Introduction, Up: (dir) [Contents][Index] Libidn2This manual is for Libidn2 (version 2.2.0, 4 January 2019), an implementation of IDNA2008/TR46 internationalized domain names. Copyright © 2011-2017 Simon Josefsson
Next: Library Functions, Previous: Top, Up: Top [Contents][Index] 1 IntroductionLibidn2 is a free software implementation of IDNA2008, Punycode and TR46 in the form a library. It contains functionality to convert internationalized domain names to and from ASCII Compatible Encoding (ACE), following the IDNA2008 and TR46 standards. It is available at https://gitlab.com/libidn/libidn2. The library is a rewrite of the popular but legacy libidn library, and is backwards (API) compatible with it. See Converting from libidn for more information. For technical reference on IDNA protocols, see
Libidn2 uses GNU libunistring (https://www.gnu.org/software/libunistring/) for Unicode processing and optionally GNU libiconv (https://www.gnu.org/software/libiconv/) for character set conversion. The library is dual-licensed under LGPLv3 or GPLv2, see the file COPYING for detailed information. Next: Converting from libidn, Previous: Introduction, Up: Top [Contents][Index] 2 Library FunctionsBelow are the interfaces of the Libidn2 library documented. 2.1 Header file
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| libidn | libidn2 |
|---|---|
rc = idna_to_ascii_8z (buf, &p, 0 /* any flags */); if (rc != IDNA_SUCCESS) | /* The flag IDN2_NONTRANSITIONAL is the default under * libidn2 2.0.5 or later; we specify it explicitly * for earlier versions. */ rc = idn2_to_ascii_8z (buf, &p, IDN2_NONTRANSITIONAL); if (rc != IDN2_OK) |
rc = idna_to_unicode_8z8z (buf, &p, 0 /* any flags */); if (rc != IDNA_SUCCESS) | rc = idn2_to_unicode_8z8z (buf, &p, 0); if (rc != IDN2_OK) |
Note that, although the table only lists the UTF-8 functions, the mapping
is identical for every other one on the family of toUnicode and toAscii.
As the IDNA2003 details differ signicantly to IDNA2008, not all flags used in
the libidn functions map to any specific flags; it is typically safe to use
the suggested libidn2 flags. Exceptionally the libidn flag IDNA_USE_STD3_ASCII_RULES
is mapped to IDN2_USE_STD3_ASCII_RULES.
3.3 Converting with backwards compatibility
In several cases where IDNA2008 mappings do not exist whereas IDNA2003 mappings do, software like browsers take a backwards compatible approach. That is convert the domain to IDNA2008 form, and if that fails try the IDNA2003 conversion. The following example demonstrates that approach.
rc = idn2_to_ascii_8z (buf, &p, IDN2_NONTRANSITIONAL); /* IDNA2008 */ if (rc == IDN2_DISALLOWED) rc = idn2_to_ascii_8z (buf, &p, IDN2_TRANSITIONAL); /* IDNA2003 - compatible */
3.4 Using libidn and libidn2 code
In the special case of software that needs to support both
libraries (e.g., both IDNA2003 and IDNA2008), you must define
IDN2_SKIP_LIBIDN_COMPAT prior to including idn2.h
in order to disable compatibility code which overlaps with libidn
functionality. That would allow software to use both libraries’ functions.
3.5 Stringprep and libidn2
The original libidn library includes functionality for the stringprep
processing in stringprep.h. That functionality was an integral part
of an IDNA2003 implementation, but it does not apply to IDNA2008. Furthermore,
stringprep processing has been replaced by the PRECIS framework (RFC8264).
For the reasons above, libidn2 does not implement stringprep or any other string processing protocols unrelated to IDNA2008. Applications requiring the stringprep processing should continue using the original libidn, and new applications should consider using the PRECIS framework.
Next: Invoking idn2, Previous: Converting from libidn, Up: Top [Contents][Index]
4 Examples
This chapter contains example code which illustrate how Libidn2 is used when you write your own application.
| • ToASCII: | Example using IDNA ToASCII. | |
| • ToUnicode: | Example using IDNA ToUnicode. | |
| • Lookup: | Example IDNA2008 Lookup domain name operation. | |
| • Register: | Example IDNA2008 Register label operation. |
4.1 ToASCII example
This example demonstrates how the library is used to convert internationalized domain names into ASCII compatible names (ACE). It expects input to be in UTF-8 form.
/* example-toascii.c --- Example ToASCII() code showing how to use Libidn2.
*
* This code is placed under public domain.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <idn2.h> /* idn2_to_ascii_8z() */
/*
* Compiling using pkg-config is recommended:
*
* $ cc -o example-toascii example-toascii.c $(pkg-config --cflags --libs libidn2)
* $ ./example-toascii
* Input domain encoded as `UTF-8': βόλος.com
* Read string (length 15): ce b2 cf 8c ce bb ce bf cf 82 2e 63 6f 6d 0a
* ACE label (length 17): 'xn--nxasmm1c.com'
*
*/
int
main (void)
{
char buf[BUFSIZ];
char *p;
int rc;
size_t i;
if (!fgets (buf, BUFSIZ, stdin))
perror ("fgets");
buf[strlen (buf) - 1] = '\0';
printf ("Read string (length %ld): ", (long int) strlen (buf));
for (i = 0; i < strlen (buf); i++)
printf ("%02x ", (unsigned) buf[i] & 0xFF);
printf ("\n");
/* Use non-transitional IDNA2008 */
rc = idn2_to_ascii_8z (buf, &p, IDN2_NONTRANSITIONAL);
if (rc != IDNA_SUCCESS)
{
printf ("ToASCII() failed (%d): %s\n", rc, idn2_strerror (rc));
return EXIT_FAILURE;
}
printf ("ACE label (length %ld): '%s'\n", (long int) strlen (p), p);
free (p); /* or idn2_free() */
return 0;
}
4.2 ToUnicode example
This example demonstrates how the library is used to convert ASCII compatible names (ACE) to internationalized domain names. Both input and output are in UTF-8 form.
/* example-tounicode.c --- Example ToUnicode() code showing how to use Libidn2.
*
* This code is placed under public domain.
*/
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <idn2.h> /* idn2_to_unicode_8z8z() */
/*
* Compiling using pkg-config is recommended:
*
* $ cc -o example-to-unicode example-to-unicode.c $(pkg-config --cflags --libs libidn2)
* $ ./example-tounicode
* Input domain (ACE) encoded as `UTF-8': xn--nxasmm1c.com
*
* Read string (length 16): 78 6e 2d 2d 6e 78 61 73 6d 6d 31 63 2e 63 6f 6d
* ACE label (length 14): 'βόλος.com'
*
*/
int
main (void)
{
char buf[BUFSIZ];
char *p;
int rc;
size_t i;
if (!fgets (buf, BUFSIZ, stdin))
perror ("fgets");
buf[strlen (buf) - 1] = '\0';
printf ("Read string (length %ld): ", (long int) strlen (buf));
for (i = 0; i < strlen (buf); i++)
printf ("%02x ", (unsigned) buf[i] & 0xFF);
printf ("\n");
rc = idn2_to_unicode_8z8z (buf, &p, 0);
if (rc != IDNA_SUCCESS)
{
printf ("ToUnicode() failed (%d): %s\n", rc, idn2_strerror (rc));
return EXIT_FAILURE;
}
printf ("ACE label (length %ld): '%s'\n", (long int) strlen (p), p);
free (p); /* or idn2_free() */
return 0;
}
4.3 Lookup
This example demonstrates how a domain name is processed before it is lookup in the DNS. The input expected is in the locale encoding.
#include <stdio.h> /* printf, fflush, fgets, stdin, perror, fprintf */
#include <string.h> /* strlen */
#include <locale.h> /* setlocale */
#include <stdlib.h> /* free */
#include <idn2.h> /* idn2_lookup_ul, IDN2_OK, idn2_strerror, idn2_strerror_name */
int
main (int argc, char *argv[])
{
int rc;
char src[BUFSIZ];
char *lookupname;
setlocale (LC_ALL, "");
printf ("Enter (possibly non-ASCII) domain name to lookup: ");
fflush (stdout);
if (!fgets (src, sizeof (src), stdin))
{
perror ("fgets");
return 1;
}
src[strlen (src) - 1] = '\0';
rc = idn2_lookup_ul (src, &lookupname, 0);
if (rc != IDN2_OK)
{
fprintf (stderr, "error: %s (%s, %d)\n",
idn2_strerror (rc), idn2_strerror_name (rc), rc);
return 1;
}
printf ("IDNA2008 domain name to lookup in DNS: %s\n", lookupname);
free (lookupname);
return 0;
}
4.4 Register
This example demonstrates how a domain label is processed before it is registered in the DNS. The input expected is in the locale encoding.
#include <stdio.h> /* printf, fflush, fgets, stdin, perror, fprintf */
#include <string.h> /* strlen */
#include <locale.h> /* setlocale */
#include <stdlib.h> /* free */
#include <idn2.h> /* idn2_register_ul, IDN2_OK, idn2_strerror, idn2_strerror_name */
int
main (int argc, char *argv[])
{
int rc;
char src[BUFSIZ];
char *insertname;
setlocale (LC_ALL, "");
printf ("Enter (possibly non-ASCII) label to register: ");
fflush (stdout);
if (!fgets (src, sizeof (src), stdin))
{
perror ("fgets");
return 1;
}
src[strlen (src) - 1] = '\0';
rc = idn2_register_ul (src, NULL, &insertname, 0);
if (rc != IDN2_OK)
{
fprintf (stderr, "error: %s (%s, %d)\n",
idn2_strerror (rc), idn2_strerror_name (rc), rc);
return 1;
}
printf ("IDNA2008 label to register in DNS: %s\n", insertname);
free (insertname);
return 0;
}
Next: Interface Index, Previous: Examples, Up: Top [Contents][Index]
5 Invoking idn2
idn2 translates internationalized domain names to the
IDNA2008 encoded format, either for lookup or registration.
If strings are specified on the command line, they are used as input
and the computed output is printed to standard output stdout.
If no strings are specified on the command line, the program read
data, line by line, from the standard input stdin, and print
the computed output to standard output. What processing is performed
(e.g., lookup or register) is indicated by options. If any errors are
encountered, the execution of the applications is aborted.
All strings are expected to be encoded in the preferred charset used
by your locale. Use --debug to find out what this charset is.
On POSIX systems you may use the LANG environment variable to
specify a different locale.
To process a string that starts with -, for example
-foo, use -- to signal the end of parameters, as in
idn2 -r -- -foo.
5.1 Options
idn2 recognizes these commands:
-h, --help Print help and exit
-V, --version Print version and exit
-d, --decode Decode (punycode) domain name
-l, --lookup Lookup domain name (default)
-r, --register Register label
-T, --tr46t Enable TR46 transitional processing
-N, --tr46nt Enable TR46 non-transitional processing (default)
--no-tr46 Disable TR46 processing
--usestd3asciirules Enable STD3 ASCII rules
--debug Print debugging information
--quiet Silent operation
5.2 Environment Variables
On POSIX systems the LANG environment variable can be used to override the system locale for the command being invoked. The system locale may influence what character set is used to decode data (i.e., strings on the command line or data read from the standard input stream), and to encode data to the standard output. If your system is set up correctly, however, the application will use the correct locale and character set automatically. Example usage:
$ LANG=en_US.UTF-8 idn2 ...
5.3 Examples
Standard usage, reading input from standard input and disabling license and usage instructions:
jas@latte:~$ idn2 --quiet räksmörgås.se xn--rksmrgs-5wao1o.se ...
Reading input from the command line:
jas@latte:~$ idn2 räksmörgås.se blåbærgrød.no xn--rksmrgs-5wao1o.se xn--blbrgrd-fxak7p.no jas@latte:~$
Testing the IDNA2008 Register function:
jas@latte:~$ idn2 --register fußball xn--fuball-cta jas@latte:~$
5.4 Troubleshooting
Getting character data encoded right, and making sure Libidn2 use the
same encoding, can be difficult. The reason for this is that most
systems may encode character data in more than one character encoding,
i.e., using UTF-8 together with ISO-8859-1 or
ISO-2022-JP. This problem is likely to continue to exist until
only one character encoding come out as the evolutionary winner, or
(more likely, at least to some extents) forever.
The first step to troubleshooting character encoding problems with Libidn2 is to use the ‘--debug’ parameter to find out which character set encoding ‘idn2’ believe your locale uses.
jas@latte:~$ idn2 --debug --quiet "" Charset: UTF-8 jas@latte:~$
If it prints ANSI_X3.4-1968 (i.e., US-ASCII), this
indicate you have not configured your locale properly. To configure
the locale, you can, for example, use ‘LANG=sv_SE.UTF-8; export
LANG’ at a /bin/sh prompt, to set up your locale for a Swedish
environment using UTF-8 as the encoding.
Sometimes ‘idn2’ appear to be unable to translate from your
system locale into UTF-8 (which is used internally), and you
will get an error message like this:
idn2: lookup: could not convert string to UTF-8
One explanation is that you didn’t install the ‘iconv’ conversion tools. You can find it as a standalone library in GNU Libiconv (https://www.gnu.org/software/libiconv/). On many GNU/Linux systems, this library is part of the system, but you may have to install additional packages to be able to use it.
Another explanation is that the error is correct and you are feeding
‘idn2’ invalid data. This can happen inadvertently if you are
not careful with the character set encoding you use. For example, if
your shell run in a ISO-8859-1 environment, and you invoke
‘idn2’ with the ‘LANG’ environment variable as follows, you
will feed it ISO-8859-1 characters but force it to believe they
are UTF-8. Naturally this will lead to an error, unless the
byte sequences happen to be valid UTF-8. Note that even if you
don’t get an error, the output may be incorrect in this situation,
because ISO-8859-1 and UTF-8 does not in general encode
the same characters as the same byte sequences.
jas@latte:~$ idn2 --quiet --debug "" Charset: ISO-8859-1 jas@latte:~$ LANG=sv_SE.UTF-8 idn2 --debug räksmörgås Charset: UTF-8 input[0] = 0x72 input[1] = 0xc3 input[2] = 0xa4 input[3] = 0xc3 input[4] = 0xa4 input[5] = 0x6b input[6] = 0x73 input[7] = 0x6d input[8] = 0xc3 input[9] = 0xb6 input[10] = 0x72 input[11] = 0x67 input[12] = 0xc3 input[13] = 0xa5 input[14] = 0x73 UCS-4 input[0] = U+0072 UCS-4 input[1] = U+00e4 UCS-4 input[2] = U+00e4 UCS-4 input[3] = U+006b UCS-4 input[4] = U+0073 UCS-4 input[5] = U+006d UCS-4 input[6] = U+00f6 UCS-4 input[7] = U+0072 UCS-4 input[8] = U+0067 UCS-4 input[9] = U+00e5 UCS-4 input[10] = U+0073 output[0] = 0x72 output[1] = 0xc3 output[2] = 0xa4 output[3] = 0xc3 output[4] = 0xa4 output[5] = 0x6b output[6] = 0x73 output[7] = 0x6d output[8] = 0xc3 output[9] = 0xb6 output[10] = 0x72 output[11] = 0x67 output[12] = 0xc3 output[13] = 0xa5 output[14] = 0x73 UCS-4 output[0] = U+0072 UCS-4 output[1] = U+00e4 UCS-4 output[2] = U+00e4 UCS-4 output[3] = U+006b UCS-4 output[4] = U+0073 UCS-4 output[5] = U+006d UCS-4 output[6] = U+00f6 UCS-4 output[7] = U+0072 UCS-4 output[8] = U+0067 UCS-4 output[9] = U+00e5 UCS-4 output[10] = U+0073 xn--rksmrgs-5waap8p jas@latte:~$
The sense moral here is to forget about ‘LANG’ (instead, configure your system locale properly) unless you know what you are doing, and if you want to use ‘LANG’, do it carefully and after verifying with ‘--debug’ that you get the desired results.
Next: Concept Index, Previous: Invoking idn2, Up: Top [Contents][Index]
Interface Index
| Jump to: | I |
|---|
| Jump to: | I |
|---|
Previous: Interface Index, Up: Top [Contents][Index]
Concept Index
| Jump to: | C E I L |
|---|
| Index Entry | Section | ||
|---|---|---|---|
| | |||
| C | |||
| command line: | Invoking idn2 | ||
| | |||
| E | |||
| Examples: | Examples | ||
| | |||
| I | |||
idn2: | Invoking idn2 | ||
invoking idn2: | Invoking idn2 | ||
| | |||
| L | |||
| libidn: | Converting from libidn | ||
| Library Functions: | Library Functions | ||
| | |||
| Jump to: | C E I L |
|---|
:: Command execute :: | |
--[ c99shell v. 2.0 [PHP 7 Update] [25.02.2019] maintained by KaizenLouie | C99Shell Github | Generation time: 0.0131 ]-- |