.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::LibIDN2 3pm"
.TH Net::LibIDN2 3pm 2023-07-26 "perl v5.38.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::LibIDN2 \- Perl bindings for GNU Libidn2
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  use Net::LibIDN2 \*(Aq:all\*(Aq;
\&  use Encode;
\&
\&  idn2_lookup_u8(Encode::encode_utf8("m\eN{U+00FC}\eN{U+00DF}li.de"))
\&    eq \*(Aqxn\-\-mli\-5ka8l.de\*(Aq;
\&
\&  idn2_register_u8(
\&    Encode::encode_utf8("m\eN{U+00FC}\eN{U+00DF}li"),
\&    "xn\-\-mli\-5ka8l"
\&  ) eq \*(Aqxn\-\-mli\-5ka8l\*(Aq;
\&
\&  Encode::decode_utf8(idn2_to_unicode_88("xn\-\-mli\-5ka8l.de"))
\&    eq "m\eN{U+00FC}\eN{U+00DF}li.de"
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides bindings for GNU Libidn2, a C library for handling internationalized
domain names based on IDNA 2008, Punycode and TR46.
.SS Functions
.IX Subsection "Functions"
.ie n .IP "\fBNet::LibIDN2::idn2_lookup_u8\fR(\fR\fI$src\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_lookup_u8\fR(\fR\f(CI$src\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN2::idn2_lookup_u8($src, [$flags, [$rc]]);"
Alternative name idn2_to_ascii_8.
.Sp
Perform IDNA2008 lookup string conversion on domain name $\fIsrc\fR, 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.
.Sp
Pass \fBIDN2_NFC_INPUT\fR in \fR\f(CI$flags\fR\fI\fR to convert input to NFC form before further
processing. IDN2_TRANSITIONAL and IDN2_NONTRANSITIONAL do already imply IDN2_NFC_INPUT.
.Sp
Pass \fBIDN2_ALABEL_ROUNDTRIP\fR 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.
.Sp
Pass IDN2_TRANSITIONAL to enable Unicode TR46 transitional processing, and
IDN2_NONTRANSITIONAL to enable Unicode TR46 non-transitional processing.
.Sp
Multiple flags may be specified by binary or:ing them together, for example
\&\fBIDN2_NFC_INPUT\fR | \fBIDN2_ALABEL_ROUNDTRIP\fR.
.Sp
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.
.Sp
On error, returns undef. If a scalar variable is provided in \fR\f(CI$rc\fR\fI\fR, 
returns the internal libidn2 C library result code as well.
.ie n .IP "\fBNet::LibIDN2::idn2_lookup_ul\fR(\fR\fI$src\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_lookup_ul\fR(\fR\f(CI$src\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN2::idn2_lookup_ul($src, [$flags, [$rc]]);"
Alternative name idn2_to_ascii_l.
.Sp
Similar to function \f(CW\*(C`idn2_lookup_u8\*(C'\fR but \fR\f(CI$src\fR\fI\fR 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.
.ie n .IP "\fBNet::LibIDN2::idn2_register_u8\fR(\fR\fI$ulabel\fR\fI\fR, [\fI\fR\fI$alabel\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_register_u8\fR(\fR\f(CI$ulabel\fR\fI\fR, [\fI\fR\f(CI$alabel\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]]);" 4
.IX Item "Net::LibIDN2::idn2_register_u8($ulabel, [$alabel, [$flags, [$rc]]]);"
Perform IDNA2008 register string conversion on domain label \fR\f(CI$ulabel\fR\fI\fR and \fI\fR\f(CI$alabel\fR\fI\fR,
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.
.Sp
Pass \fBIDN2_NFC_INPUT\fR in \fR\f(CI$flags\fR\fI\fR to convert input \fI\fR\f(CI$ulabel\fR\fI\fR to NFC form before
further processing.
.Sp
It is recommended to supply both \fR\f(CI$ulabel\fR\fI\fR and \fI\fR\f(CI$alabel\fR\fI\fR for better error checking,
but supplying just one of them will work. Passing in only \fI\fR\f(CI$alabel\fR\fI\fR is better than
only \fI\fR\f(CI$ulabel\fR\fI\fR. See RFC 5891 section 4 for more information.
.Sp
On error, returns undef. If a scalar variable is provided in \fR\f(CI$rc\fR\fI\fR, 
returns the internal libidn2 C library result code as well.
.ie n .IP "\fBNet::LibIDN2::idn2_register_ul\fR(\fR\fI$ulabel\fR\fI\fR, [\fI\fR\fI$alabel\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_register_ul\fR(\fR\f(CI$ulabel\fR\fI\fR, [\fI\fR\f(CI$alabel\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]]);" 4
.IX Item "Net::LibIDN2::idn2_register_ul($ulabel, [$alabel, [$flags, [$rc]]]);"
Similar to function \f(CW\*(C`idn2_register_u8\*(C'\fR but \fR\f(CI$ulabel\fR\fI\fR 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.
.ie n .IP "\fBNet::LibIDN2::idn2_to_unicode_88\fR(\fR\fI$input\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_to_unicode_88\fR(\fR\f(CI$input\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]);" 4
.IX Item "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).
.Sp
On error, returns undef. If a scalar variable is provided in \fR\f(CI$rc\fR\fI\fR, 
returns the internal libidn2 C library result code as well.
.ie n .IP "\fBNet::LibIDN2::idn2_to_unicode_8l\fR(\fR\fI$input\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_to_unicode_8l\fR(\fR\f(CI$input\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN2::idn2_to_unicode_8l($input, [$flags, [$rc]]);"
Similar to function \f(CW\*(C`idn2_to_unicode_88\*(C'\fR but the return value is encoded in 
the locale's default coding system.
.ie n .IP "\fBNet::LibIDN2::idn2_to_unicode_ll\fR(\fR\fI$input\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR, [\fI\fR\fI$rc\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN2::idn2_to_unicode_ll\fR(\fR\f(CI$input\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR, [\fI\fR\f(CI$rc\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN2::idn2_to_unicode_ll($input, [$flags, [$rc]]);"
Similar to function \f(CW\*(C`idn2_to_unicode_8l\*(C'\fR but \fR\f(CI$input\fR\fI\fR is also assumed to be encoded in 
the locale's default coding system.
.ie n .IP \fBNet::LibIDN2::idn2_strerror\fR(\fR\fI$rc\fR\fI\fR); 4
.el .IP \fBNet::LibIDN2::idn2_strerror\fR(\fR\f(CI$rc\fR\fI\fR); 4
.IX Item "Net::LibIDN2::idn2_strerror($rc);"
Convert internal libidn2 error code \fR\f(CI$rc\fR\fI\fR to a human-readable string.
.ie n .IP \fBNet::LibIDN2::idn2_strerror_name\fR(\fR\fI$rc\fR\fI\fR); 4
.el .IP \fBNet::LibIDN2::idn2_strerror_name\fR(\fR\f(CI$rc\fR\fI\fR); 4
.IX Item "Net::LibIDN2::idn2_strerror_name($rc);"
Convert internal libidn2 error code \fR\f(CI$rc\fR\fI\fR to a string corresponding to
internal header file symbols names like IDN2_MALLOC.
.ie n .IP \fBNet::LibIDN2::idn2_check_version\fR([\fR\fI$req_version\fR\fI\fR]) 4
.el .IP \fBNet::LibIDN2::idn2_check_version\fR([\fR\f(CI$req_version\fR\fI\fR]) 4
.IX Item "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 \fR\f(CI$req_version\fR\fI\fR 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.
.Sp
See \fBIDN2_VERSION\fR for a suitable \fR\f(CI$req_version\fR\fI\fR 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.
.SS Constants
.IX Subsection "Constants"
.IP \fBIDN2_VERSION\fR 4
.IX Item "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 \fBidn2_check_version()\fR
to verify header file and run-time library consistency.
.IP \fBIDN2_VERSION_NUMBER\fR 4
.IX Item "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.
.IP \fBIDN2_VERSION_MAJOR\fR 4
.IX Item "IDN2_VERSION_MAJOR"
Pre-processor symbol for the major version number (decimal).
The version scheme is major.minor.patchlevel.
.IP \fBIDN2_VERSION_MINOR\fR 4
.IX Item "IDN2_VERSION_MINOR"
Pre-processor symbol for the minor version number (decimal).
The version scheme is major.minor.patchlevel.
.IP \fBIDN2_VERSION_PATCH\fR 4
.IX Item "IDN2_VERSION_PATCH"
Pre-processor symbol for the patch level number (decimal).
The version scheme is major.minor.patchlevel.
.IP \fBIDN2_LABEL_MAX_LENGTH\fR 4
.IX Item "IDN2_LABEL_MAX_LENGTH"
Constant specifying the maximum length of a DNS label to 63 characters,
as specified in RFC 1034.
.IP \fBIDN2_DOMAIN_MAX_LENGTH\fR 4
.IX Item "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.
.SS "Result codes"
.IX Subsection "Result codes"
.IP "\fB""Net::LibIDN2::IDN2_OK""\fR Successful return." 4
.IX Item """Net::LibIDN2::IDN2_OK"" Successful return."
.PD 0
.IP "\fB""Net::LibIDN2::IDN2_MALLOC""\fR Memory allocation error." 4
.IX Item """Net::LibIDN2::IDN2_MALLOC"" Memory allocation error."
.IP "\fB""Net::LibIDN2::IDN2_NO_CODESET""\fR Could not determine locale string encoding format." 4
.IX Item """Net::LibIDN2::IDN2_NO_CODESET"" Could not determine locale string encoding format."
.IP "\fB""Net::LibIDN2::IDN2_ICONV_FAIL""\fR Could not transcode locale string to UTF\-8." 4
.IX Item """Net::LibIDN2::IDN2_ICONV_FAIL"" Could not transcode locale string to UTF-8."
.IP "\fB""Net::LibIDN2::IDN2_ENCODING_ERROR""\fR Unicode data encoding error." 4
.IX Item """Net::LibIDN2::IDN2_ENCODING_ERROR"" Unicode data encoding error."
.IP "\fB""Net::LibIDN2::IDN2_NFC""\fR Error normalizing string." 4
.IX Item """Net::LibIDN2::IDN2_NFC"" Error normalizing string."
.IP "\fB""Net::LibIDN2::IDN2_PUNYCODE_BAD_INPUT""\fR Punycode invalid input." 4
.IX Item """Net::LibIDN2::IDN2_PUNYCODE_BAD_INPUT"" Punycode invalid input."
.IP "\fB""Net::LibIDN2::IDN2_PUNYCODE_BIG_OUTPUT""\fR Punycode output buffer too small." 4
.IX Item """Net::LibIDN2::IDN2_PUNYCODE_BIG_OUTPUT"" Punycode output buffer too small."
.IP "\fB""Net::LibIDN2::IDN2_PUNYCODE_OVERFLOW""\fR Punycode conversion would overflow." 4
.IX Item """Net::LibIDN2::IDN2_PUNYCODE_OVERFLOW"" Punycode conversion would overflow."
.IP "\fB""Net::LibIDN2::IDN2_TOO_BIG_DOMAIN""\fR Domain name longer than 255 characters." 4
.IX Item """Net::LibIDN2::IDN2_TOO_BIG_DOMAIN"" Domain name longer than 255 characters."
.IP "\fB""Net::LibIDN2::IDN2_TOO_BIG_LABEL""\fR Domain label longer than 63 characters." 4
.IX Item """Net::LibIDN2::IDN2_TOO_BIG_LABEL"" Domain label longer than 63 characters."
.IP "\fB""Net::LibIDN2::IDN2_INVALID_ALABEL""\fR Input A\-label is not valid." 4
.IX Item """Net::LibIDN2::IDN2_INVALID_ALABEL"" Input A-label is not valid."
.IP "\fB""Net::LibIDN2::IDN2_UALABEL_MISMATCH""\fR Input A\-label and U\-label does not match." 4
.IX Item """Net::LibIDN2::IDN2_UALABEL_MISMATCH"" Input A-label and U-label does not match."
.IP "\fB""Net::LibIDN2::IDN2_NOT_NFC""\fR String is not NFC." 4
.IX Item """Net::LibIDN2::IDN2_NOT_NFC"" String is not NFC."
.IP "\fB""Net::LibIDN2::IDN2_2HYPHEN""\fR String has forbidden two hyphens." 4
.IX Item """Net::LibIDN2::IDN2_2HYPHEN"" String has forbidden two hyphens."
.IP "\fB""Net::LibIDN2::IDN2_HYPHEN_STARTEND""\fR String has forbidden starting/ending hyphen." 4
.IX Item """Net::LibIDN2::IDN2_HYPHEN_STARTEND"" String has forbidden starting/ending hyphen."
.IP "\fB""Net::LibIDN2::IDN2_LEADING_COMBINING""\fR String has forbidden leading combining character." 4
.IX Item """Net::LibIDN2::IDN2_LEADING_COMBINING"" String has forbidden leading combining character."
.IP "\fB""Net::LibIDN2::IDN2_DISALLOWED""\fR String has disallowed character." 4
.IX Item """Net::LibIDN2::IDN2_DISALLOWED"" String has disallowed character."
.IP "\fB""Net::LibIDN2::IDN2_CONTEXTJ""\fR String has forbidden context-j character." 4
.IX Item """Net::LibIDN2::IDN2_CONTEXTJ"" String has forbidden context-j character."
.IP "\fB""Net::LibIDN2::IDN2_CONTEXTJ_NO_RULE""\fR String has context-j character with no rule." 4
.IX Item """Net::LibIDN2::IDN2_CONTEXTJ_NO_RULE"" String has context-j character with no rule."
.IP "\fB""Net::LibIDN2::IDN2_CONTEXTO""\fR String has forbidden context-o character." 4
.IX Item """Net::LibIDN2::IDN2_CONTEXTO"" String has forbidden context-o character."
.IP "\fB""Net::LibIDN2::IDN2_CONTEXTO_NO_RULE""\fR String has context-o character with no rule." 4
.IX Item """Net::LibIDN2::IDN2_CONTEXTO_NO_RULE"" String has context-o character with no rule."
.IP "\fB""Net::LibIDN2::IDN2_UNASSIGNED""\fR String has forbidden unassigned character." 4
.IX Item """Net::LibIDN2::IDN2_UNASSIGNED"" String has forbidden unassigned character."
.IP "\fB""Net::LibIDN2::IDN2_BIDI""\fR String has forbidden bi-directional properties." 4
.IX Item """Net::LibIDN2::IDN2_BIDI"" String has forbidden bi-directional properties."
.IP "\fB""Net::LibIDN2::IDN2_DOT_IN_LABEL""\fR Label has forbidden dot (TR46)." 4
.IX Item """Net::LibIDN2::IDN2_DOT_IN_LABEL"" Label has forbidden dot (TR46)."
.IP "\fB""Net::LibIDN2::IDN2_INVALID_TRANSITIONAL""\fR Label has character forbidden in transitional mode (TR46)." 4
.IX Item """Net::LibIDN2::IDN2_INVALID_TRANSITIONAL"" Label has character forbidden in transitional mode (TR46)."
.IP "\fB""Net::LibIDN2::IDN2_INVALID_NONTRANSITIONAL""\fR Label has character forbidden in non-transitional mode (TR46)." 4
.IX Item """Net::LibIDN2::IDN2_INVALID_NONTRANSITIONAL"" Label has character forbidden in non-transitional mode (TR46)."
.PD
.SH AUTHOR
.IX Header "AUTHOR"
Thomas Jacob, https://github.com/gnuthor
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), RFC 5890\-5893, TR 46, https://gitlab.com/libidn/libidn2.