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{config.charset}.
  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_escape_sequence
  41 This handler produces an escape sequence @code{\u@var{xxxx}} or
  42 @code{\U@var{xxxxxxxx}} for each unconvertible character.
  43 @end deftypevr
  44
  45 @cindex converting
  46 The following functions convert between strings in a specified encoding and
  47 Unicode strings.
  48
  49 @deftypefun {uint8_t *} u8_conv_from_encoding (const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler}, const char *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, uint8_t *@var{resultbuf}, size_t *@var{lengthp})
  50 @deftypefunx {uint16_t *} u16_conv_from_encoding (const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler}, const char *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, uint16_t *@var{resultbuf}, size_t *@var{lengthp})
  51 @deftypefunx {uint32_t *} u32_conv_from_encoding (const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler}, const char *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, uint32_t *@var{resultbuf}, size_t *@var{lengthp})
  52 Converts an entire string, possibly including NUL bytes, from one encoding
  53 to UTF-8 encoding.
  54
  55 Converts a memory region given in encoding @var{fromcode}.  @var{fromcode} is
  56 as for the @code{iconv_open} function.
  57
  58 The input is in the memory region between @var{src} (inclusive) and
  59 @code{@var{src} + @var{srclen}} (exclusive).
  60
  61 If @var{offsets} is not NULL, it should point to an array of @var{srclen}
  62 integers; this array is filled with offsets into the result, i.e@. the
  63 character starting at @code{@var{src}[i]} corresponds to the character starting
  64 at @code{@var{result}[@var{offsets}[i]]}, and other offsets are set to
  65 @code{(size_t)(-1)}.
  66
  67 @code{@var{resultbuf}} and @code{*@var{lengthp}} should be a scratch
  68 buffer and its size, or @code{@var{resultbuf}} can be NULL.
  69
  70 May erase the contents of the memory at @code{@var{resultbuf}}.
  71
  72 If successful: The resulting Unicode string (non-NULL) is returned and
  73 its length stored in @code{*@var{lengthp}}.  The resulting string is
  74 @code{@var{resultbuf}} if no dynamic memory allocation was necessary,
  75 or a freshly allocated memory block otherwise.
  76
  77 In case of error: NULL is returned and @code{errno} is set.
  78 Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
  79 @end deftypefun
  80
  81 @deftypefun {char *} u8_conv_to_encoding (const char *@var{tocode}, enum iconv_ilseq_handler @var{handler}, const uint8_t *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, char *@var{resultbuf}, size_t *@var{lengthp})
  82 @deftypefunx {char *} u16_conv_to_encoding (const char *@var{tocode}, enum iconv_ilseq_handler @var{handler}, const uint16_t *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, char *@var{resultbuf}, size_t *@var{lengthp})
  83 @deftypefunx {char *} u32_conv_to_encoding (const char *@var{tocode}, enum iconv_ilseq_handler @var{handler}, const uint32_t *@var{src}, size_t @var{srclen}, size_t *@var{offsets}, char *@var{resultbuf}, size_t *@var{lengthp})
  84 Converts an entire Unicode string, possibly including NUL units, from UTF-8
  85 encoding to a given encoding.
  86
  87 Converts a memory region to encoding @var{tocode}.  @var{tocode} is as for
  88 the @code{iconv_open} function.
  89
  90 The input is in the memory region between @var{src} (inclusive) and
  91 @code{@var{src} + @var{srclen}} (exclusive).
  92
  93 If @var{offsets} is not NULL, it should point to an array of @var{srclen}
  94 integers; this array is filled with offsets into the result, i.e@. the
  95 character starting at @code{@var{src}[i]} corresponds to the character starting
  96 at @code{@var{result}[@var{offsets}[i]]}, and other offsets are set to
  97 @code{(size_t)(-1)}.
  98
  99 @code{@var{resultbuf}} and @code{*@var{lengthp}} should be a scratch
 100 buffer and its size, or @code{@var{resultbuf}} can be NULL.
 101
 102 May erase the contents of the memory at @code{@var{resultbuf}}.
 103
 104 If successful: The resulting Unicode string (non-NULL) is returned and
 105 its length stored in @code{*@var{lengthp}}.  The resulting string is
 106 @code{@var{resultbuf}} if no dynamic memory allocation was necessary,
 107 or a freshly allocated memory block otherwise.
 108
 109 In case of error: NULL is returned and @code{errno} is set.
 110 Particular @code{errno} values: @code{EINVAL}, @code{EILSEQ}, @code{ENOMEM}.
 111 @end deftypefun
 112
 113 The following functions convert between NUL terminated strings in a specified
 114 encoding and NUL terminated Unicode strings.
 115
 116 @deftypefun {uint8_t *} u8_strconv_from_encoding (const char *@var{string}, const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler})
 117 @deftypefunx {uint16_t *} u16_strconv_from_encoding (const char *@var{string}, const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler})
 118 @deftypefunx {uint32_t *} u32_strconv_from_encoding (const char *@var{string}, const char *@var{fromcode}, enum iconv_ilseq_handler @var{handler})
 119 Converts a NUL terminated string from a given encoding.
 120
 121 The result is @code{malloc} allocated, or NULL (with @var{errno} set) in case of error.
 122
 123 Particular @code{errno} values: @code{EILSEQ}, @code{ENOMEM}.
 124 @end deftypefun
 125
 126 @deftypefun {char *} u8_strconv_to_encoding (const uint8_t *@var{string}, const char *@var{tocode}, enum iconv_ilseq_handler @var{handler})
 127 @deftypefunx {char *} u16_strconv_to_encoding (const uint16_t *@var{string}, const char *@var{tocode}, enum iconv_ilseq_handler @var{handler})
 128 @deftypefunx {char *} u32_strconv_to_encoding (const uint32_t *@var{string}, const char *@var{tocode}, enum iconv_ilseq_handler @var{handler})
 129 Converts a NUL terminated string to a given encoding.
 130
 131 The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
 132
 133 Particular @code{errno} values: @code{EILSEQ}, @code{ENOMEM}.
 134 @end deftypefun
 135
 136 The following functions are shorthands that convert between NUL terminated
 137 strings in locale encoding and NUL terminated Unicode strings.
 138
 139 @deftypefun {uint8_t *} u8_strconv_from_locale (const char *@var{string})
 140 @deftypefunx {uint16_t *} u16_strconv_from_locale (const char *@var{string})
 141 @deftypefunx {uint32_t *} u32_strconv_from_locale (const char *@var{string})
 142 Converts a NUL terminated string from the locale encoding.
 143
 144 The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
 145
 146 Particular @code{errno} values: @code{ENOMEM}.
 147 @end deftypefun
 148
 149 @deftypefun {char *} u8_strconv_to_locale (const uint8_t *@var{string})
 150 @deftypefunx {char *} u16_strconv_to_locale (const uint16_t *@var{string})
 151 @deftypefunx {char *} u32_strconv_to_locale (const uint32_t *@var{string})
 152 Converts a NUL terminated string to the locale encoding.
 153
 154 The result is @code{malloc} allocated, or NULL (with @code{errno} set) in case of error.
 155
 156 Particular @code{errno} values: @code{ENOMEM}.
 157 @end deftypefun