1Net::LibIDN2(3)       User Contributed Perl Documentation      Net::LibIDN2(3)
2
3
4

NAME

6       Net::LibIDN2 - Perl bindings for GNU Libidn2
7

SYNOPSIS

9         use Net::LibIDN2 ':all';
10         use Encode;
11
12         idn2_lookup_u8(Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li.de"))
13           eq 'xn--mli-5ka8l.de';
14
15         idn2_register_u8(
16           Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li"),
17           "xn--mli-5ka8l"
18         ) eq 'xn--mli-5ka8l';
19
20         Encode::decode_utf8(idn2_to_unicode_88("xn--mli-5ka8l.de"))
21           eq "m\N{U+00FC}\N{U+00DF}li.de"
22

DESCRIPTION

24       Provides bindings for GNU Libidn2, a C library for handling
25       internationalized domain names based on IDNA 2008, Punycode and TR46.
26
27   Functions
28       Net::LibIDN2::idn2_lookup_u8($src, [$flags, [$rc]]);
29           Alternative name idn2_to_ascii_8.
30
31           Perform IDNA2008 lookup string conversion on domain name $src, as
32           described in section 5 of RFC 5891. Note that the input string must
33           be encoded in UTF-8 and be in Unicode NFC form.
34
35           Pass IDN2_NFC_INPUT in $flags to convert input to NFC form before
36           further processing. IDN2_TRANSITIONAL and IDN2_NONTRANSITIONAL do
37           already imply IDN2_NFC_INPUT.
38
39           Pass IDN2_ALABEL_ROUNDTRIP in flags to convert any input A-labels
40           to U-labels and perform additional testing. This is default if used
41           with a libidn2 version >= 2.2. To switch this behavior off, pass
42           IDN2_NO_ALABEL_ROUNDTRIP.
43
44           Pass IDN2_TRANSITIONAL to enable Unicode TR46 transitional
45           processing, and IDN2_NONTRANSITIONAL to enable Unicode TR46 non-
46           transitional processing.
47
48           Multiple flags may be specified by binary or:ing them together, for
49           example IDN2_NFC_INPUT | IDN2_ALABEL_ROUNDTRIP.
50
51           If linked to library GNU Libidn2 version > 2.0.3:
52           IDN2_USE_STD3_ASCII_RULES disabled by default.  Previously we were
53           eliminating non-STD3 characters from domain strings such as
54           _443._tcp.example.com, or IPs 1.2.3.4/24 provided to libidn2
55           functions.  That was an unexpected regression for applications
56           switching from libidn2 and thus it is no longer applied by default.
57           Use IDN2_USE_STD3_ASCII_RULES to enable that behavior again.
58
59           On error, returns undef. If a scalar variable is provided in $rc,
60           returns the internal libidn2 C library result code as well.
61
62       Net::LibIDN2::idn2_lookup_ul($src, [$flags, [$rc]]);
63           Alternative name idn2_to_ascii_l.
64
65           Similar to function "idn2_lookup_u8" but $src is assumed to be
66           encoded in the locale's default coding system, and will be
67           transcoded to UTF-8 and NFC normalized before returning the result.
68
69       Net::LibIDN2::idn2_register_u8($ulabel, [$alabel, [$flags, [$rc]]]);
70           Perform IDNA2008 register string conversion on domain label $ulabel
71           and $alabel, as described in section 4 of RFC 5891. Note that the
72           input ulabel must be encoded in UTF-8 and be in Unicode NFC form.
73
74           Pass IDN2_NFC_INPUT in $flags to convert input $ulabel to NFC form
75           before further processing.
76
77           It is recommended to supply both $ulabel and $alabel for better
78           error checking, but supplying just one of them will work. Passing
79           in only $alabel is better than only $ulabel. See RFC 5891 section 4
80           for more information.
81
82           On error, returns undef. If a scalar variable is provided in $rc,
83           returns the internal libidn2 C library result code as well.
84
85       Net::LibIDN2::idn2_register_ul($ulabel, [$alabel, [$flags, [$rc]]]);
86           Similar to function "idn2_register_u8" but $ulabel is assumed to be
87           encoded in the locale's default coding system, and will be
88           transcoded to UTF-8 and NFC normalized before returning the result.
89
90       Net::LibIDN2::idn2_to_unicode_88($input, [$flags, [$rc]]);
91           Converts a possibly ACE encoded domain name in UTF-8 format into a
92           an UTF-8 encoded string (punycode decoding).
93
94           On error, returns undef. If a scalar variable is provided in $rc,
95           returns the internal libidn2 C library result code as well.
96
97       Net::LibIDN2::idn2_to_unicode_8l($input, [$flags, [$rc]]);
98           Similar to function "idn2_to_unicode_88" but the return value is
99           encoded in the locale's default coding system.
100
101       Net::LibIDN2::idn2_to_unicode_ll($input, [$flags, [$rc]]);
102           Similar to function "idn2_to_unicode_8l" but $input is also assumed
103           to be encoded in the locale's default coding system.
104
105       Net::LibIDN2::idn2_strerror($rc);
106           Convert internal libidn2 error code $rc to a human-readable string.
107
108       Net::LibIDN2::idn2_strerror_name($rc);
109           Convert internal libidn2 error code $rc to a string corresponding
110           to internal header file symbols names like IDN2_MALLOC.
111
112       Net::LibIDN2::idn2_check_version([$req_version])
113           Checks that the version of the underlying IDN2 C library is at
114           minimum the one given as a string in $req_version and if that is
115           the case returns the actual version string  of the underlying C
116           library or undef if the condition is not met. If no parameter is
117           passed to this function no check is done and only the version
118           string is returned.
119
120           See IDN2_VERSION for a suitable $req_version string, it corresponds
121           to  the idn2.h C header file version at compile time of this Perl
122           module.  Normally these two version numbers match, but if you
123           compiled this Perl module against an older libidn2  and then run it
124           with a newer libidn2 shared library, they will be different.
125
126   Constants
127       IDN2_VERSION
128           Pre-processor symbol with a string that describes the C header file
129           version number at compile time of this Perl module. Used together
130           with idn2_check_version() to verify header file and run-time
131           library consistency.
132
133       IDN2_VERSION_NUMBER
134           Pre-processor symbol with a hexadecimal value describing the C
135           header file version number at compile time of this Perl module. For
136           example, when the header version is 1.2.4711 this symbol will have
137           the value 0x01021267. The last four digits are used to enumerate
138           development snapshots, but for all public releases they will be
139           0000.
140
141       IDN2_VERSION_MAJOR
142           Pre-processor symbol for the major version number (decimal).  The
143           version scheme is major.minor.patchlevel.
144
145       IDN2_VERSION_MINOR
146           Pre-processor symbol for the minor version number (decimal).  The
147           version scheme is major.minor.patchlevel.
148
149       IDN2_VERSION_PATCH
150           Pre-processor symbol for the patch level number (decimal).  The
151           version scheme is major.minor.patchlevel.
152
153       IDN2_LABEL_MAX_LENGTH
154           Constant specifying the maximum length of a DNS label to 63
155           characters, as specified in RFC 1034.
156
157       IDN2_DOMAIN_MAX_LENGTH
158           Constant specifying the maximum size of the wire encoding of a DNS
159           domain to 255 characters, as specified in RFC 1034. Note that the
160           usual printed representation of a domain name is limited to 253
161           characters if it does not end with a period or 254 characters if it
162           ends with a period.
163
164   Result codes
165       "Net::LibIDN2::IDN2_OK" Successful return.
166       "Net::LibIDN2::IDN2_MALLOC" Memory allocation error.
167       "Net::LibIDN2::IDN2_NO_CODESET" Could not determine locale string
168       encoding format.
169       "Net::LibIDN2::IDN2_ICONV_FAIL" Could not transcode locale string to
170       UTF-8.
171       "Net::LibIDN2::IDN2_ENCODING_ERROR" Unicode data encoding error.
172       "Net::LibIDN2::IDN2_NFC" Error normalizing string.
173       "Net::LibIDN2::IDN2_PUNYCODE_BAD_INPUT" Punycode invalid input.
174       "Net::LibIDN2::IDN2_PUNYCODE_BIG_OUTPUT" Punycode output buffer too
175       small.
176       "Net::LibIDN2::IDN2_PUNYCODE_OVERFLOW" Punycode conversion would
177       overflow.
178       "Net::LibIDN2::IDN2_TOO_BIG_DOMAIN" Domain name longer than 255
179       characters.
180       "Net::LibIDN2::IDN2_TOO_BIG_LABEL" Domain label longer than 63
181       characters.
182       "Net::LibIDN2::IDN2_INVALID_ALABEL" Input A-label is not valid.
183       "Net::LibIDN2::IDN2_UALABEL_MISMATCH" Input A-label and U-label does
184       not match.
185       "Net::LibIDN2::IDN2_NOT_NFC" String is not NFC.
186       "Net::LibIDN2::IDN2_2HYPHEN" String has forbidden two hyphens.
187       "Net::LibIDN2::IDN2_HYPHEN_STARTEND" String has forbidden
188       starting/ending hyphen.
189       "Net::LibIDN2::IDN2_LEADING_COMBINING" String has forbidden leading
190       combining character.
191       "Net::LibIDN2::IDN2_DISALLOWED" String has disallowed character.
192       "Net::LibIDN2::IDN2_CONTEXTJ" String has forbidden context-j character.
193       "Net::LibIDN2::IDN2_CONTEXTJ_NO_RULE" String has context-j character
194       with no rule.
195       "Net::LibIDN2::IDN2_CONTEXTO" String has forbidden context-o character.
196       "Net::LibIDN2::IDN2_CONTEXTO_NO_RULE" String has context-o character
197       with no rule.
198       "Net::LibIDN2::IDN2_UNASSIGNED" String has forbidden unassigned
199       character.
200       "Net::LibIDN2::IDN2_BIDI" String has forbidden bi-directional
201       properties.
202       "Net::LibIDN2::IDN2_DOT_IN_LABEL" Label has forbidden dot (TR46).
203       "Net::LibIDN2::IDN2_INVALID_TRANSITIONAL" Label has character forbidden
204       in transitional mode (TR46).
205       "Net::LibIDN2::IDN2_INVALID_NONTRANSITIONAL" Label has character
206       forbidden in non-transitional mode (TR46).
207

AUTHOR

209       Thomas Jacob, https://github.com/gnuthor
210

SEE ALSO

212       perl(1), RFC 5890-5893, TR 46, https://gitlab.com/libidn/libidn2.
213
214
215
216perl v5.36.0                      2023-01-20                   Net::LibIDN2(3)
Impressum