doc/uniconv.texi

   1 @node uniconv.h
   2 @chapter Conversions between Unicode and encodings @code{<uniconv.h>}
   3
   4 This include file declares functions for converting between Unicode strings
   5 and @code{char *} strings in locale encoding or in other specified encodings.
   6
   7 @cindex locale encoding
   8 The following function returns the locale encoding.
   9
  10 @deftypefun {const char *} locale_charset ()
  11 Determines the current locale's character encoding, and canonicalizes it
  12 into one of the canonical names listed in @file{localcharset.h}.
  13 If the canonical name cannot be determined, the result is a non-canonical
  14 name.
  15
  16 The result must not be freed; it is statically allocated.
  17
  18 The result of this function can be used as an argument to the @code{iconv_open}
  19 function in GNU libc, in GNU libiconv, or in the gnulib provided wrapper
  20 around the native @code{iconv_open} function.  It may not work as an argument
  21 to the native @code{iconv_open} function directly.
  22 @end deftypefun
  23
  24 The handling of unconvertible characters during the conversions can be
  25 parametrized through the following enumeration type:
  26
  27 @deftp Type {enum iconv_ilseq_handler}
  28 This type specifies how unconvertible characters in the input are handled.
  29 @end deftp
  30
  31 @deftypevr Constant {enum iconv_ilseq_handler} iconveh_error
  32 This handler causes the function to return with @code{errno} set to
  33 @code{EILSEQ}.
  34 @end deftypevr
  35
  36 @deftypevr Constant {enum iconv_ilseq_handler} iconveh_question_mark
  37 This handler produces one question mark @samp{?} per unconvertible character.
  38 @end deftypevr
  39
  40 @deftypevr Constant {enum iconv_ilseq_handler} iconveh_question_replacement_character
  41 This handler produces one U+FFFD per unconvertible character if that
  42 fits in the target encoding, otherwise one question mark @samp{?} per
  43 unconvertible character.
  44 @end deftypevr
  45
  46 @deftypevr Constant {enum iconv_ilseq_handler} iconveh_escape_sequence
  47 This handler produces an escape sequence @code{\u@var{xxxx}} or
  48 @code{\U@var{xxxxxxxx}} for each unconvertible character.
  49 @end deftypevr
  50
  51 @cindex converting
  52 The following functions convert between strings in a specified encoding and
  53 Unicode strings.
  54
  55 @deftypefun {uint8_t *} u8_conv_from_encoding (const@tie{}char@tie{}*@var{fromcode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler}, const@tie{}char@tie{}*@var{src}, size_t@tie{}@var{srclen}, size_t@tie{}*@var{offsets}, uint8_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
  56 @deftypefunx {uint16_t *} u16_conv_from_encoding (const@tie{}char@tie{}*@var{fromcode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler}, const@tie{}char@tie{}*@var{src}, size_t@tie{}@var{srclen}, size_t@tie{}*@var{offsets}, uint16_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
  57 @deftypefunx {uint32_t *} u32_conv_from_encoding (const@tie{}char@tie{}*@var{fromcode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler}, const@tie{}char@tie{}*@var{src}, size_t@tie{}@var{srclen}, size_t@tie{}*@var{offsets}, uint32_t@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
  58 Converts an entire string, possibly including NUL bytes, from one encoding
  59 to UTF-8 encoding.
  60
  61 Converts a memory region given in encoding @var{fromcode}.  @var{fromcode} is
  62 as for the @code{iconv_open} function.
  63
  64 The input is in the memory region between @var{src} (inclusive) and
  65 @code{@var{src} + @var{srclen}} (exclusive).
  66
  67 If @var{offsets} is not NULL, it should point to an array of @var{srclen}
  68 integers; this array is filled with offsets into the result, i.e@. the
  69 character starting at @code{@var{src}[i]} corresponds to the character starting
  70 at @code{@var{result}[@var{offsets}[i]]}, and other offsets are set to
  71 @code{(size_t)(-1)}.
  72
  73 @code{@var{resultbuf}} and @code{*@var{lengthp}} should be a scratch
  74 buffer and its size, or @code{@var{resultbuf}} can be NULL.
  75
  76 May erase the contents of the memory at @code{@var{resultbuf}}.
  77
  78 If successful: The resulting Unicode string (non-NULL) is returned and
  79 its length stored in @code{*@var{lengthp}}.  The resulting string is
  80 @code{@var{resultbuf}} if no dynamic memory allocation was necessary,
  81 or a freshly allocated memory block otherwise.
  82
  83 In case of error: NULL is returned and @code{errno} is set.
  84 Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
  85 @end deftypefun
  86
  87 @deftypefun {char *} u8_conv_to_encoding (const@tie{}char@tie{}*@var{tocode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler}, const@tie{}uint8_t@tie{}*@var{src}, size_t@tie{}@var{srclen}, size_t@tie{}*@var{offsets}, char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
  88 @deftypefunx {char *} u16_conv_to_encoding (const@tie{}char@tie{}*@var{tocode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler}, const@tie{}uint16_t@tie{}*@var{src}, size_t@tie{}@var{srclen}, size_t@tie{}*@var{offsets}, char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
  89 @deftypefunx {char *} u32_conv_to_encoding (const@tie{}char@tie{}*@var{tocode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler}, const@tie{}uint32_t@tie{}*@var{src}, size_t@tie{}@var{srclen}, size_t@tie{}*@var{offsets}, char@tie{}*@var{resultbuf}, size_t@tie{}*@var{lengthp})
  90 Converts an entire Unicode string, possibly including NUL units, from UTF-8
  91 encoding to a given encoding.
  92
  93 Converts a memory region to encoding @var{tocode}.  @var{tocode} is as for
  94 the @code{iconv_open} function.
  95
  96 The input is in the memory region between @var{src} (inclusive) and
  97 @code{@var{src} + @var{srclen}} (exclusive).
  98
  99 If @var{offsets} is not NULL, it should point to an array of @var{srclen}
 100 integers; this array is filled with offsets into the result, i.e@. the
 101 character starting at @code{@var{src}[i]} corresponds to the character starting
 102 at @code{@var{result}[@var{offsets}[i]]}, and other offsets are set to
 103 @code{(size_t)(-1)}.
 104
 105 @code{@var{resultbuf}} and @code{*@var{lengthp}} should be a scratch
 106 buffer and its size, or @code{@var{resultbuf}} can be NULL.
 107
 108 May erase the contents of the memory at @code{@var{resultbuf}}.
 109
 110 If successful: The resulting Unicode string (non-NULL) is returned and
 111 its length stored in @code{*@var{lengthp}}.  The resulting string is
 112 @code{@var{resultbuf}} if no dynamic memory allocation was necessary,
 113 or a freshly allocated memory block otherwise.
 114
 115 In case of error: NULL is returned and @code{errno} is set.
 116 Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
 117 @end deftypefun
 118
 119 The following functions convert between NUL terminated strings in a specified
 120 encoding and NUL terminated Unicode strings.
 121
 122 @deftypefun {uint8_t *} u8_strconv_from_encoding (const@tie{}char@tie{}*@var{string}, const@tie{}char@tie{}*@var{fromcode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler})
 123 @deftypefunx {uint16_t *} u16_strconv_from_encoding (const@tie{}char@tie{}*@var{string}, const@tie{}char@tie{}*@var{fromcode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler})
 124 @deftypefunx {uint32_t *} u32_strconv_from_encoding (const@tie{}char@tie{}*@var{string}, const@tie{}char@tie{}*@var{fromcode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler})
 125 Converts a NUL terminated string from a given encoding.
 126
 127 The result is @code{malloc} allocated, or NULL (with @var{errno} set) in case of error.
 128
 129 Particular @code{errno} values: @code{EILSEQ}, @code{ENOMEM}.
 130 @end deftypefun
 131
 132 @deftypefun {char *} u8_strconv_to_encoding (const@tie{}uint8_t@tie{}*@var{string}, const@tie{}char@tie{}*@var{tocode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler})
 133 @deftypefunx {char *} u16_strconv_to_encoding (const@tie{}uint16_t@tie{}*@var{string}, const@tie{}char@tie{}*@var{tocode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler})
 134 @deftypefunx {char *} u32_strconv_to_encoding (const@tie{}uint32_t@tie{}*@var{string}, const@tie{}char@tie{}*@var{tocode}, enum@tie{}iconv_ilseq_handler@tie{}@var{handler})
 135 Converts a NUL terminated string to a given encoding.
 136
 137 The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
 138
 139 Particular @code{errno} values: @code{EILSEQ}, @code{ENOMEM}.
 140 @end deftypefun
 141
 142 The following functions are shorthands that convert between NUL terminated
 143 strings in locale encoding and NUL terminated Unicode strings.
 144
 145 @deftypefun {uint8_t *} u8_strconv_from_locale (const@tie{}char@tie{}*@var{string})
 146 @deftypefunx {uint16_t *} u16_strconv_from_locale (const@tie{}char@tie{}*@var{string})
 147 @deftypefunx {uint32_t *} u32_strconv_from_locale (const@tie{}char@tie{}*@var{string})
 148 Converts a NUL terminated string from the locale encoding.
 149
 150 The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
 151
 152 Particular @code{errno} values: @code{ENOMEM}.
 153 @end deftypefun
 154
 155 @deftypefun {char *} u8_strconv_to_locale (const@tie{}uint8_t@tie{}*@var{string})
 156 @deftypefunx {char *} u16_strconv_to_locale (const@tie{}uint16_t@tie{}*@var{string})
 157 @deftypefunx {char *} u32_strconv_to_locale (const@tie{}uint32_t@tie{}*@var{string})
 158 Converts a NUL terminated string to the locale encoding.
 159
 160 The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
 161
 162 Particular @code{errno} values: @code{ENOMEM}.
 163 @end deftypefun