2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
<refentry id="libidn-idna">
6
<refentrytitle role="top_of_page" id="libidn-idna.top_of_page">idna</refentrytitle>
7
<manvolnum>3</manvolnum>
8
<refmiscinfo>LIBIDN Library</refmiscinfo>
12
<refname>idna</refname>
13
<refpurpose></refpurpose>
16
<refsynopsisdiv id="libidn-idna.synopsis" role="synopsis">
17
<title role="synopsis.title">Synopsis</title>
20
#define <link linkend="IDNAPI--CAPS">IDNAPI</link>
21
enum <link linkend="Idna-rc">Idna_rc</link>;
22
enum <link linkend="Idna-flags">Idna_flags</link>;
23
#define <link linkend="IDNA-ACE-PREFIX--CAPS">IDNA_ACE_PREFIX</link>
24
const <link linkend="char">char</link> * <link linkend="idna-strerror">idna_strerror</link> (<link linkend="Idna-rc">Idna_rc</link> rc);
25
<link linkend="int">int</link> <link linkend="idna-to-ascii-4i">idna_to_ascii_4i</link> (const <link linkend="uint32-t">uint32_t</link> *in,
26
<link linkend="size-t">size_t</link> inlen,
27
<link linkend="char">char</link> *out,
28
<link linkend="int">int</link> flags);
29
<link linkend="int">int</link> <link linkend="idna-to-unicode-44i">idna_to_unicode_44i</link> (const <link linkend="uint32-t">uint32_t</link> *in,
30
<link linkend="size-t">size_t</link> inlen,
31
<link linkend="uint32-t">uint32_t</link> *out,
32
<link linkend="size-t">size_t</link> *outlen,
33
<link linkend="int">int</link> flags);
34
<link linkend="int">int</link> <link linkend="idna-to-ascii-4z">idna_to_ascii_4z</link> (const <link linkend="uint32-t">uint32_t</link> *input,
35
<link linkend="char">char</link> **output,
36
<link linkend="int">int</link> flags);
37
<link linkend="int">int</link> <link linkend="idna-to-ascii-8z">idna_to_ascii_8z</link> (const <link linkend="char">char</link> *input,
38
<link linkend="char">char</link> **output,
39
<link linkend="int">int</link> flags);
40
<link linkend="int">int</link> <link linkend="idna-to-ascii-lz">idna_to_ascii_lz</link> (const <link linkend="char">char</link> *input,
41
<link linkend="char">char</link> **output,
42
<link linkend="int">int</link> flags);
43
<link linkend="int">int</link> <link linkend="idna-to-unicode-4z4z">idna_to_unicode_4z4z</link> (const <link linkend="uint32-t">uint32_t</link> *input,
44
<link linkend="uint32-t">uint32_t</link> **output,
45
<link linkend="int">int</link> flags);
46
<link linkend="int">int</link> <link linkend="idna-to-unicode-8z4z">idna_to_unicode_8z4z</link> (const <link linkend="char">char</link> *input,
47
<link linkend="uint32-t">uint32_t</link> **output,
48
<link linkend="int">int</link> flags);
49
<link linkend="int">int</link> <link linkend="idna-to-unicode-8z8z">idna_to_unicode_8z8z</link> (const <link linkend="char">char</link> *input,
50
<link linkend="char">char</link> **output,
51
<link linkend="int">int</link> flags);
52
<link linkend="int">int</link> <link linkend="idna-to-unicode-8zlz">idna_to_unicode_8zlz</link> (const <link linkend="char">char</link> *input,
53
<link linkend="char">char</link> **output,
54
<link linkend="int">int</link> flags);
55
<link linkend="int">int</link> <link linkend="idna-to-unicode-lzlz">idna_to_unicode_lzlz</link> (const <link linkend="char">char</link> *input,
56
<link linkend="char">char</link> **output,
57
<link linkend="int">int</link> flags);
69
<refsect1 id="libidn-idna.description" role="desc">
70
<title role="desc.title">Description</title>
75
<refsect1 id="libidn-idna.details" role="details">
76
<title role="details.title">Details</title>
77
<refsect2 id="IDNAPI--CAPS" role="macro">
79
<indexterm zone="IDNAPI--CAPS"><primary sortas="IDNAPI">IDNAPI</primary></indexterm><programlisting>#define IDNAPI</programlisting>
82
<refsect2 id="Idna-rc" role="enum">
83
<title>enum Idna_rc</title>
84
<indexterm zone="Idna-rc"><primary sortas="Idna_rc">Idna_rc</primary></indexterm><programlisting> typedef enum
87
IDNA_STRINGPREP_ERROR = 1,
88
IDNA_PUNYCODE_ERROR = 2,
89
IDNA_CONTAINS_NON_LDH = 3,
90
/* Workaround typo in earlier versions. */
91
IDNA_CONTAINS_LDH = IDNA_CONTAINS_NON_LDH,
92
IDNA_CONTAINS_MINUS = 4,
93
IDNA_INVALID_LENGTH = 5,
94
IDNA_NO_ACE_PREFIX = 6,
95
IDNA_ROUNDTRIP_VERIFY_ERROR = 7,
96
IDNA_CONTAINS_ACE_PREFIX = 8,
98
/* Internal errors. */
99
IDNA_MALLOC_ERROR = 201,
100
IDNA_DLOPEN_ERROR = 202
104
Enumerated return codes of <link linkend="idna-to-ascii-4i"><function>idna_to_ascii_4i()</function></link>,
105
<link linkend="idna-to-unicode-44i"><function>idna_to_unicode_44i()</function></link> functions (and functions derived from those
106
functions). The value 0 is guaranteed to always correspond to
109
</para><variablelist role="enum">
110
<varlistentry id="IDNA-SUCCESS--CAPS" role="constant">
111
<term><literal>IDNA_SUCCESS</literal></term>
112
<listitem><simpara> Successful operation. This value is guaranteed to
113
always be zero, the remaining ones are only guaranteed to hold
114
non-zero values, for logical comparison purposes.
115
</simpara></listitem>
117
<varlistentry id="IDNA-STRINGPREP-ERROR--CAPS" role="constant">
118
<term><literal>IDNA_STRINGPREP_ERROR</literal></term>
119
<listitem><simpara> Error during string preparation.
120
</simpara></listitem>
122
<varlistentry id="IDNA-PUNYCODE-ERROR--CAPS" role="constant">
123
<term><literal>IDNA_PUNYCODE_ERROR</literal></term>
124
<listitem><simpara> Error during punycode operation.
125
</simpara></listitem>
127
<varlistentry id="IDNA-CONTAINS-NON-LDH--CAPS" role="constant">
128
<term><literal>IDNA_CONTAINS_NON_LDH</literal></term>
129
<listitem><simpara> For IDNA_USE_STD3_ASCII_RULES, indicate that
130
the string contains non-LDH ASCII characters.
131
</simpara></listitem>
133
<varlistentry id="IDNA-CONTAINS-LDH--CAPS" role="constant">
134
<term><literal>IDNA_CONTAINS_LDH</literal></term>
136
</simpara></listitem>
138
<varlistentry id="IDNA-CONTAINS-MINUS--CAPS" role="constant">
139
<term><literal>IDNA_CONTAINS_MINUS</literal></term>
140
<listitem><simpara> For IDNA_USE_STD3_ASCII_RULES, indicate that
141
the string contains a leading or trailing hyphen-minus (U+002D).
142
</simpara></listitem>
144
<varlistentry id="IDNA-INVALID-LENGTH--CAPS" role="constant">
145
<term><literal>IDNA_INVALID_LENGTH</literal></term>
146
<listitem><simpara> The final output string is not within the
147
(inclusive) range 1 to 63 characters.
148
</simpara></listitem>
150
<varlistentry id="IDNA-NO-ACE-PREFIX--CAPS" role="constant">
151
<term><literal>IDNA_NO_ACE_PREFIX</literal></term>
152
<listitem><simpara> The string does not contain the ACE prefix
154
</simpara></listitem>
156
<varlistentry id="IDNA-ROUNDTRIP-VERIFY-ERROR--CAPS" role="constant">
157
<term><literal>IDNA_ROUNDTRIP_VERIFY_ERROR</literal></term>
158
<listitem><simpara> The ToASCII operation on output
159
string does not equal the input.
160
</simpara></listitem>
162
<varlistentry id="IDNA-CONTAINS-ACE-PREFIX--CAPS" role="constant">
163
<term><literal>IDNA_CONTAINS_ACE_PREFIX</literal></term>
164
<listitem><simpara> The input contains the ACE prefix (for
166
</simpara></listitem>
168
<varlistentry id="IDNA-ICONV-ERROR--CAPS" role="constant">
169
<term><literal>IDNA_ICONV_ERROR</literal></term>
170
<listitem><simpara> Could not convert string in locale encoding.
171
</simpara></listitem>
173
<varlistentry id="IDNA-MALLOC-ERROR--CAPS" role="constant">
174
<term><literal>IDNA_MALLOC_ERROR</literal></term>
175
<listitem><simpara> Could not allocate buffer (this is typically a
177
</simpara></listitem>
179
<varlistentry id="IDNA-DLOPEN-ERROR--CAPS" role="constant">
180
<term><literal>IDNA_DLOPEN_ERROR</literal></term>
181
<listitem><simpara> Could not dlopen the libcidn DSO (only used
183
</simpara></listitem>
185
</variablelist></refsect2>
186
<refsect2 id="Idna-flags" role="enum">
187
<title>enum Idna_flags</title>
188
<indexterm zone="Idna-flags"><primary sortas="Idna_flags">Idna_flags</primary></indexterm><programlisting> typedef enum
190
IDNA_ALLOW_UNASSIGNED = 0x0001,
191
IDNA_USE_STD3_ASCII_RULES = 0x0002
195
Flags to pass to <link linkend="idna-to-ascii-4i"><function>idna_to_ascii_4i()</function></link>, <link linkend="idna-to-unicode-44i"><function>idna_to_unicode_44i()</function></link> etc.</para>
197
</para><variablelist role="enum">
198
<varlistentry id="IDNA-ALLOW-UNASSIGNED--CAPS" role="constant">
199
<term><literal>IDNA_ALLOW_UNASSIGNED</literal></term>
200
<listitem><simpara> Don't reject strings containing unassigned
202
</simpara></listitem>
204
<varlistentry id="IDNA-USE-STD3-ASCII-RULES--CAPS" role="constant">
205
<term><literal>IDNA_USE_STD3_ASCII_RULES</literal></term>
206
<listitem><simpara> Validate strings according to STD3
207
rules (i.e., normal host name rules).
208
</simpara></listitem>
210
</variablelist></refsect2>
211
<refsect2 id="IDNA-ACE-PREFIX--CAPS" role="macro">
212
<title>IDNA_ACE_PREFIX</title>
213
<indexterm zone="IDNA-ACE-PREFIX--CAPS"><primary sortas="IDNA_ACE_PREFIX">IDNA_ACE_PREFIX</primary></indexterm><programlisting># define IDNA_ACE_PREFIX "xn--"
216
The IANA allocated prefix to use for IDNA. "xn--"</para>
219
<refsect2 id="idna-strerror" role="function">
220
<title>idna_strerror ()</title>
221
<indexterm zone="idna-strerror"><primary sortas="idna_strerror">idna_strerror</primary></indexterm><programlisting>const <link linkend="char">char</link> * idna_strerror (<link linkend="Idna-rc">Idna_rc</link> rc);</programlisting>
223
Convert a return code integer to a text string. This string can be
224
used to output a diagnostic message to the user.
227
IDNA_SUCCESS: Successful operation. This value is guaranteed to
228
always be zero, the remaining ones are only guaranteed to hold
229
non-zero values, for logical comparison purposes.
230
IDNA_STRINGPREP_ERROR: Error during string preparation.
231
IDNA_PUNYCODE_ERROR: Error during punycode operation.
232
IDNA_CONTAINS_NON_LDH: For IDNA_USE_STD3_ASCII_RULES, indicate that
233
the string contains non-LDH ASCII characters.
234
IDNA_CONTAINS_MINUS: For IDNA_USE_STD3_ASCII_RULES, indicate that
235
the string contains a leading or trailing hyphen-minus (U+002D).
236
IDNA_INVALID_LENGTH: The final output string is not within the
237
(inclusive) range 1 to 63 characters.
238
IDNA_NO_ACE_PREFIX: The string does not contain the ACE prefix
240
IDNA_ROUNDTRIP_VERIFY_ERROR: The ToASCII operation on output
241
string does not equal the input.
242
IDNA_CONTAINS_ACE_PREFIX: The input contains the ACE prefix (for
244
IDNA_ICONV_ERROR: Could not convert string in locale encoding.
245
IDNA_MALLOC_ERROR: Could not allocate buffer (this is typically a
247
IDNA_DLOPEN_ERROR: Could not dlopen the libcidn DSO (only used
248
internally in libc).</para>
250
</para><variablelist role="params">
251
<varlistentry><term><parameter>rc</parameter> :</term>
252
<listitem><simpara> an <link linkend="Idna-rc"><type>Idna_rc</type></link> return code.
253
</simpara></listitem></varlistentry>
254
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns a pointer to a statically allocated string
255
containing a description of the error with the return code <parameter>rc</parameter>.
256
</simpara></listitem></varlistentry>
257
</variablelist></refsect2>
258
<refsect2 id="idna-to-ascii-4i" role="function">
259
<title>idna_to_ascii_4i ()</title>
260
<indexterm zone="idna-to-ascii-4i"><primary sortas="idna_to_ascii_4i">idna_to_ascii_4i</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_ascii_4i (const <link linkend="uint32-t">uint32_t</link> *in,
261
<link linkend="size-t">size_t</link> inlen,
262
<link linkend="char">char</link> *out,
263
<link linkend="int">int</link> flags);</programlisting>
265
The ToASCII operation takes a sequence of Unicode code points that
266
make up one domain label and transforms it into a sequence of code
267
points in the ASCII range (0..7F). If ToASCII succeeds, the
268
original sequence and the resulting sequence are equivalent labels.
271
It is important to note that the ToASCII operation can fail. ToASCII
272
fails if any step of it fails. If any step of the ToASCII operation
273
fails on any label in a domain name, that domain name MUST NOT be used
274
as an internationalized domain name. The method for deadling with this
275
failure is application-specific.
278
The inputs to ToASCII are a sequence of code points, the AllowUnassigned
279
flag, and the UseSTD3ASCIIRules flag. The output of ToASCII is either a
280
sequence of ASCII code points or a failure condition.
283
ToASCII never alters a sequence of code points that are all in the ASCII
284
range to begin with (although it could fail). Applying the ToASCII
285
operation multiple times has exactly the same effect as applying it just
288
</para><variablelist role="params">
289
<varlistentry><term><parameter>in</parameter> :</term>
290
<listitem><simpara> input array with unicode code points.
291
</simpara></listitem></varlistentry>
292
<varlistentry><term><parameter>inlen</parameter> :</term>
293
<listitem><simpara> length of input array with unicode code points.
294
</simpara></listitem></varlistentry>
295
<varlistentry><term><parameter>out</parameter> :</term>
296
<listitem><simpara> output zero terminated string that must have room for at
297
least 63 characters plus the terminating zero.
298
</simpara></listitem></varlistentry>
299
<varlistentry><term><parameter>flags</parameter> :</term>
300
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
301
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
302
</simpara></listitem></varlistentry>
303
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns 0 on success, or an <link linkend="Idna-rc"><type>Idna_rc</type></link> error code.
304
</simpara></listitem></varlistentry>
305
</variablelist></refsect2>
306
<refsect2 id="idna-to-unicode-44i" role="function">
307
<title>idna_to_unicode_44i ()</title>
308
<indexterm zone="idna-to-unicode-44i"><primary sortas="idna_to_unicode_44i">idna_to_unicode_44i</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_unicode_44i (const <link linkend="uint32-t">uint32_t</link> *in,
309
<link linkend="size-t">size_t</link> inlen,
310
<link linkend="uint32-t">uint32_t</link> *out,
311
<link linkend="size-t">size_t</link> *outlen,
312
<link linkend="int">int</link> flags);</programlisting>
314
The ToUnicode operation takes a sequence of Unicode code points
315
that make up one domain label and returns a sequence of Unicode
316
code points. If the input sequence is a label in ACE form, then the
317
result is an equivalent internationalized label that is not in ACE
318
form, otherwise the original sequence is returned unaltered.
321
ToUnicode never fails. If any step fails, then the original input
322
sequence is returned immediately in that step.
325
The Punycode decoder can never output more code points than it
326
inputs, but Nameprep can, and therefore ToUnicode can. Note that
327
the number of octets needed to represent a sequence of code points
328
depends on the particular character encoding used.
331
The inputs to ToUnicode are a sequence of code points, the
332
AllowUnassigned flag, and the UseSTD3ASCIIRules flag. The output of
333
ToUnicode is always a sequence of Unicode code points.</para>
335
</para><variablelist role="params">
336
<varlistentry><term><parameter>in</parameter> :</term>
337
<listitem><simpara> input array with unicode code points.
338
</simpara></listitem></varlistentry>
339
<varlistentry><term><parameter>inlen</parameter> :</term>
340
<listitem><simpara> length of input array with unicode code points.
341
</simpara></listitem></varlistentry>
342
<varlistentry><term><parameter>out</parameter> :</term>
343
<listitem><simpara> output array with unicode code points.
344
</simpara></listitem></varlistentry>
345
<varlistentry><term><parameter>outlen</parameter> :</term>
346
<listitem><simpara> on input, maximum size of output array with unicode code points,
347
on exit, actual size of output array with unicode code points.
348
</simpara></listitem></varlistentry>
349
<varlistentry><term><parameter>flags</parameter> :</term>
350
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
351
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
352
</simpara></listitem></varlistentry>
353
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="Idna-rc"><type>Idna_rc</type></link> error condition, but it must only be
354
used for debugging purposes. The output buffer is always
355
guaranteed to contain the correct data according to the
356
specification (sans malloc induced errors). NB! This means that
357
you normally ignore the return code from this function, as
358
checking it means breaking the standard.
359
</simpara></listitem></varlistentry>
360
</variablelist></refsect2>
361
<refsect2 id="idna-to-ascii-4z" role="function">
362
<title>idna_to_ascii_4z ()</title>
363
<indexterm zone="idna-to-ascii-4z"><primary sortas="idna_to_ascii_4z">idna_to_ascii_4z</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_ascii_4z (const <link linkend="uint32-t">uint32_t</link> *input,
364
<link linkend="char">char</link> **output,
365
<link linkend="int">int</link> flags);</programlisting>
367
Convert UCS-4 domain name to ASCII string. The domain name may
368
contain several labels, separated by dots. The output buffer must
369
be deallocated by the caller.</para>
371
</para><variablelist role="params">
372
<varlistentry><term><parameter>input</parameter> :</term>
373
<listitem><simpara> zero terminated input Unicode string.
374
</simpara></listitem></varlistentry>
375
<varlistentry><term><parameter>output</parameter> :</term>
376
<listitem><simpara> pointer to newly allocated output string.
377
</simpara></listitem></varlistentry>
378
<varlistentry><term><parameter>flags</parameter> :</term>
379
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
380
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
381
</simpara></listitem></varlistentry>
382
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
383
</simpara></listitem></varlistentry>
384
</variablelist></refsect2>
385
<refsect2 id="idna-to-ascii-8z" role="function">
386
<title>idna_to_ascii_8z ()</title>
387
<indexterm zone="idna-to-ascii-8z"><primary sortas="idna_to_ascii_8z">idna_to_ascii_8z</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_ascii_8z (const <link linkend="char">char</link> *input,
388
<link linkend="char">char</link> **output,
389
<link linkend="int">int</link> flags);</programlisting>
391
Convert UTF-8 domain name to ASCII string. The domain name may
392
contain several labels, separated by dots. The output buffer must
393
be deallocated by the caller.</para>
395
</para><variablelist role="params">
396
<varlistentry><term><parameter>input</parameter> :</term>
397
<listitem><simpara> zero terminated input UTF-8 string.
398
</simpara></listitem></varlistentry>
399
<varlistentry><term><parameter>output</parameter> :</term>
400
<listitem><simpara> pointer to newly allocated output string.
401
</simpara></listitem></varlistentry>
402
<varlistentry><term><parameter>flags</parameter> :</term>
403
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
404
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
405
</simpara></listitem></varlistentry>
406
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
407
</simpara></listitem></varlistentry>
408
</variablelist></refsect2>
409
<refsect2 id="idna-to-ascii-lz" role="function">
410
<title>idna_to_ascii_lz ()</title>
411
<indexterm zone="idna-to-ascii-lz"><primary sortas="idna_to_ascii_lz">idna_to_ascii_lz</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_ascii_lz (const <link linkend="char">char</link> *input,
412
<link linkend="char">char</link> **output,
413
<link linkend="int">int</link> flags);</programlisting>
415
Convert domain name in the locale's encoding to ASCII string. The
416
domain name may contain several labels, separated by dots. The
417
output buffer must be deallocated by the caller.</para>
419
</para><variablelist role="params">
420
<varlistentry><term><parameter>input</parameter> :</term>
421
<listitem><simpara> zero terminated input string encoded in the current locale's
423
</simpara></listitem></varlistentry>
424
<varlistentry><term><parameter>output</parameter> :</term>
425
<listitem><simpara> pointer to newly allocated output string.
426
</simpara></listitem></varlistentry>
427
<varlistentry><term><parameter>flags</parameter> :</term>
428
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
429
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
430
</simpara></listitem></varlistentry>
431
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
432
</simpara></listitem></varlistentry>
433
</variablelist></refsect2>
434
<refsect2 id="idna-to-unicode-4z4z" role="function">
435
<title>idna_to_unicode_4z4z ()</title>
436
<indexterm zone="idna-to-unicode-4z4z"><primary sortas="idna_to_unicode_4z4z">idna_to_unicode_4z4z</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_unicode_4z4z (const <link linkend="uint32-t">uint32_t</link> *input,
437
<link linkend="uint32-t">uint32_t</link> **output,
438
<link linkend="int">int</link> flags);</programlisting>
440
Convert possibly ACE encoded domain name in UCS-4 format into a
441
UCS-4 string. The domain name may contain several labels,
442
separated by dots. The output buffer must be deallocated by the
445
</para><variablelist role="params">
446
<varlistentry><term><parameter>input</parameter> :</term>
447
<listitem><simpara> zero-terminated Unicode string.
448
</simpara></listitem></varlistentry>
449
<varlistentry><term><parameter>output</parameter> :</term>
450
<listitem><simpara> pointer to newly allocated output Unicode string.
451
</simpara></listitem></varlistentry>
452
<varlistentry><term><parameter>flags</parameter> :</term>
453
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
454
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
455
</simpara></listitem></varlistentry>
456
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
457
</simpara></listitem></varlistentry>
458
</variablelist></refsect2>
459
<refsect2 id="idna-to-unicode-8z4z" role="function">
460
<title>idna_to_unicode_8z4z ()</title>
461
<indexterm zone="idna-to-unicode-8z4z"><primary sortas="idna_to_unicode_8z4z">idna_to_unicode_8z4z</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_unicode_8z4z (const <link linkend="char">char</link> *input,
462
<link linkend="uint32-t">uint32_t</link> **output,
463
<link linkend="int">int</link> flags);</programlisting>
465
Convert possibly ACE encoded domain name in UTF-8 format into a
466
UCS-4 string. The domain name may contain several labels,
467
separated by dots. The output buffer must be deallocated by the
470
</para><variablelist role="params">
471
<varlistentry><term><parameter>input</parameter> :</term>
472
<listitem><simpara> zero-terminated UTF-8 string.
473
</simpara></listitem></varlistentry>
474
<varlistentry><term><parameter>output</parameter> :</term>
475
<listitem><simpara> pointer to newly allocated output Unicode string.
476
</simpara></listitem></varlistentry>
477
<varlistentry><term><parameter>flags</parameter> :</term>
478
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
479
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
480
</simpara></listitem></varlistentry>
481
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
482
</simpara></listitem></varlistentry>
483
</variablelist></refsect2>
484
<refsect2 id="idna-to-unicode-8z8z" role="function">
485
<title>idna_to_unicode_8z8z ()</title>
486
<indexterm zone="idna-to-unicode-8z8z"><primary sortas="idna_to_unicode_8z8z">idna_to_unicode_8z8z</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_unicode_8z8z (const <link linkend="char">char</link> *input,
487
<link linkend="char">char</link> **output,
488
<link linkend="int">int</link> flags);</programlisting>
490
Convert possibly ACE encoded domain name in UTF-8 format into a
491
UTF-8 string. The domain name may contain several labels,
492
separated by dots. The output buffer must be deallocated by the
495
</para><variablelist role="params">
496
<varlistentry><term><parameter>input</parameter> :</term>
497
<listitem><simpara> zero-terminated UTF-8 string.
498
</simpara></listitem></varlistentry>
499
<varlistentry><term><parameter>output</parameter> :</term>
500
<listitem><simpara> pointer to newly allocated output UTF-8 string.
501
</simpara></listitem></varlistentry>
502
<varlistentry><term><parameter>flags</parameter> :</term>
503
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
504
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
505
</simpara></listitem></varlistentry>
506
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
507
</simpara></listitem></varlistentry>
508
</variablelist></refsect2>
509
<refsect2 id="idna-to-unicode-8zlz" role="function">
510
<title>idna_to_unicode_8zlz ()</title>
511
<indexterm zone="idna-to-unicode-8zlz"><primary sortas="idna_to_unicode_8zlz">idna_to_unicode_8zlz</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_unicode_8zlz (const <link linkend="char">char</link> *input,
512
<link linkend="char">char</link> **output,
513
<link linkend="int">int</link> flags);</programlisting>
515
Convert possibly ACE encoded domain name in UTF-8 format into a
516
string encoded in the current locale's character set. The domain
517
name may contain several labels, separated by dots. The output
518
buffer must be deallocated by the caller.</para>
520
</para><variablelist role="params">
521
<varlistentry><term><parameter>input</parameter> :</term>
522
<listitem><simpara> zero-terminated UTF-8 string.
523
</simpara></listitem></varlistentry>
524
<varlistentry><term><parameter>output</parameter> :</term>
525
<listitem><simpara> pointer to newly allocated output string encoded in the
526
current locale's character set.
527
</simpara></listitem></varlistentry>
528
<varlistentry><term><parameter>flags</parameter> :</term>
529
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
530
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
531
</simpara></listitem></varlistentry>
532
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
533
</simpara></listitem></varlistentry>
534
</variablelist></refsect2>
535
<refsect2 id="idna-to-unicode-lzlz" role="function">
536
<title>idna_to_unicode_lzlz ()</title>
537
<indexterm zone="idna-to-unicode-lzlz"><primary sortas="idna_to_unicode_lzlz">idna_to_unicode_lzlz</primary></indexterm><programlisting><link linkend="int">int</link> idna_to_unicode_lzlz (const <link linkend="char">char</link> *input,
538
<link linkend="char">char</link> **output,
539
<link linkend="int">int</link> flags);</programlisting>
541
Convert possibly ACE encoded domain name in the locale's character
542
set into a string encoded in the current locale's character set.
543
The domain name may contain several labels, separated by dots. The
544
output buffer must be deallocated by the caller.</para>
546
</para><variablelist role="params">
547
<varlistentry><term><parameter>input</parameter> :</term>
548
<listitem><simpara> zero-terminated string encoded in the current locale's
550
</simpara></listitem></varlistentry>
551
<varlistentry><term><parameter>output</parameter> :</term>
552
<listitem><simpara> pointer to newly allocated output string encoded in the
553
current locale's character set.
554
</simpara></listitem></varlistentry>
555
<varlistentry><term><parameter>flags</parameter> :</term>
556
<listitem><simpara> an <link linkend="Idna-flags"><type>Idna_flags</type></link> value, e.g., <link linkend="IDNA-ALLOW-UNASSIGNED--CAPS"><literal>IDNA_ALLOW_UNASSIGNED</literal></link> or
557
<link linkend="IDNA-USE-STD3-ASCII-RULES--CAPS"><literal>IDNA_USE_STD3_ASCII_RULES</literal></link>.
558
</simpara></listitem></varlistentry>
559
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Returns <link linkend="IDNA-SUCCESS--CAPS"><literal>IDNA_SUCCESS</literal></link> on success, or error code.
560
</simpara></listitem></varlistentry>
561
</variablelist></refsect2>
added
removed
doc/reference/xml/idna.xml
