.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" 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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "LibIDN 3"
.TH LibIDN 3 2025-07-14 "perl v5.42.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::LibIDN \- Perl bindings for GNU Libidn
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::LibIDN \*(Aq:all\*(Aq;
\&
\&  idn_to_ascii("Räksmörgås.Josefßon.ORG") eq
\&    idn_to_ascii(idn_to_unicode("xn\-\-rksmrgs\-5wao1o.josefsson.org"));
\&
\&  idn_prep_name("LibÜDN") eq "libüdn";
\&
\&  idn_punycode_encode("kistenmöhre") eq
\&    idn_punycode_encode(idn_punycode_decode("kistenmhre\-kcb"));
\&
\&  my $errpos;
\&  tld_check("mèrle.se", $errpos) eq undef;
\&    $errpos == 1;
\&
\&  tld_get("mainbase.mars") eq "mars";
\&
\&  my $hashref = Net::LibIDN::tld_get_table("de");
\&
\&  print "$hashref\->{version}\en";
\&  foreach (@{$hashref\->{valid}})
\&  {
\&    print "Unicode range from ".$_\->{start}." to ".$_\->{end}."\en";
\&  }
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Provides bindings for GNU Libidn, a C library for handling Internationalized
Domain Names according to IDNA (RFC 3490), in a way very much inspired by
Turbo Fredriksson\*(Aqs PHP\-IDN.
.SS Functions
.IX Subsection "Functions"
.ie n .IP "\fBNet::LibIDN::idn_to_ascii\fR(\fR\fI$clear_hostname\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN::idn_to_ascii\fR(\fR\f(CI$clear_hostname\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN::idn_to_ascii($clear_hostname, [$charset, [$flags]]);"
Converts \fR\f(CI$clear_hostname\fR\fI\fR which might contain characters outside
the range allowed in DNS names, to IDNA ACE. If \fI\fR\f(CI$charset\fR\fI\fR is
specified, treats string as being encoded in it, otherwise
assumes it is ISO\-8859\-1 encoded. If flag
\&\fBIDNA_ALLOW_UNASSIGNED\fR is set in \fI\fR\f(CI$flags\fR\fI\fR, accepts also unassigned
Unicode characters, if \fBIDNA_USE_STD3_ASCII_RULES\fR is set, accepts
only ASCII LDH characters (letter\-digit\-hyphen). Flags can be
combined with ||. Returns result of conversion or \fBundef\fR on
error.
.ie n .IP "\fBNet::LibIDN::idn_to_unicode\fR(\fR\fI$idn_hostname\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR, [\fI\fR\fI$flags\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN::idn_to_unicode\fR(\fR\f(CI$idn_hostname\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR, [\fI\fR\f(CI$flags\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN::idn_to_unicode($idn_hostname, [$charset, [$flags]]);"
Converts ASCII \fR\f(CI$idn_hostname\fR\fI\fR, which might be IDNA ACE
encoded, into the decoded form in \fI\fR\f(CI$charset\fR\fI\fR or ISO\-8859\-1. Flags
are interpreted as above. Returns result of conversion
or \fBundef\fR on error.
.ie n .IP "\fBNet::LibIDN::idn_punycode_encode\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_punycode_encode\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_punycode_encode($string, [$charset]);"
Encodes \fR\f(CI$string\fR\fI\fR into "punycode" (RFC 3492). If \fI\fR\f(CI$charset\fR\fI\fR
is present, treats \fI\fR\f(CI$string\fR\fI\fR as being in \fI\fR\f(CI$charset\fR\fI\fR, otherwise
uses ISO\-8859\-1. Returns result of conversion
or \fBundef\fR on error.
.ie n .IP "\fBNet::LibIDN::idn_punycode_decode\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_punycode_decode\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_punycode_decode($string, [$charset]);"
Decodes \fR\f(CI$string\fR\fI\fR from "punycode" (RFC 3492). If \fI\fR\f(CI$charset\fR\fI\fR
is present, result is converted to \fI\fR\f(CI$charset\fR\fI\fR, otherwise
it is converted to ISO\-8859\-1. Returns result of conversion
or \fBundef\fR on error.
.ie n .IP "\fBNet::LibIDN::idn_prep_name\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_name\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_name($string, [$charset]);"
.PD 0
.ie n .IP "\fBNet::LibIDN::idn_prep_kerberos5\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_kerberos5\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_kerberos5($string, [$charset]);"
.ie n .IP "\fBNet::LibIDN::idn_prep_node\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_node\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_node($string, [$charset]);"
.ie n .IP "\fBNet::LibIDN::idn_prep_resource\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_resource\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_resource($string, [$charset]);"
.ie n .IP "\fBNet::LibIDN::idn_prep_plain\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_plain\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_plain($string, [$charset]);"
.ie n .IP "\fBNet::LibIDN::idn_prep_trace\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_trace\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_trace($string, [$charset]);"
.ie n .IP "\fBNet::LibIDN::idn_prep_sasl\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_sasl\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_sasl($string, [$charset]);"
.ie n .IP "\fBNet::LibIDN::idn_prep_iscsi\fR(\fR\fI$string\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR]);" 4
.el .IP "\fBNet::LibIDN::idn_prep_iscsi\fR(\fR\f(CI$string\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR]);" 4
.IX Item "Net::LibIDN::idn_prep_iscsi($string, [$charset]);"
.PD
Performs "stringprep" (RFC 3454) on \f(CW$string\fR according to the named
profile (e.g. *_name \-> "nameprep" (RFC 3491)).
If \fR\f(CI$charset\fR\fI\fR is present, converts from and to this charset before and after
the operation respectively. Returns result string, or \fBundef\fR on error.
.ie n .IP "\fBNet::LibIDN::tdl_check\fR(\fR\fI$string\fR\fI\fR, \fI\fR\fI$errpos\fR\fI\fR, [\fI\fR\fI$charset\fR\fI\fR, [\fI\fR\fI$tld\fR\fI\fR]]);" 4
.el .IP "\fBNet::LibIDN::tdl_check\fR(\fR\f(CI$string\fR\fI\fR, \fI\fR\f(CI$errpos\fR\fI\fR, [\fI\fR\f(CI$charset\fR\fI\fR, [\fI\fR\f(CI$tld\fR\fI\fR]]);" 4
.IX Item "Net::LibIDN::tdl_check($string, $errpos, [$charset, [$tld]]);"
Checks whether or not \fR\f(CI$string\fR\fI\fR conforms to the restrictions on the sets
of valid characters defined by TLD authorities around the World. Treats
\&\fI\fR\f(CI$string\fR\fI\fR as a hostname if \fI\fR\f(CI$tld\fR\fI\fR is not present, determining the TLD
from the hostname. If \fI\fR\f(CI$tld\fR\fI\fR is present, uses the restrictions defined
by the parties responsible for TLD \fI\fR\f(CI$tld\fR\fI\fR. \fI\fR\f(CI$charset\fR\fI\fR may be used to
specify the character set the \fI\fR\f(CI$string\fR\fI\fR is in. Should an invalid character
be detected, returns 0 and the 0\-based position of the offending character
in \fI\fR\f(CI$errpos\fR\fI\fR. In case of other failure conditions, \fI\fR\f(CI$errpos\fR\fI\fR is not touched,
and \fBundef\fR is returned. Should \fI\fR\f(CI$string\fR\fI\fR conform to the TLD restrictions,
1 is returned.
.ie n .IP \fBNet::LibIDN::tld_get\fR(\fR\fI$hostname\fR\fI\fR); 4
.el .IP \fBNet::LibIDN::tld_get\fR(\fR\f(CI$hostname\fR\fI\fR); 4
.IX Item "Net::LibIDN::tld_get($hostname);"
Returns top level domain of \fR\f(CI$hostname\fR\fI\fR, or \fBundef\fR if an error
occurs or if no top level domain was found.
.ie n .IP \fBNet::LibIDN::tld_get_table\fR(\fR\fI$tld\fR\fI\fR); 4
.el .IP \fBNet::LibIDN::tld_get_table\fR(\fR\f(CI$tld\fR\fI\fR); 4
.IX Item "Net::LibIDN::tld_get_table($tld);"
Retrieves a hash reference with the TLD restriction info of given
TLD \fR\f(CI$tld\fR\fI\fR, or \fBundef\fR if \fI\fR\f(CI$tld\fR\fI\fR is not found. The hash ref contains the
following fields:
.RS 4
.IP \(bu 4
\&\fR\f(CI$h\fR\fI\-\fR>\fI{name}\fR ... name of TLD
.IP \(bu 4
\&\fR\f(CI$h\fR\fI\-\fR>\fI{version}\fR ... version string of this restriction table
.IP \(bu 4
\&\fR\f(CI$h\fR\fI\-\fR>\fI{nvalid}\fR ... number of Unicode intervals
.IP \(bu 4
\&\fR\f(CI$h\fR\fI\-\fR>\fI{valid}\fR ...  [ {\fIstart\fR => number, \fIend\fR => number}, ...] ... Unicode intervals
.RE
.RS 4
.RE
.SS Limitations
.IX Subsection "Limitations"
There is currently no support for Perl\*(Aqs unicode capabilities (man perlunicode).
All input strings are assumed to be octet strings, all output strings are 
generated as octet strings. Thus, if you require Perl\*(Aqs unicode features, you 
will have to convert your strings manually. For example:
.Sp
.RS 4
use Encode;
.Sp
use Data::Dumper;
.Sp
print Dumper(Net::LibIDN::idn_to_unicode(\*(Aqxn\-\-uro\-j50a.com\*(Aq, \*(Aqutf\-8\*(Aq));
.Sp
print Dumper(decode(\*(Aqutf\-8\*(Aq, Net::LibIDN::idn_to_unicode(\*(Aqxn\-\-uro\-j50a.com\*(Aq, \*(Aqutf\-8\*(Aq)));
.RE
.SH AUTHOR
.IX Header "AUTHOR"
Thomas Jacob, http://internet24.de
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBperl\fR\|(1), RFC 3454, RFC 3490\-3492, http://www.gnu.org/software/libidn.