dwww Home | Manual pages | Find package

Net::LibIDN2(3pm)     User Contributed Perl Documentation     Net::LibIDN2(3pm)

NAME
       Net::LibIDN2 - Perl bindings for GNU Libidn2

SYNOPSIS
         use Net::LibIDN2 ':all';
         use Encode;

         idn2_lookup_u8(Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li.de"))
           eq 'xn--mli-5ka8l.de';

         idn2_register_u8(
           Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li"),
           "xn--mli-5ka8l"
         ) eq 'xn--mli-5ka8l';

         Encode::decode_utf8(idn2_to_unicode_88("xn--mli-5ka8l.de"))
           eq "m\N{U+00FC}\N{U+00DF}li.de"

DESCRIPTION
       Provides bindings for GNU Libidn2, a C library for handling
       internationalized domain names based on IDNA 2008, Punycode and TR46.

   Functions
       Net::LibIDN2::idn2_lookup_u8($src, [$flags, [$rc]]);
           Alternative name idn2_to_ascii_8.

           Perform  IDNA2008  lookup  string conversion on domain name $src, as
           described in section 5 of RFC 5891. Note that the input string  must
           be encoded in UTF-8 and be in Unicode NFC form.

           Pass  IDN2_NFC_INPUT  in  $flags to convert input to NFC form before
           further processing. IDN2_TRANSITIONAL  and  IDN2_NONTRANSITIONAL  do
           already imply IDN2_NFC_INPUT.

           Pass IDN2_ALABEL_ROUNDTRIP in flags to convert any input A-labels to
           U-labels  and  perform  additional  testing. This is default if used
           with a libidn2 version >= 2.2. To switch  this  behavior  off,  pass
           IDN2_NO_ALABEL_ROUNDTRIP.

           Pass   IDN2_TRANSITIONAL   to   enable   Unicode  TR46  transitional
           processing, and IDN2_NONTRANSITIONAL to  enable  Unicode  TR46  non-
           transitional processing.

           Multiple  flags may be specified by binary or:ing them together, for
           example IDN2_NFC_INPUT | IDN2_ALABEL_ROUNDTRIP.

           If   linked   to   library   GNU   Libidn2    version    >    2.0.3:
           IDN2_USE_STD3_ASCII_RULES  disabled  by default.  Previously we were
           eliminating  non-STD3  characters  from  domain  strings   such   as
           _443._tcp.example.com,   or   IPs  1.2.3.4/24  provided  to  libidn2
           functions.  That  was  an  unexpected  regression  for  applications
           switching  from libidn2 and thus it is no longer applied by default.
           Use IDN2_USE_STD3_ASCII_RULES to enable that behavior again.

           On error, returns undef. If a scalar variable is  provided  in  $rc,
           returns the internal libidn2 C library result code as well.

       Net::LibIDN2::idn2_lookup_ul($src, [$flags, [$rc]]);
           Alternative name idn2_to_ascii_l.

           Similar  to  function  "idn2_lookup_u8"  but  $src  is assumed to be
           encoded  in  the  locale's  default  coding  system,  and  will   be
           transcoded to UTF-8 and NFC normalized before returning the result.

       Net::LibIDN2::idn2_register_u8($ulabel, [$alabel, [$flags, [$rc]]]);
           Perform  IDNA2008 register string conversion on domain label $ulabel
           and $alabel, as described in section 4 of RFC 5891.  Note  that  the
           input ulabel must be encoded in UTF-8 and be in Unicode NFC form.

           Pass  IDN2_NFC_INPUT  in $flags to convert input $ulabel to NFC form
           before further processing.

           It is recommended to supply both  $ulabel  and  $alabel  for  better
           error checking, but supplying just one of them will work. Passing in
           only $alabel is better than only $ulabel. See RFC 5891 section 4 for
           more information.

           On  error,  returns  undef. If a scalar variable is provided in $rc,
           returns the internal libidn2 C library result code as well.

       Net::LibIDN2::idn2_register_ul($ulabel, [$alabel, [$flags, [$rc]]]);
           Similar to function "idn2_register_u8" but $ulabel is assumed to  be
           encoded   in  the  locale's  default  coding  system,  and  will  be
           transcoded to UTF-8 and NFC normalized before returning the result.

       Net::LibIDN2::idn2_to_unicode_88($input, [$flags, [$rc]]);
           Converts a possibly ACE encoded domain name in UTF-8 format  into  a
           an UTF-8 encoded string (punycode decoding).

           On  error,  returns  undef. If a scalar variable is provided in $rc,
           returns the internal libidn2 C library result code as well.

       Net::LibIDN2::idn2_to_unicode_8l($input, [$flags, [$rc]]);
           Similar to function "idn2_to_unicode_88" but  the  return  value  is
           encoded in the locale's default coding system.

       Net::LibIDN2::idn2_to_unicode_ll($input, [$flags, [$rc]]);
           Similar  to function "idn2_to_unicode_8l" but $input is also assumed
           to be encoded in the locale's default coding system.

       Net::LibIDN2::idn2_strerror($rc);
           Convert internal libidn2 error code $rc to a human-readable string.

       Net::LibIDN2::idn2_strerror_name($rc);
           Convert internal libidn2 error code $rc to a string corresponding to
           internal header file symbols names like IDN2_MALLOC.

       Net::LibIDN2::idn2_check_version([$req_version])
           Checks that the version of the  underlying  IDN2  C  library  is  at
           minimum the one given as a string in $req_version and if that is the
           case  returns the actual version string  of the underlying C library
           or undef if the condition is not met. If no parameter is  passed  to
           this  function  no  check  is  done  and only the version  string is
           returned.

           See IDN2_VERSION for a suitable $req_version string, it  corresponds
           to   the  idn2.h  C header file version at compile time of this Perl
           module.  Normally these  two  version  numbers  match,  but  if  you
           compiled  this Perl module against an older libidn2  and then run it
           with a newer libidn2 shared library, they will be different.

   Constants
       IDN2_VERSION
           Pre-processor symbol with a string that describes the C header  file
           version  number  at  compile time of this Perl module. Used together
           with idn2_check_version() to verify header file and run-time library
           consistency.

       IDN2_VERSION_NUMBER
           Pre-processor symbol with  a  hexadecimal  value  describing  the  C
           header  file version number at compile time of this Perl module. For
           example, when the header version is 1.2.4711 this symbol  will  have
           the  value  0x01021267.  The  last four digits are used to enumerate
           development snapshots, but for all  public  releases  they  will  be
           0000.

       IDN2_VERSION_MAJOR
           Pre-processor  symbol  for  the major version number (decimal).  The
           version scheme is major.minor.patchlevel.

       IDN2_VERSION_MINOR
           Pre-processor symbol for the minor version  number  (decimal).   The
           version scheme is major.minor.patchlevel.

       IDN2_VERSION_PATCH
           Pre-processor  symbol  for  the  patch  level number (decimal).  The
           version scheme is major.minor.patchlevel.

       IDN2_LABEL_MAX_LENGTH
           Constant specifying  the  maximum  length  of  a  DNS  label  to  63
           characters, as specified in RFC 1034.

       IDN2_DOMAIN_MAX_LENGTH
           Constant  specifying  the maximum size of the wire encoding of a DNS
           domain to 255 characters, as specified in RFC 1034.  Note  that  the
           usual  printed  representation  of  a  domain name is limited to 253
           characters if it does not end with a period or 254 characters if  it
           ends with a period.

   Result codes
       "Net::LibIDN2::IDN2_OK" Successful return.
       "Net::LibIDN2::IDN2_MALLOC" Memory allocation error.
       "Net::LibIDN2::IDN2_NO_CODESET" Could not determine locale string
       encoding format.
       "Net::LibIDN2::IDN2_ICONV_FAIL" Could not transcode locale string to
       UTF-8.
       "Net::LibIDN2::IDN2_ENCODING_ERROR" Unicode data encoding error.
       "Net::LibIDN2::IDN2_NFC" Error normalizing string.
       "Net::LibIDN2::IDN2_PUNYCODE_BAD_INPUT" Punycode invalid input.
       "Net::LibIDN2::IDN2_PUNYCODE_BIG_OUTPUT" Punycode output buffer too
       small.
       "Net::LibIDN2::IDN2_PUNYCODE_OVERFLOW" Punycode conversion would
       overflow.
       "Net::LibIDN2::IDN2_TOO_BIG_DOMAIN" Domain name longer than 255
       characters.
       "Net::LibIDN2::IDN2_TOO_BIG_LABEL" Domain label longer than 63
       characters.
       "Net::LibIDN2::IDN2_INVALID_ALABEL" Input A-label is not valid.
       "Net::LibIDN2::IDN2_UALABEL_MISMATCH" Input A-label and U-label does not
       match.
       "Net::LibIDN2::IDN2_NOT_NFC" String is not NFC.
       "Net::LibIDN2::IDN2_2HYPHEN" String has forbidden two hyphens.
       "Net::LibIDN2::IDN2_HYPHEN_STARTEND" String has forbidden
       starting/ending hyphen.
       "Net::LibIDN2::IDN2_LEADING_COMBINING" String has forbidden leading
       combining character.
       "Net::LibIDN2::IDN2_DISALLOWED" String has disallowed character.
       "Net::LibIDN2::IDN2_CONTEXTJ" String has forbidden context-j character.
       "Net::LibIDN2::IDN2_CONTEXTJ_NO_RULE" String has context-j character
       with no rule.
       "Net::LibIDN2::IDN2_CONTEXTO" String has forbidden context-o character.
       "Net::LibIDN2::IDN2_CONTEXTO_NO_RULE" String has context-o character
       with no rule.
       "Net::LibIDN2::IDN2_UNASSIGNED" String has forbidden unassigned
       character.
       "Net::LibIDN2::IDN2_BIDI" String has forbidden bi-directional
       properties.
       "Net::LibIDN2::IDN2_DOT_IN_LABEL" Label has forbidden dot (TR46).
       "Net::LibIDN2::IDN2_INVALID_TRANSITIONAL" Label has character forbidden
       in transitional mode (TR46).
       "Net::LibIDN2::IDN2_INVALID_NONTRANSITIONAL" Label has character
       forbidden in non-transitional mode (TR46).

AUTHOR
       Thomas Jacob, https://github.com/gnuthor

SEE ALSO
       perl(1), RFC 5890-5893, TR 46, https://gitlab.com/libidn/libidn2.

perl v5.40.0                       2024-10-15                 Net::LibIDN2(3pm)

Generated by dwww version 1.16 on Fri Nov 6 04:45:04 CET 2026.