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
11         idn2_lookup_u8(Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li.de"))
12           eq 'xn--mli-5ka8l.de';
13
14         idn2_register_u8(
15           Encode::encode_utf8("m\N{U+00FC}\N{U+00DF}li"),
16           "xn--mli-5ka8l"
17         ) eq 'xn--mli-5ka8l';
18
19         Encode::decode_utf8(idn2_to_unicode_88("xn--mli-5ka8l.de"))
20           eq "m\N{U+00FC}\N{U+00DF}li"
21

DESCRIPTION

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

AUTHOR

196       Thomas Jacob, https://github.com/gnuthor
197

SEE ALSO

199       perl(1), RFC 5890-5893, TR 46, https://gitlab.com/libidn/libidn2.
200
201
202
203perl v5.28.0                      2018-07-15                   Net::LibIDN2(3)
Impressum