manpagez: man pages & more
info libidn2
Home | html | info | man

libidn2: Library Functions

 
 2 Library Functions
 *******************
 
 Below are the interfaces of the Libidn2 library documented.
 
 2.1 Header file ‘idn2.h’
 ========================
 
 To use the functions documented in this chapter, you need to include the
 file ‘idn2.h’ like this:
 
      #include <idn2.h>
 
 2.2 Core Functions
 ==================
 
 When you have the data encoded in UTF-8 form the direct interfaces to
 the library are as follows.
 
 idn2_to_ascii_8z
 ----------------
 
  -- Function: int idn2_to_ascii_8z (const char * INPUT, char ** OUTPUT,
           int FLAGS)
      INPUT: zero terminated input UTF-8 string.
 
      OUTPUT: pointer to newly allocated output string.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Convert UTF-8 domain name to ASCII string using the IDNA2008 rules.
      The domain name may contain several labels, separated by dots.  The
      output buffer must be deallocated by the caller.
 
      When unsure, it is recommended to call this function with the
      ‘IDN2_NONTRANSITIONAL’ and ‘IDN2_NFC_INPUT’ flags.
 
      Return value: Returns ‘IDN2_OK’ on success, or error code.
 
      *Since:* 2.0.0
 
 idn2_to_unicode_8z8z
 --------------------
 
  -- Function: int idn2_to_unicode_8z8z (const char * INPUT, char **
           OUTPUT, int FLAGS)
      INPUT: Input zero-terminated UTF-8 string.
 
      OUTPUT: Newly allocated UTF-8 output string.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Converts a possibly ACE encoded domain name in UTF-8 format into a
      UTF-8 string (punycode decoding).  The output buffer will be
      zero-terminated and must be deallocated by the caller.
 
      ‘output’ may be NULL to test lookup of ‘input’ without allocating
      memory.
 
      *Since:* 2.0.0
 
 idn2_lookup_u8
 --------------
 
  -- Function: int idn2_lookup_u8 (const uint8_t * SRC, uint8_t **
           LOOKUPNAME, int FLAGS)
      SRC: input zero-terminated UTF-8 string in Unicode NFC normalized
      form.
 
      LOOKUPNAME: newly allocated output variable with name to lookup in
      DNS.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Perform IDNA2008 lookup string conversion on domain name ‘src’ , 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.
 
      Pass ‘IDN2_NFC_INPUT’ in ‘flags’ to convert input to NFC form
      before further processing.  ‘IDN2_TRANSITIONAL’ and
      ‘IDN2_NONTRANSITIONAL’ do already imply ‘IDN2_NFC_INPUT’ .  Pass
      ‘IDN2_ALABEL_ROUNDTRIP’ in ‘flags’ to convert any input A-labels to
      U-labels and perform additional testing (not implemented yet).
      Pass ‘IDN2_TRANSITIONAL’ to enable Unicode TR46 transitional
      processing, and ‘IDN2_NONTRANSITIONAL’ to enable Unicode TR46
      non-transitional processing.  Multiple flags may be specified by
      binary or:ing them together.
 
      After version 2.0.3: ‘IDN2_USE_STD3_ASCII_RULES’ disabled by
      default.  Previously we were eliminating non-STD3 characters from
      domain strings such as _443._tcp.example.com, or IPs 1.2.3.4/24
      provided to libidn2 functions.  That was an unexpected regression
      for applications switching from libidn and thus it is no longer
      applied by default.  Use ‘IDN2_USE_STD3_ASCII_RULES’ to enable that
      behavior again.
 
      After version 0.11: ‘lookupname’ may be NULL to test lookup of
      ‘src’ without allocating memory.
 
      *Returns:* On successful conversion ‘IDN2_OK’ is returned, if the
      output domain or any label would have been too long
      ‘IDN2_TOO_BIG_DOMAIN’ or ‘IDN2_TOO_BIG_LABEL’ is returned, or
      another error code is returned.
 
      *Since:* 0.1
 
 idn2_register_u8
 ----------------
 
  -- Function: int idn2_register_u8 (const uint8_t * ULABEL, const
           uint8_t * ALABEL, uint8_t ** INSERTNAME, int FLAGS)
      ULABEL: input zero-terminated UTF-8 and Unicode NFC string, or
      NULL.
 
      ALABEL: input zero-terminated ACE encoded string (xn–), or NULL.
 
      INSERTNAME: newly allocated output variable with name to register
      in DNS.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Perform IDNA2008 register string conversion on domain label
      ‘ulabel’ and ‘alabel’ , as described in section 4 of RFC 5891.
      Note that the input ‘ulabel’ must be encoded in UTF-8 and be in
      Unicode NFC form.
 
      Pass ‘IDN2_NFC_INPUT’ in ‘flags’ to convert input ‘ulabel’ to NFC
      form before further processing.
 
      It is recommended to supply both ‘ulabel’ and ‘alabel’ for better
      error checking, but supplying just one of them will work.  Passing
      in only ‘alabel’ is better than only ‘ulabel’ .  See RFC 5891
      section 4 for more information.
 
      After version 0.11: ‘insertname’ may be NULL to test conversion of
      ‘src’ without allocating memory.
 
      *Returns:* On successful conversion ‘IDN2_OK’ is returned, when the
      given ‘ulabel’ and ‘alabel’ does not match each other
      ‘IDN2_UALABEL_MISMATCH’ is returned, when either of the input
      labels are too long ‘IDN2_TOO_BIG_LABEL’ is returned, when ‘alabel’
      does does not appear to be a proper A-label ‘IDN2_INVALID_ALABEL’
      is returned, or another error code is returned.
 
 2.3 Locale Functions
 ====================
 
 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.
 
 idn2_to_ascii_lz
 ----------------
 
  -- Function: int idn2_to_ascii_lz (const char * INPUT, char ** OUTPUT,
           int FLAGS)
      INPUT: zero terminated input UTF-8 string.
 
      OUTPUT: pointer to newly allocated output string.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Convert a domain name in locale’s encoding to ASCII string using
      the IDNA2008 rules.  The domain name may contain several labels,
      separated by dots.  The output buffer must be deallocated by the
      caller.
 
      When unsure, it is recommended to call this function with the
      ‘IDN2_NONTRANSITIONAL’ and ‘IDN2_NFC_INPUT’ flags.
 
      *Returns:* ‘IDN2_OK’ on success, or error code.  Same as described
      in ‘idn2_lookup_ul()’ documentation.
 
      *Since:* 2.0.0
 
 idn2_to_unicode_8zlz
 --------------------
 
  -- Function: int idn2_to_unicode_8zlz (const char * INPUT, char **
           OUTPUT, int FLAGS)
      INPUT: Input zero-terminated UTF-8 string.
 
      OUTPUT: Newly allocated output string in current locale’s character
      set.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Converts a possibly ACE encoded domain name in UTF-8 format into a
      string encoded in the current locale’s character set (punycode
      decoding).  The output buffer will be zero-terminated and must be
      deallocated by the caller.
 
      ‘output’ may be NULL to test lookup of ‘input’ without allocating
      memory.
 
      *Since:* 2.0.0
 
 idn2_to_unicode_lzlz
 --------------------
 
  -- Function: int idn2_to_unicode_lzlz (const char * INPUT, char **
           OUTPUT, int FLAGS)
      INPUT: Input zero-terminated string encoded in the current locale’s
      character set.
 
      OUTPUT: Newly allocated output string in current locale’s character
      set.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Converts a possibly ACE encoded domain name in the locale’s
      character set into a string encoded in the current locale’s
      character set (punycode decoding).  The output buffer will be
      zero-terminated and must be deallocated by the caller.
 
      ‘output’ may be NULL to test lookup of ‘input’ without allocating
      memory.
 
      *Since:* 2.0.0
 
 idn2_lookup_ul
 --------------
 
  -- Function: int idn2_lookup_ul (const char * SRC, char ** LOOKUPNAME,
           int FLAGS)
      SRC: input zero-terminated locale encoded string.
 
      LOOKUPNAME: newly allocated output variable with name to lookup in
      DNS.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Perform IDNA2008 lookup string conversion on domain name ‘src’ , 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.
 
      Pass ‘IDN2_ALABEL_ROUNDTRIP’ in ‘flags’ to convert any input
      A-labels to U-labels and perform additional testing.  Pass
      ‘IDN2_TRANSITIONAL’ to enable Unicode TR46 transitional processing,
      and ‘IDN2_NONTRANSITIONAL’ to enable Unicode TR46 non-transitional
      processing.  Multiple flags may be specified by binary or:ing them
      together, for example ‘IDN2_ALABEL_ROUNDTRIP’ |
      ‘IDN2_NONTRANSITIONAL’ .  The ‘IDN2_NFC_INPUT’ in ‘flags’ is always
      enabled in this function.
 
      After version 0.11: ‘lookupname’ may be NULL to test lookup of
      ‘src’ without allocating memory.
 
      *Returns:* On successful conversion ‘IDN2_OK’ is returned, if
      conversion from locale to UTF-8 fails then ‘IDN2_ICONV_FAIL’ is
      returned, if the output domain or any label would have been too
      long ‘IDN2_TOO_BIG_DOMAIN’ or ‘IDN2_TOO_BIG_LABEL’ is returned, or
      another error code is returned.
 
      *Since:* 0.1
 
 idn2_register_ul
 ----------------
 
  -- Function: int idn2_register_ul (const char * ULABEL, const char *
           ALABEL, char ** INSERTNAME, int FLAGS)
      ULABEL: input zero-terminated locale encoded string, or NULL.
 
      ALABEL: input zero-terminated ACE encoded string (xn–), or NULL.
 
      INSERTNAME: newly allocated output variable with name to register
      in DNS.
 
      FLAGS: optional ‘idn2_flags’ to modify behaviour.
 
      Perform IDNA2008 register string conversion on domain label
      ‘ulabel’ and ‘alabel’ , as described in section 4 of RFC 5891.
      Note that the input ‘ulabel’ 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.
 
      It is recommended to supply both ‘ulabel’ and ‘alabel’ for better
      error checking, but supplying just one of them will work.  Passing
      in only ‘alabel’ is better than only ‘ulabel’ .  See RFC 5891
      section 4 for more information.
 
      After version 0.11: ‘insertname’ may be NULL to test conversion of
      ‘src’ without allocating memory.
 
      *Returns:* On successful conversion ‘IDN2_OK’ is returned, when the
      given ‘ulabel’ and ‘alabel’ does not match each other
      ‘IDN2_UALABEL_MISMATCH’ is returned, when either of the input
      labels are too long ‘IDN2_TOO_BIG_LABEL’ is returned, when ‘alabel’
      does does not appear to be a proper A-label ‘IDN2_INVALID_ALABEL’
      is returned, or another error code is returned.
 
 2.4 Control Flags
 =================
 
 The ‘flags’ parameter can take on the following values, or a bit-wise
 inclusive or of any subset of the parameters:
 
  -- Global flag: idn2_flags IDN2_NFC_INPUT
      Apply NFC normalization on input.
 
  -- Global flag: idn2_flags IDN2_ALABEL_ROUNDTRIP
      Apply additional round-trip conversion of A-label inputs.
 
  -- Global flag: idn2_flags IDN2_TRANSITIONAL
      Perform Unicode TR46 transitional processing.
 
  -- Global flag: idn2_flags IDN2_NONTRANSITIONAL
      Perform Unicode TR46 non-transitional processing.
 
 2.5 Error Handling
 ==================
 
 idn2_strerror
 -------------
 
  -- Function: const char * idn2_strerror (int RC)
      RC: return code from another libidn2 function.
 
      Convert internal libidn2 error code to a humanly readable string.
      The returned pointer must not be de-allocated by the caller.
 
      Return value: A humanly readable string describing error.
 
 idn2_strerror_name
 ------------------
 
  -- Function: const char * idn2_strerror_name (int RC)
      RC: return code from another libidn2 function.
 
      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".
 
      The caller must not attempt to de-allocate the returned string.
 
      Return value: A string corresponding to error code symbol.
 
 2.6 Return Codes
 ================
 
 The functions normally return 0 on sucess or a negative error code.
 
  -- Return code: idn2_rc IDN2_OK
      Successful return.
 
  -- Return code: idn2_rc IDN2_MALLOC
      Memory allocation error.
 
  -- Return code: idn2_rc IDN2_NO_CODESET
      Could not determine locale string encoding format.
 
  -- Return code: idn2_rc IDN2_ICONV_FAIL
      Could not transcode locale string to UTF-8.
 
  -- Return code: idn2_rc IDN2_ENCODING_ERROR
      Unicode data encoding error.
 
  -- Return code: idn2_rc IDN2_NFC
      Error normalizing string.
 
  -- Return code: idn2_rc IDN2_PUNYCODE_BAD_INPUT
      Punycode invalid input.
 
  -- Return code: idn2_rc IDN2_PUNYCODE_BIG_OUTPUT
      Punycode output buffer too small.
 
  -- Return code: idn2_rc IDN2_PUNYCODE_OVERFLOW
      Punycode conversion would overflow.
 
  -- Return code: idn2_rc IDN2_TOO_BIG_DOMAIN
      Domain name longer than 255 characters.
 
  -- Return code: idn2_rc IDN2_TOO_BIG_LABEL
      Domain label longer than 63 characters.
 
  -- Return code: idn2_rc IDN2_INVALID_ALABEL
      Input A-label is not valid.
 
  -- Return code: idn2_rc IDN2_UALABEL_MISMATCH
      Input A-label and U-label does not match.
 
  -- Return code: idn2_rc IDN2_INVALID_FLAGS
      Invalid combination of flags.
 
  -- Return code: idn2_rc IDN2_NOT_NFC
      String is not NFC.
 
  -- Return code: idn2_rc IDN2_2HYPHEN
      String has forbidden two hyphens.
 
  -- Return code: idn2_rc IDN2_HYPHEN_STARTEND
      String has forbidden starting/ending hyphen.
 
  -- Return code: idn2_rc IDN2_LEADING_COMBINING
      String has forbidden leading combining character.
 
  -- Return code: idn2_rc IDN2_DISALLOWED
      String has disallowed character.
 
  -- Return code: idn2_rc IDN2_CONTEXTJ
      String has forbidden context-j character.
 
  -- Return code: idn2_rc IDN2_CONTEXTJ_NO_RULE
      String has context-j character with no rull.
 
  -- Return code: idn2_rc IDN2_CONTEXTO
      String has forbidden context-o character.
 
  -- Return code: idn2_rc IDN2_CONTEXTO_NO_RULE
      String has context-o character with no rull.
 
  -- Return code: idn2_rc IDN2_UNASSIGNED
      String has forbidden unassigned character.
 
  -- Return code: idn2_rc IDN2_BIDI
      String has forbidden bi-directional properties.
 
  -- Return code: idn2_rc IDN2_DOT_IN_LABEL
      Label has forbidden dot (TR46).
 
  -- Return code: idn2_rc IDN2_INVALID_TRANSITIONAL
      Label has character forbidden in transitional mode (TR46).
 
  -- Return code: idn2_rc IDN2_INVALID_NONTRANSITIONAL
      Label has character forbidden in non-transitional mode (TR46).
 
 2.7 Memory Handling
 ===================
 
 idn2_free
 ---------
 
  -- Function: void idn2_free (void * PTR)
      PTR: pointer to deallocate
 
      Call free(3) on the given pointer.
 
      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.
 
 2.8 Version Check
 =================
 
 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.
 
 idn2_check_version
 ------------------
 
  -- Function: const char * idn2_check_version (const char * REQ_VERSION)
      REQ_VERSION: version string to compare with, or NULL.
 
      Check IDN2 library version.  This function can also be used to read
      out the version of the library code used.  See ‘IDN2_VERSION’ for a
      suitable ‘req_version’ 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.
 
      Return value: Check that the version of the library is at minimum
      the one given as a string in ‘req_version’ 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.
 
    The normal way to use the function is to put something similar to the
 following first in your ‘main’:
 
        if (!idn2_check_version (IDN2_VERSION))
          {
            printf ("idn2_check_version() failed:\n"
                    "Header file incompatible with shared library.\n");
            exit(EXIT_FAILURE);
          }
 
© manpagez.com 2000-2018
Individual documents may contain additional copyright information.