<html lang="en"> <head> <title>Libidn2 0.7</title> <meta http-equiv="Content-Type" content="text/html"> <meta name="description" content="Libidn2 0.7"> <meta name="generator" content="makeinfo 4.13"> <link title="Top" rel="top" href="#Top"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <!-- This manual is for Libidn2 (version 0.7, 5 May 2011), an implementation of IDNA2008 internationalized domain names. Copyright (C) 2011 Simon Josefsson--> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } body { margin: 2%; padding: 0 5%; background: #ffffff; } h1,h2,h3,h4,h5 { font-weight: bold; padding: 5px 5px 5px 5px; background-color: #c2e0ff; color: #336699; } h1 { padding: 2em 2em 2em 5%; color: white; background: #336699; text-align: center; letter-spacing: 3px; } h2 { text-decoration: underline; } pre { margin: 0 5%; padding: 0.5em; } pre.example { border: solid 1px; background: #eeeeff; padding-bottom: 1em; } pre.verbatim { border: solid 1px gray; background: white; padding-bottom: 1em; } div.node { margin: 0 -5% 0 -2%; padding: 0.5em 0.5em; margin-top: 0.5em; margin-bottom: 0.5em; font-weight: bold; } dd, li { padding-top: 0.1em; padding-bottom: 0.1em; } --></style> </head> <body> <h1 class="settitle">Libidn2 0.7</h1> <div class="contents"> <h2>Table of Contents</h2> <ul> <li><a name="toc_Top" href="#Top">Libidn2</a> <li><a name="toc_Introduction" href="#Introduction">1 Introduction</a> <li><a name="toc_Library-Functions" href="#Library-Functions">2 Library Functions</a> <ul> <li><a href="#Library-Functions">2.1 Header file <code>idn2.h</code></a> <li><a href="#Library-Functions">2.2 Core Functions</a> <li><a href="#Library-Functions">2.3 Locale Functions</a> <li><a href="#Library-Functions">2.4 Control Flags</a> <li><a href="#Library-Functions">2.5 Error Handling</a> <li><a href="#Library-Functions">2.6 Return Codes</a> <li><a href="#Library-Functions">2.7 Memory Handling</a> <li><a href="#Library-Functions">2.8 Version Check</a> </li></ul> <li><a name="toc_Examples" href="#Examples">3 Examples</a> <ul> <li><a href="#Lookup">3.1 Lookup</a> <li><a href="#Register">3.2 Register</a> </li></ul> <li><a name="toc_Invoking-idn2" href="#Invoking-idn2">4 Invoking idn2</a> <ul> <li><a href="#Invoking-idn2">4.1 Options</a> <li><a href="#Invoking-idn2">4.2 Environment Variables</a> <li><a href="#Invoking-idn2">4.3 Examples</a> <li><a href="#Invoking-idn2">4.4 Troubleshooting</a> </li></ul> <li><a name="toc_Interface-Index" href="#Interface-Index">Interface Index</a> <li><a name="toc_Concept-Index" href="#Concept-Index">Concept Index</a> </li></ul> </div> <div class="node"> <a name="Top"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Introduction">Introduction</a>, Up: <a rel="up" accesskey="u" href="#dir">(dir)</a> </div> <h2 class="unnumbered">Libidn2</h2> <p>This manual is for Libidn2 (version 0.7, 5 May 2011), an implementation of IDNA2008 internationalized domain names. <p>Copyright © 2011 Simon Josefsson <ul class="menu"> <li><a accesskey="1" href="#Introduction">Introduction</a>: What is Libidn2? <li><a accesskey="2" href="#Library-Functions">Library Functions</a>: Library functions. <li><a accesskey="3" href="#Examples">Examples</a>: Demonstrate how to use the library. <li><a accesskey="4" href="#Invoking-idn2">Invoking idn2</a>: Command line interface to the library. <li><a accesskey="5" href="#Interface-Index">Interface Index</a> <li><a accesskey="6" href="#Concept-Index">Concept Index</a> </ul> <div class="node"> <a name="Introduction"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Library-Functions">Library Functions</a>, Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, Up: <a rel="up" accesskey="u" href="#Top">Top</a> </div> <h2 class="chapter">1 Introduction</h2> <p>Libidn2 is a free software implementation of IDNA2008. <div class="node"> <a name="Library-Functions"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Examples">Examples</a>, Previous: <a rel="previous" accesskey="p" href="#Introduction">Introduction</a>, Up: <a rel="up" accesskey="u" href="#Top">Top</a> </div> <h2 class="chapter">2 Library Functions</h2> <p><a name="index-Library-Functions-1"></a> Below are the interfaces of the Libidn2 library documented. <h3 class="section">2.1 Header file <code>idn2.h</code></h3> <p>To use the functions documented in this chapter, you need to include the file <samp><span class="file">idn2.h</span></samp> like this: <pre class="example"> #include <idn2.h> </pre> <h3 class="section">2.2 Core Functions</h3> <p>When you have the data encoded in UTF-8 form the direct interfaces to the library are as follows. <h4 class="subheading">idn2_lookup_u8</h4> <p><a name="idn2_005flookup_005fu8"></a> <div class="defun"> — Function: int <b>idn2_lookup_u8</b> (<var>const uint8_t * src, uint8_t ** lookupname, int flags</var>)<var><a name="index-idn2_005flookup_005fu8-2"></a></var><br> <blockquote><p><var>src</var>: input zero-terminated UTF-8 string in Unicode NFC normalized form. <p><var>lookupname</var>: newly allocated output variable with name to lookup in DNS. <p><var>flags</var>: optional <code>idn2_flags</code> to modify behaviour. <p>Perform IDNA2008 lookup string conversion on domain name <code>src</code>, 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. <p>Pass <code>IDN2_NFC_INPUT</code> in <code>flags</code> to convert input to NFC form before further processing. Pass <code>IDN2_ALABEL_ROUNDTRIP</code> in <code>flags</code> to convert any input A-labels to U-labels and perform additional testing. Multiple flags may be specified by binary or:ing them together, for example <code>IDN2_NFC_INPUT</code> | <code>IDN2_ALABEL_ROUNDTRIP</code>. <p><strong>Returns:</strong> On successful conversion <code>IDN2_OK</code> is returned, if the output domain or any label would have been too long <code>IDN2_TOO_BIG_DOMAIN</code> or <code>IDN2_TOO_BIG_LABEL</code> is returned, or another error code is returned. </p></blockquote></div> <h4 class="subheading">idn2_register_u8</h4> <p><a name="idn2_005fregister_005fu8"></a> <div class="defun"> — Function: int <b>idn2_register_u8</b> (<var>const uint8_t * ulabel, const uint8_t * alabel, uint8_t ** insertname, int flags</var>)<var><a name="index-idn2_005fregister_005fu8-3"></a></var><br> <blockquote><p><var>ulabel</var>: input zero-terminated UTF-8 and Unicode NFC string, or NULL. <p><var>alabel</var>: input zero-terminated ACE encoded string (xn–), or NULL. <p><var>insertname</var>: newly allocated output variable with name to register in DNS. <p><var>flags</var>: optional <code>idn2_flags</code> to modify behaviour. <p>Perform IDNA2008 register string conversion on domain label <code>ulabel</code> and <code>alabel</code>, as described in section 4 of RFC 5891. Note that the input <code>ulabel</code> must be encoded in UTF-8 and be in Unicode NFC form. <p>Pass <code>IDN2_NFC_INPUT</code> in <code>flags</code> to convert input <code>ulabel</code> to NFC form before further processing. <p>It is recommended to supply both <code>ulabel</code> and <code>alabel</code> for better error checking, but supplying just one of them will work. Passing in only <code>alabel</code> is better than only <code>ulabel</code>. See RFC 5891 section 4 for more information. <p><strong>Returns:</strong> On successful conversion <code>IDN2_OK</code> is returned, when the given <code>ulabel</code> and <code>alabel</code> does not match each other <code>IDN2_UALABEL_MISMATCH</code> is returned, when either of the input labels are too long <code>IDN2_TOO_BIG_LABEL</code> is returned, when <code>alabel</code> does does not appear to be a proper A-label <code>IDN2_INVALID_ALABEL</code> is returned, or another error code is returned. </p></blockquote></div> <h3 class="section">2.3 Locale Functions</h3> <p>As a convenience, the following functions are provided that will convert the input from the locale encoding format to UTF-8 and normalize the string using NFC, and then apply the core functions described earlier. <h4 class="subheading">idn2_lookup_ul</h4> <p><a name="idn2_005flookup_005ful"></a> <div class="defun"> — Function: int <b>idn2_lookup_ul</b> (<var>const char * src, char ** lookupname, int flags</var>)<var><a name="index-idn2_005flookup_005ful-4"></a></var><br> <blockquote><p><var>src</var>: input zero-terminated locale encoded string. <p><var>lookupname</var>: newly allocated output variable with name to lookup in DNS. <p><var>flags</var>: optional <code>idn2_flags</code> to modify behaviour. <p>Perform IDNA2008 lookup string conversion on domain name <code>src</code>, as described in section 5 of RFC 5891. Note that the input is assumed to be encoded in the locale's default coding system, and will be transcoded to UTF-8 and NFC normalized by this function. <p>Pass <code>IDN2_ALABEL_ROUNDTRIP</code> in <code>flags</code> to convert any input A-labels to U-labels and perform additional testing. <p><strong>Returns:</strong> On successful conversion <code>IDN2_OK</code> is returned, if conversion from locale to UTF-8 fails then <code>IDN2_ICONV_FAIL</code> is returned, if the output domain or any label would have been too long <code>IDN2_TOO_BIG_DOMAIN</code> or <code>IDN2_TOO_BIG_LABEL</code> is returned, or another error code is returned. </p></blockquote></div> <h4 class="subheading">idn2_register_ul</h4> <p><a name="idn2_005fregister_005ful"></a> <div class="defun"> — Function: int <b>idn2_register_ul</b> (<var>const char * ulabel, const char * alabel, char ** insertname, int flags</var>)<var><a name="index-idn2_005fregister_005ful-5"></a></var><br> <blockquote><p><var>ulabel</var>: input zero-terminated locale encoded string, or NULL. <p><var>alabel</var>: input zero-terminated ACE encoded string (xn–), or NULL. <p><var>insertname</var>: newly allocated output variable with name to register in DNS. <p><var>flags</var>: optional <code>idn2_flags</code> to modify behaviour. <p>Perform IDNA2008 register string conversion on domain label <code>ulabel</code> and <code>alabel</code>, as described in section 4 of RFC 5891. Note that the input <code>ulabel</code> is assumed to be encoded in the locale's default coding system, and will be transcoded to UTF-8 and NFC normalized by this function. <p>It is recommended to supply both <code>ulabel</code> and <code>alabel</code> for better error checking, but supplying just one of them will work. Passing in only <code>alabel</code> is better than only <code>ulabel</code>. See RFC 5891 section 4 for more information. <p><strong>Returns:</strong> On successful conversion <code>IDN2_OK</code> is returned, when the given <code>ulabel</code> and <code>alabel</code> does not match each other <code>IDN2_UALABEL_MISMATCH</code> is returned, when either of the input labels are too long <code>IDN2_TOO_BIG_LABEL</code> is returned, when <code>alabel</code> does does not appear to be a proper A-label <code>IDN2_INVALID_ALABEL</code> is returned, or another error code is returned. </p></blockquote></div> <h3 class="section">2.4 Control Flags</h3> <p>The <code>flags</code> parameter can take on the following values, or a bit-wise inclusive or of any subset of the parameters: <div class="defun"> — Global flag: idn2_flags <b>IDN2_NFC_INPUT</b><var><a name="index-IDN2_005fNFC_005fINPUT-6"></a></var><br> <blockquote><p>Apply NFC normalization on input. </p></blockquote></div> <div class="defun"> — Global flag: idn2_flags <b>IDN2_ALABEL_ROUNDTRIP</b><var><a name="index-IDN2_005fALABEL_005fROUNDTRIP-7"></a></var><br> <blockquote><p>Apply additional round-trip conversion of A-label inputs. </p></blockquote></div> <h3 class="section">2.5 Error Handling</h3> <h4 class="subheading">idn2_strerror</h4> <p><a name="idn2_005fstrerror"></a> <div class="defun"> — Function: const char * <b>idn2_strerror</b> (<var>int rc</var>)<var><a name="index-idn2_005fstrerror-8"></a></var><br> <blockquote><p><var>rc</var>: return code from another libidn2 function. <p>Convert internal libidn2 error code to a humanly readable string. The returned pointer must not be de-allocated by the caller. <p><strong>Return value:</strong> A humanly readable string describing error. </p></blockquote></div> <h4 class="subheading">idn2_strerror_name</h4> <p><a name="idn2_005fstrerror_005fname"></a> <div class="defun"> — Function: const char * <b>idn2_strerror_name</b> (<var>int rc</var>)<var><a name="index-idn2_005fstrerror_005fname-9"></a></var><br> <blockquote><p><var>rc</var>: return code from another libidn2 function. <p>Convert internal libidn2 error code to a string corresponding to internal header file symbols. For example, idn2_strerror_name(IDN2_MALLOC) will return the string "IDN2_MALLOC". <p>The caller must not attempt to de-allocate the returned string. <p><strong>Return value:</strong> A string corresponding to error code symbol. </p></blockquote></div> <h3 class="section">2.6 Return Codes</h3> <p>The functions normally return 0 on sucess or a negative error code. <div class="defun"> — Return code: idn2_rc <b>IDN2_OK</b><var><a name="index-IDN2_005fOK-10"></a></var><br> <blockquote><p>Successful return. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_MALLOC</b><var><a name="index-IDN2_005fMALLOC-11"></a></var><br> <blockquote><p>Memory allocation error. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_NO_CODESET</b><var><a name="index-IDN2_005fNO_005fCODESET-12"></a></var><br> <blockquote><p>Could not determine locale string encoding format. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_ICONV_FAIL</b><var><a name="index-IDN2_005fICONV_005fFAIL-13"></a></var><br> <blockquote><p>Could not transcode locale string to UTF-8. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_ENCODING_ERROR</b><var><a name="index-IDN2_005fENCODING_005fERROR-14"></a></var><br> <blockquote><p>Unicode data encoding error. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_NFC</b><var><a name="index-IDN2_005fNFC-15"></a></var><br> <blockquote><p>Error normalizing string. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_PUNYCODE_BAD_INPUT</b><var><a name="index-IDN2_005fPUNYCODE_005fBAD_005fINPUT-16"></a></var><br> <blockquote><p>Punycode invalid input. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_PUNYCODE_BIG_OUTPUT</b><var><a name="index-IDN2_005fPUNYCODE_005fBIG_005fOUTPUT-17"></a></var><br> <blockquote><p>Punycode output buffer too small. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_PUNYCODE_OVERFLOW</b><var><a name="index-IDN2_005fPUNYCODE_005fOVERFLOW-18"></a></var><br> <blockquote><p>Punycode conversion would overflow. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_TOO_BIG_DOMAIN</b><var><a name="index-IDN2_005fTOO_005fBIG_005fDOMAIN-19"></a></var><br> <blockquote><p>Domain name longer than 255 characters. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_TOO_BIG_LABEL</b><var><a name="index-IDN2_005fTOO_005fBIG_005fLABEL-20"></a></var><br> <blockquote><p>Domain label longer than 63 characters. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_INVALID_ALABEL</b><var><a name="index-IDN2_005fINVALID_005fALABEL-21"></a></var><br> <blockquote><p>Input A-label is not valid. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_UALABEL_MISMATCH</b><var><a name="index-IDN2_005fUALABEL_005fMISMATCH-22"></a></var><br> <blockquote><p>Input A-label and U-label does not match. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_NOT_NFC</b><var><a name="index-IDN2_005fNOT_005fNFC-23"></a></var><br> <blockquote><p>String is not NFC. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_2HYPHEN</b><var><a name="index-IDN2_005f2HYPHEN-24"></a></var><br> <blockquote><p>String has forbidden two hyphens. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_HYPHEN_STARTEND</b><var><a name="index-IDN2_005fHYPHEN_005fSTARTEND-25"></a></var><br> <blockquote><p>String has forbidden starting/ending hyphen. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_LEADING_COMBINING</b><var><a name="index-IDN2_005fLEADING_005fCOMBINING-26"></a></var><br> <blockquote><p>String has forbidden leading combining character. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_DISALLOWED</b><var><a name="index-IDN2_005fDISALLOWED-27"></a></var><br> <blockquote><p>String has disallowed character. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_CONTEXTJ</b><var><a name="index-IDN2_005fCONTEXTJ-28"></a></var><br> <blockquote><p>String has forbidden context-j character. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_CONTEXTJ_NO_RULE</b><var><a name="index-IDN2_005fCONTEXTJ_005fNO_005fRULE-29"></a></var><br> <blockquote><p>String has context-j character with no rull. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_CONTEXTO</b><var><a name="index-IDN2_005fCONTEXTO-30"></a></var><br> <blockquote><p>String has forbidden context-o character. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_CONTEXTO_NO_RULE</b><var><a name="index-IDN2_005fCONTEXTO_005fNO_005fRULE-31"></a></var><br> <blockquote><p>String has context-o character with no rull. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_UNASSIGNED</b><var><a name="index-IDN2_005fUNASSIGNED-32"></a></var><br> <blockquote><p>String has forbidden unassigned character. </p></blockquote></div> <div class="defun"> — Return code: idn2_rc <b>IDN2_BIDI</b><var><a name="index-IDN2_005fBIDI-33"></a></var><br> <blockquote><p>String has forbidden bi-directional properties. </p></blockquote></div> <h3 class="section">2.7 Memory Handling</h3> <h4 class="subheading">idn2_free</h4> <p><a name="idn2_005ffree"></a> <div class="defun"> — Function: void <b>idn2_free</b> (<var>void * ptr</var>)<var><a name="index-idn2_005ffree-34"></a></var><br> <blockquote><p><var>ptr</var>: pointer to deallocate <p>Call free(3) on the given pointer. <p>This function is typically only useful on systems where the library malloc heap is different from the library caller malloc heap, which happens on Windows when the library is a separate DLL. </p></blockquote></div> <h3 class="section">2.8 Version Check</h3> <p>It is often desirable to check that the version of Libidn2 used is indeed one which fits all requirements. Even with binary compatibility new features may have been introduced but due to problem with the dynamic linker an old version is actually used. So you may want to check that the version is okay right after program startup. <h4 class="subheading">idn2_check_version</h4> <p><a name="idn2_005fcheck_005fversion"></a> <div class="defun"> — Function: const char * <b>idn2_check_version</b> (<var>const char * req_version</var>)<var><a name="index-idn2_005fcheck_005fversion-35"></a></var><br> <blockquote><p><var>req_version</var>: version string to compare with, or NULL. <p>Check IDN2 library version. This function can also be used to read out the version of the library code used. See <code>IDN2_VERSION</code> for a suitable <code>req_version</code> string, it corresponds to the idn2.h header file version. Normally these two version numbers match, but if you are using an application built against an older libidn2 with a newer libidn2 shared library they will be different. <p><strong>Return value:</strong> Check that the version of the library is at minimum the one given as a string in <code>req_version</code> and return the actual version string of the library; return NULL if the condition is not met. If NULL is passed to this function no check is done and only the version string is returned. </p></blockquote></div> <p>The normal way to use the function is to put something similar to the following first in your <code>main</code>: <pre class="example"> if (!idn2_check_version (IDN2_VERSION)) { printf ("idn2_check_version() failed:\n" "Header file incompatible with shared library.\n"); exit(EXIT_FAILURE); } </pre> <div class="node"> <a name="Examples"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Invoking-idn2">Invoking idn2</a>, Previous: <a rel="previous" accesskey="p" href="#Library-Functions">Library Functions</a>, Up: <a rel="up" accesskey="u" href="#Top">Top</a> </div> <h2 class="chapter">3 Examples</h2> <p><a name="index-Examples-36"></a> This chapter contains example code which illustrate how Libidn2 is used when you write your own application. <ul class="menu"> <li><a accesskey="1" href="#Lookup">Lookup</a>: Example IDNA2008 Lookup domain name operation. <li><a accesskey="2" href="#Register">Register</a>: Example IDNA2008 Register label operation. </ul> <div class="node"> <a name="Lookup"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Register">Register</a>, Up: <a rel="up" accesskey="u" href="#Examples">Examples</a> </div> <h3 class="section">3.1 Lookup</h3> <p>This example demonstrates how a domain name is processed before it is lookup in the DNS. <pre class="verbatim">#include <stdio.h> /* printf, fflush, fgets, stdin, perror, fprintf */ #include <string.h> /* strlen */ #include <locale.h> /* setlocale */ #include <stdlib.h> /* free */ #include <idn2.h> /* idn2_lookup_ul, IDN2_OK, idn2_strerror, idn2_strerror_name */ int main (int argc, char *argv[]) { int rc; char src[BUFSIZ]; char *lookupname; setlocale (LC_ALL, ""); printf ("Enter (possibly non-ASCII) domain name to lookup: "); fflush (stdout); if (!fgets (src, sizeof (src), stdin)) { perror ("fgets"); return 1; } src[strlen (src) - 1] = '\0'; rc = idn2_lookup_ul (src, &lookupname, 0); if (rc != IDN2_OK) { fprintf (stderr, "error: %s (%s, %d)\n", idn2_strerror (rc), idn2_strerror_name (rc), rc); return 1; } printf ("IDNA2008 domain name to lookup in DNS: %s\n", lookupname); free (lookupname); return 0; } </pre> <div class="node"> <a name="Register"></a> <p><hr> Previous: <a rel="previous" accesskey="p" href="#Lookup">Lookup</a>, Up: <a rel="up" accesskey="u" href="#Examples">Examples</a> </div> <h3 class="section">3.2 Register</h3> <p>This example demonstrates how a domain label is processed before it is registered in the DNS. <pre class="verbatim">#include <stdio.h> /* printf, fflush, fgets, stdin, perror, fprintf */ #include <string.h> /* strlen */ #include <locale.h> /* setlocale */ #include <stdlib.h> /* free */ #include <idn2.h> /* idn2_register_ul, IDN2_OK, idn2_strerror, idn2_strerror_name */ int main (int argc, char *argv[]) { int rc; char src[BUFSIZ]; char *insertname; setlocale (LC_ALL, ""); printf ("Enter (possibly non-ASCII) label to register: "); fflush (stdout); if (!fgets (src, sizeof (src), stdin)) { perror ("fgets"); return 1; } src[strlen (src) - 1] = '\0'; rc = idn2_register_ul (src, NULL, &insertname, 0); if (rc != IDN2_OK) { fprintf (stderr, "error: %s (%s, %d)\n", idn2_strerror (rc), idn2_strerror_name (rc), rc); return 1; } printf ("IDNA2008 label to register in DNS: %s\n", insertname); free (insertname); return 0; } </pre> <div class="node"> <a name="Invoking-idn2"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Interface-Index">Interface Index</a>, Previous: <a rel="previous" accesskey="p" href="#Examples">Examples</a>, Up: <a rel="up" accesskey="u" href="#Top">Top</a> </div> <h2 class="chapter">4 Invoking idn2</h2> <p><a name="index-idn2-37"></a><a name="index-invoking-_0040command_007bidn2_007d-38"></a><a name="index-command-line-39"></a> <samp><span class="command">idn2</span></samp> translates internationalized domain names to the IDNA2008 encoded format, either for lookup or registration. <p>If strings are specified on the command line, they are used as input and the computed output is printed to standard output <code>stdout</code>. If no strings are specified on the command line, the program read data, line by line, from the standard input <code>stdin</code>, and print the computed output to standard output. What processing is performed (e.g., lookup or register) is indicated by options. If any errors are encountered, the execution of the applications is aborted. <p>All strings are expected to be encoded in the preferred charset used by your locale. Use <code>--debug</code> to find out what this charset is. On POSIX systems you may use the <code>LANG</code> environment variable to specify a different locale. <p>To process a string that starts with <code>-</code>, for example <code>-foo</code>, use <code>--</code> to signal the end of parameters, as in <code>idn2 -r -- -foo</code>. <h3 class="section">4.1 Options</h3> <p><code>idn2</code> recognizes these commands: <pre class="verbatim"> -h, --help Print help and exit -V, --version Print version and exit -l, --lookup Lookup domain name (default) -r, --register Register label --debug Print debugging information --quiet Silent operation </pre> <h3 class="section">4.2 Environment Variables</h3> <p>On POSIX systems the <var>LANG</var> environment variable can be used to override the system locale for the command being invoked. The system locale may influence what character set is used to decode data (i.e., strings on the command line or data read from the standard input stream), and to encode data to the standard output. If your system is set up correctly, however, the application will use the correct locale and character set automatically. Example usage: <pre class="example"> $ LANG=en_US.UTF-8 idn2 ... </pre> <h3 class="section">4.3 Examples</h3> <p>Standard usage, reading input from standard input and disabling license and usage instructions: <pre class="example"> jas@latte:~$ idn2 --quiet räksmörgås.se xn--rksmrgs-5wao1o.se ... </pre> <p>Reading input from the command line: <pre class="example"> jas@latte:~$ idn2 räksmörgås.se blåbærgrød.no xn--rksmrgs-5wao1o.se xn--blbrgrd-fxak7p.no jas@latte:~$ </pre> <p>Testing the IDNA2008 Register function: <pre class="example"> jas@latte:~$ idn2 --register fußball xn--fuball-cta jas@latte:~$ </pre> <h3 class="section">4.4 Troubleshooting</h3> <p>Getting character data encoded right, and making sure Libidn2 use the same encoding, can be difficult. The reason for this is that most systems may encode character data in more than one character encoding, i.e., using <code>UTF-8</code> together with <code>ISO-8859-1</code> or <code>ISO-2022-JP</code>. This problem is likely to continue to exist until only one character encoding come out as the evolutionary winner, or (more likely, at least to some extents) forever. <p>The first step to troubleshooting character encoding problems with Libidn2 is to use the ‘<samp><span class="samp">--debug</span></samp>’ parameter to find out which character set encoding ‘<samp><span class="samp">idn2</span></samp>’ believe your locale uses. <pre class="example"> jas@latte:~$ idn2 --debug --quiet "" Charset: UTF-8 jas@latte:~$ </pre> <p>If it prints <code>ANSI_X3.4-1968</code> (i.e., <code>US-ASCII</code>), this indicate you have not configured your locale properly. To configure the locale, you can, for example, use ‘<samp><span class="samp">LANG=sv_SE.UTF-8; export LANG</span></samp>’ at a <code>/bin/sh</code> prompt, to set up your locale for a Swedish environment using <code>UTF-8</code> as the encoding. <p>Sometimes ‘<samp><span class="samp">idn2</span></samp>’ appear to be unable to translate from your system locale into <code>UTF-8</code> (which is used internally), and you will get an error message like this: <pre class="example"> idn2: lookup: could not convert string to UTF-8 </pre> <p>One explanation is that you didn't install the ‘<samp><span class="samp">iconv</span></samp>’ conversion tools. You can find it as a standalone library in GNU Libiconv (<a href="http://www.gnu.org/software/libiconv/">http://www.gnu.org/software/libiconv/</a>). On many GNU/Linux systems, this library is part of the system, but you may have to install additional packages to be able to use it. <p>Another explanation is that the error is correct and you are feeding ‘<samp><span class="samp">idn2</span></samp>’ invalid data. This can happen inadvertently if you are not careful with the character set encoding you use. For example, if your shell run in a <code>ISO-8859-1</code> environment, and you invoke ‘<samp><span class="samp">idn2</span></samp>’ with the ‘<samp><span class="samp">LANG</span></samp>’ environment variable as follows, you will feed it <code>ISO-8859-1</code> characters but force it to believe they are <code>UTF-8</code>. Naturally this will lead to an error, unless the byte sequences happen to be valid <code>UTF-8</code>. Note that even if you don't get an error, the output may be incorrect in this situation, because <code>ISO-8859-1</code> and <code>UTF-8</code> does not in general encode the same characters as the same byte sequences. <pre class="example"> jas@latte:~$ idn2 --quiet --debug "" Charset: ISO-8859-1 jas@latte:~$ LANG=sv_SE.UTF-8 idn2 --debug räksmörgås Charset: UTF-8 input[0] = 0x72 input[1] = 0xc3 input[2] = 0xa4 input[3] = 0xc3 input[4] = 0xa4 input[5] = 0x6b input[6] = 0x73 input[7] = 0x6d input[8] = 0xc3 input[9] = 0xb6 input[10] = 0x72 input[11] = 0x67 input[12] = 0xc3 input[13] = 0xa5 input[14] = 0x73 UCS-4 input[0] = U+0072 UCS-4 input[1] = U+00e4 UCS-4 input[2] = U+00e4 UCS-4 input[3] = U+006b UCS-4 input[4] = U+0073 UCS-4 input[5] = U+006d UCS-4 input[6] = U+00f6 UCS-4 input[7] = U+0072 UCS-4 input[8] = U+0067 UCS-4 input[9] = U+00e5 UCS-4 input[10] = U+0073 output[0] = 0x72 output[1] = 0xc3 output[2] = 0xa4 output[3] = 0xc3 output[4] = 0xa4 output[5] = 0x6b output[6] = 0x73 output[7] = 0x6d output[8] = 0xc3 output[9] = 0xb6 output[10] = 0x72 output[11] = 0x67 output[12] = 0xc3 output[13] = 0xa5 output[14] = 0x73 UCS-4 output[0] = U+0072 UCS-4 output[1] = U+00e4 UCS-4 output[2] = U+00e4 UCS-4 output[3] = U+006b UCS-4 output[4] = U+0073 UCS-4 output[5] = U+006d UCS-4 output[6] = U+00f6 UCS-4 output[7] = U+0072 UCS-4 output[8] = U+0067 UCS-4 output[9] = U+00e5 UCS-4 output[10] = U+0073 xn--rksmrgs-5waap8p jas@latte:~$ </pre> <p>The sense moral here is to forget about ‘<samp><span class="samp">LANG</span></samp>’ (instead, configure your system locale properly) unless you know what you are doing, and if you want to use ‘<samp><span class="samp">LANG</span></samp>’, do it carefully and after verifying with ‘<samp><span class="samp">--debug</span></samp>’ that you get the desired results. <div class="node"> <a name="Interface-Index"></a> <p><hr> Next: <a rel="next" accesskey="n" href="#Concept-Index">Concept Index</a>, Previous: <a rel="previous" accesskey="p" href="#Invoking-idn2">Invoking idn2</a>, Up: <a rel="up" accesskey="u" href="#Top">Top</a> </div> <h2 class="unnumbered">Interface Index</h2> <ul class="index-fn" compact> <li><a href="#index-idn2_005fcheck_005fversion-35"><code>idn2_check_version</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005ffree-34"><code>idn2_free</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005flookup_005fu8-2"><code>idn2_lookup_u8</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005flookup_005ful-4"><code>idn2_lookup_ul</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005fregister_005fu8-3"><code>idn2_register_u8</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005fregister_005ful-5"><code>idn2_register_ul</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005fstrerror-8"><code>idn2_strerror</code></a>: <a href="#Library-Functions">Library Functions</a></li> <li><a href="#index-idn2_005fstrerror_005fname-9"><code>idn2_strerror_name</code></a>: <a href="#Library-Functions">Library Functions</a></li> </ul><div class="node"> <a name="Concept-Index"></a> <p><hr> Previous: <a rel="previous" accesskey="p" href="#Interface-Index">Interface Index</a>, Up: <a rel="up" accesskey="u" href="#Top">Top</a> </div> <h2 class="unnumbered">Concept Index</h2> <ul class="index-cp" compact> <li><a href="#index-command-line-39">command line</a>: <a href="#Invoking-idn2">Invoking idn2</a></li> <li><a href="#index-Examples-36">Examples</a>: <a href="#Examples">Examples</a></li> <li><a href="#index-idn2-37"><code>idn2</code></a>: <a href="#Invoking-idn2">Invoking idn2</a></li> <li><a href="#index-invoking-_0040command_007bidn2_007d-38">invoking <samp><span class="command">idn2</span></samp></a>: <a href="#Invoking-idn2">Invoking idn2</a></li> <li><a href="#index-Library-Functions-1">Library Functions</a>: <a href="#Library-Functions">Library Functions</a></li> </ul></body></html>