Net::LibIDN2(3) User Contributed Perl Documentation Net::LibIDN2(3)
NAME
Net::LibIDN2 - Perl bindings for GNU Libidn2
SYNOPSIS
use Net::LibIDN2 ':all';
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"
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 libidn 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 Libidn 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 libidn 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_u8($ulabel [, $alabel, [$flags, [$rc]]]);
Similar to function "idn2_register_ul" 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 humanly 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::id2n_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 describe 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 rull.
"Net::LibIDN2::IDN2_CONTEXTO" String has forbidden context-o character.
"Net::LibIDN2::IDN2_CONTEXTO_NO_RULE" String has context-o character
with no rull.
"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.28.2 2019-11-11 Net::LibIDN2(3)
net-libidn2 1.10.0 - Generated Tue Nov 12 18:44:59 CST 2019