Libidn2 - Internationalized Domain Names Library

https://www.gnu.org/software/libidn/libidn2/manual/
Admin
Libidn2 is an Internationalized Domain Names Library that empowers users with free software, built...
Tokens:25,528
Snippets:144
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### ToASCII Example Setup

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Initial setup for a ToASCII conversion example, including necessary headers.

```c
/* 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() */
```

--------------------------------

### ToASCII Conversion Example

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Demonstrates converting UTF-8 domain names to ACE labels using idn2_to_ascii_8z.

```c
/*
 * 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;
}
```

--------------------------------

### ToUnicode Conversion Example

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Demonstrates converting ACE labels back to internationalized domain names in UTF-8 using idn2_to_unicode_8z8z.

```c
/* 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;
}
```

--------------------------------

### ToASCII example: Convert IDN to ACE with idn2_to_ascii_8z()

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/ToASCII.html

Complete C program that reads a UTF-8 domain from stdin, prints its bytes, and converts it to an ACE label using idn2_to_ascii_8z() with IDN2_NONTRANSITIONAL. Compile with pkg-config: cc -o example-toascii example-toascii.c $(pkg-config --cflags --libs libidn2). Expected output shows the input domain and the resulting ACE label.

```c
/* 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;
}

```

--------------------------------

### Process domain name for DNS lookup with idn2_lookup_ul

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Lookup.html

This example reads a domain name from standard input in the locale encoding and converts it for DNS lookup using idn2_lookup_ul. It includes error handling for the conversion process and cleans up allocated memory.

```c
#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;
}
```

--------------------------------

### Convert ACE to Unicode using idn2_to_unicode_8z8z

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/ToUnicode.html

This example reads an ACE-encoded string from standard input and converts it to a UTF-8 internationalized domain name. It includes compilation instructions using pkg-config and demonstrates error handling with idn2_strerror.

```c
/* 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;
}
```

--------------------------------

### Registering a domain label with idn2_register_ul

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Register.html

This example reads a domain label from standard input in the current locale encoding and converts it to an IDNA2008 label using idn2_register_ul. It handles potential errors by checking the return code against IDN2_OK and printing descriptive error messages.

```c
#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;
}
```

--------------------------------

### Example of idn2 conversion error

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

This error message appears when idn2 cannot convert the input string to UTF-8, often due to missing iconv tools or invalid input data.

```text
idn2: lookup: could not convert string to UTF-8
```

--------------------------------

### Set locale with LANG environment variable

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

Example of overriding the system locale using the LANG environment variable before invoking idn2.

```bash
$ LANG=en_US.UTF-8 idn2
...
```

--------------------------------

### Debug output for idn2 processing

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

An example of the verbose output provided by --debug when processing a string, showing the detected charset and internal byte/UCS-4 representations.

```bash
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:~$
```

--------------------------------

### Check Library Version

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Verify that the header file is compatible with the shared library.

```c
if (!idn2_check_version (IDN2_VERSION))
  {
    printf ("idn2_check_version() failed:\n"
            "Header file incompatible with shared library.\n");
    exit(EXIT_FAILURE);
  }
```

--------------------------------

### idn2 command options

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

List of available command-line options for the idn2 utility.

```text
  -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
      --no-tr46             Disable TR46 processing
      --usestd3asciirules   Enable STD3 ASCII rules
      --no-alabelroundtrip  Disable A-label roundtrip for lookups
      --debug               Print debugging information
      --quiet               Silent operation
```

--------------------------------

### Process input from command line

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

Passing domain names directly as arguments to the idn2 command.

```bash
jas@latte:~$ idn2 räksmörgås.se blåbærgrød.no
xn--rksmrgs-5wao1o.se
xn--blbrgrd-fxak7p.no
jas@latte:~$
```

--------------------------------

### idn2_strerror_name

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Library-Functions.html

Converts an internal libidn2 error code to a string corresponding to internal header file symbols. For example, idn2_strerror_name(IDN2_MALLOC) returns the string "IDN2_MALLOC". The caller must not attempt to de-allocate the returned string.

```APIDOC
## idn2_strerror_name

### Description
Convert internal libidn2 error code to a string corresponding to internal header file symbols. For example, idn2_strerror_name(IDN2_MALLOC) will return the string "IDN2_MALLOC". The caller must not attempt to de-allocate the returned string.

### Function Signature
`const char * idn2_strerror_name (int rc)`

### Parameters
- **rc** (int) - Return code from another libidn2 function.

### Return Value
A string corresponding to error code symbol.
```

--------------------------------

### Register domain name

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

Using the --register flag to test the IDNA2008 register function.

```bash
jas@latte:~$ idn2 --register fußball
xn--fuball-cta
jas@latte:~$
```

--------------------------------

### Debug idn2 input processing with LANG

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Demonstrates using the --debug flag to inspect how idn2 processes UTF-8 input when the LANG environment variable is set.

```bash
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:~$
```

--------------------------------

### Include Header

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Library-Functions.html

To use the Libidn2 library functions, include the header file idn2.h.

```APIDOC
## Include Header

### Description
Include the header file `idn2.h` to access all Libidn2 library functions.

### Usage
```c
#include <idn2.h>
```
```

--------------------------------

### Convert idna_to_ascii_8z with other flags to idn2_to_ascii_8z with default flags

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Converting-from-libidn.html

Shows the libidn call with any other flags and the recommended libidn2 call using default flags (0). The comment in the libidn2 version recommends using default flags for default behavior.

```c
rc = idna_to_ascii_8z (buf, &p, 0 /* any other flags */);
if (rc != IDNA_SUCCESS)

```

```c
/* we recommend to use the default flags (0), so that
 * the default behavior of libidn2 applies. */
rc = idn2_to_ascii_8z (buf, &p, 0);
if (rc != IDN2_OK)

```

--------------------------------

### Include idn2.h header

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Library-Functions.html

Required include directive for using Libidn2 functions. Place at the top of your source file.

```c
#include <idn2.h>

```

--------------------------------

### Convert idna_to_unicode_8z8z to idn2_to_unicode_8z8z

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Converting-from-libidn.html

Shows the libidn unicode conversion call and its libidn2 equivalent. The flags are set to 0 in both versions, and the error check changes from IDNA_SUCCESS to IDN2_OK.

```c
rc = idna_to_unicode_8z8z (buf, &p, 0 /* any flags */);
if (rc != IDNA_SUCCESS)

```

```c
rc = idn2_to_unicode_8z8z (buf, &p, 0);
if (rc != IDN2_OK)

```

--------------------------------

### Check system charset with idn2 --debug

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

Use the --debug flag to verify which character set encoding the idn2 tool detects for your current locale.

```bash
jas@latte:~$ idn2 --debug --quiet ""
Charset: UTF-8

jas@latte:~$ 
```

--------------------------------

### Convert idna_to_ascii_8z with IDNA_USE_STD3_ASCII_RULES to idn2_to_ascii_8z

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Converting-from-libidn.html

Shows the libidn call using IDNA_USE_STD3_ASCII_RULES and its libidn2 equivalent using IDN2_USE_STD3_ASCII_RULES. The error check changes from IDNA_SUCCESS to IDN2_OK.

```c
rc = idna_to_ascii_8z (buf, &p, IDNA_USE_STD3_ASCII_RULES);
if (rc != IDNA_SUCCESS)

```

```c
rc = idn2_to_ascii_8z (buf, &p, IDN2_USE_STD3_ASCII_RULES);
if (rc != IDN2_OK)

```

--------------------------------

### Backwards compatible conversion with IDN2_NONTRANSITIONAL and IDN2_TRANSITIONAL

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Converting-from-libidn.html

Attempts IDNA2008 conversion with IDN2_NONTRANSITIONAL, and if it fails with IDN2_DISALLOWED, falls back to IDNA2003-compatible conversion using IDN2_TRANSITIONAL.

```c
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 */

```

--------------------------------

### Return Codes

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

List of all possible return codes from libidn2 functions, each with a description of its meaning.

```APIDOC
## Return Codes

### IDN2_OK
Successful return.

### IDN2_MALLOC
Memory allocation error.

### IDN2_NO_CODESET
Could not determine locale string encoding format.

### IDN2_ICONV_FAIL
Could not transcode locale string to UTF-8.

### IDN2_ENCODING_ERROR
Unicode data encoding error.

### IDN2_NFC
Error normalizing string.

### IDN2_PUNYCODE_BAD_INPUT
Punycode invalid input.

### IDN2_PUNYCODE_BIG_OUTPUT
Punycode output buffer too small.

### IDN2_PUNYCODE_OVERFLOW
Punycode conversion would overflow.

### IDN2_TOO_BIG_DOMAIN
Domain name longer than 255 characters.

### IDN2_TOO_BIG_LABEL
Domain label longer than 63 characters.

### IDN2_INVALID_ALABEL
Input A-label is not valid.

### IDN2_UALABEL_MISMATCH
Input A-label and U-label does not match.

### IDN2_INVALID_FLAGS
Invalid combination of flags.

### IDN2_NOT_NFC
String is not NFC.

### IDN2_2HYPHEN
String has forbidden two hyphens.

### IDN2_HYPHEN_STARTEND
String has forbidden starting/ending hyphen.

### IDN2_LEADING_COMBINING
String has forbidden leading combining character.

### IDN2_DISALLOWED
String has disallowed character.

### IDN2_CONTEXTJ
String has forbidden context-j character.

### IDN2_CONTEXTJ_NO_RULE
String has context-j character with no rull.

### IDN2_CONTEXTO
String has forbidden context-o character.

### IDN2_CONTEXTO_NO_RULE
String has context-o character with no rull.

### IDN2_UNASSIGNED
String has forbidden unassigned character.

### IDN2_BIDI
String has forbidden bi-directional properties.

### IDN2_DOT_IN_LABEL
Label has forbidden dot (TR46).

### IDN2_INVALID_TRANSITIONAL
Label has character forbidden in transitional mode (TR46).

### IDN2_INVALID_NONTRANSITIONAL
Label has character forbidden in non-transitional mode (TR46).
```

--------------------------------

### Process input from standard input

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Invoking-idn2.html

Standard usage of idn2 reading from stdin with the --quiet flag.

```bash
jas@latte:~$ idn2 --quiet
räksmörgås.se
xn--rksmrgs-5wao1o.se
...
```

--------------------------------

### idn2_check_version library version verification

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Library-Functions.html

Checks if the linked Libidn2 library version meets the requirements of the header file version.

```c
const char * idn2_check_version (const char * req_version)
```

```c
  if (!idn2_check_version (IDN2_VERSION))
    {
      printf ("idn2_check_version() failed:\n"
              "Header file incompatible with shared library.\n");
      exit(EXIT_FAILURE);
    }
```

--------------------------------

### idn2_check_version

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Interface-Index.html

Checks the version of the Libidn2 library at runtime.

```APIDOC
## idn2_check_version

### Description
Checks the version of the Libidn2 library at runtime.

### Function
`const char *idn2_check_version(const char *req_version);`

### Parameters
- **req_version** (const char *) - Required - The required version string to compare against.

### Return Value
Returns a pointer to the version string if the library version is compatible, otherwise NULL.
```

--------------------------------

### Backwards Compatible IDNA2008 Conversion

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Convert a domain to IDNA2008 form, falling back to IDNA2003 if the conversion fails.

```c
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 */
```

--------------------------------

### Check idn2 charset detection

Source: https://www.gnu.org/software/libidn/libidn2/manual/libidn2.txt

Displays the charset detected by idn2 when running in a specific shell environment.

```bash
jas@latte:~$ idn2 --quiet --debug ""
Charset: ISO-8859-1
```

--------------------------------

### idn2_to_unicode_lzlz

Source: https://www.gnu.org/software/libidn/libidn2/manual/html_node/Library-Functions.html

Converts a possibly ACE encoded domain name in the locale's character set into a string encoded in the current locale's character set (punycode decoding). The output buffer is zero-terminated and must be deallocated by the caller.

```APIDOC
## idn2_to_unicode_lzlz

### Description
Converts a possibly ACE encoded domain name in the locale's character set into a string encoded in the current locale's character set (punycode decoding). The output buffer will be zero-terminated and must be deallocated by the caller.

### Function Signature
int idn2_to_unicode_lzlz(const char * input, char ** output, int flags)

### Parameters
- **input** (const char *) - Required - Input zero-terminated string encoded in the current locale's character set.
- **output** (char **) - Required - Newly allocated output string in current locale's character set.
- **flags** (int) - Optional - Currently unused.

### Notes
output may be NULL to test lookup of input without allocating memory.

### Since
2.0.0
```
Tokens:
Raw