doc/libunistring_5.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
   2 <html>
   3 <!-- Created on October, 16 2022 by texi2html 1.78a -->
   4 <!--
   5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
   6             Karl Berry  <karl@freefriends.org>
   7             Olaf Bachmann <obachman@mathematik.uni-kl.de>
   8             and many others.
   9 Maintained by: Many creative people.
  10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
  11
  12 -->
  13 <head>
  14 <title>GNU libunistring: 5. Conversions between Unicode and encodings &lt;uniconv.h&gt;</title>
  15
  16 <meta name="description" content="GNU libunistring: 5. Conversions between Unicode and encodings &lt;uniconv.h&gt;">
  17 <meta name="keywords" content="GNU libunistring: 5. Conversions between Unicode and encodings &lt;uniconv.h&gt;">
  18 <meta name="resource-type" content="document">
  19 <meta name="distribution" content="global">
  20 <meta name="Generator" content="texi2html 1.78a">
  21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22 <style type="text/css">
  23 <!--
  24 a.summary-letter {text-decoration: none}
  25 pre.display {font-family: serif}
  26 pre.format {font-family: serif}
  27 pre.menu-comment {font-family: serif}
  28 pre.menu-preformatted {font-family: serif}
  29 pre.smalldisplay {font-family: serif; font-size: smaller}
  30 pre.smallexample {font-size: smaller}
  31 pre.smallformat {font-family: serif; font-size: smaller}
  32 pre.smalllisp {font-size: smaller}
  33 span.roman {font-family:serif; font-weight:normal;}
  34 span.sansserif {font-family:sans-serif; font-weight:normal;}
  35 ul.toc {list-style: none}
  36 -->
  37 </style>
  38
  39
  40 </head>
  41
  42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  43
  44 <table cellpadding="1" cellspacing="1" border="0">
  45 <tr><td valign="middle" align="left">[<a href="libunistring_4.html#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  46 <td valign="middle" align="left">[<a href="libunistring_6.html#SEC31" title="Next chapter"> &gt;&gt; </a>]</td>
  47 <td valign="middle" align="left"> &nbsp; </td>
  48 <td valign="middle" align="left"> &nbsp; </td>
  49 <td valign="middle" align="left"> &nbsp; </td>
  50 <td valign="middle" align="left"> &nbsp; </td>
  51 <td valign="middle" align="left"> &nbsp; </td>
  52 <td valign="middle" align="left">[<a href="libunistring_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
  53 <td valign="middle" align="left">[<a href="libunistring_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  54 <td valign="middle" align="left">[<a href="libunistring_21.html#SEC92" title="Index">Index</a>]</td>
  55 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  56 </tr></table>
  57
  58 <hr size="2">
  59 <a name="uniconv_002eh"></a>
  60 <a name="SEC30"></a>
  61 <h1 class="chapter"> <a href="libunistring_toc.html#TOC30">5. Conversions between Unicode and encodings <code>&lt;uniconv.h&gt;</code></a> </h1>
  62
  63 <p>This include file declares functions for converting between Unicode strings
  64 and <code>char *</code> strings in locale encoding or in other specified encodings.
  65 </p>
  66 <a name="IDX145"></a>
  67 <p>The following function returns the locale encoding.
  68 </p>
  69 <dl>
  70 <dt><u>Function:</u> const char * <b>locale_charset</b><i> ()</i>
  71 <a name="IDX146"></a>
  72 </dt>
  73 <dd><p>Determines the current locale's character encoding, and canonicalizes it
  74 into one of the canonical names listed in &lsquo;<tt>localcharset.h</tt>&rsquo;.
  75 If the canonical name cannot be determined, the result is a non-canonical
  76 name.
  77 </p>
  78 <p>The result must not be freed; it is statically allocated.
  79 </p>
  80 <p>The result of this function can be used as an argument to the <code>iconv_open</code>
  81 function in GNU libc, in GNU libiconv, or in the gnulib provided wrapper
  82 around the native <code>iconv_open</code> function.  It may not work as an argument
  83 to the native <code>iconv_open</code> function directly.
  84 </p></dd></dl>
  85
  86 <p>The handling of unconvertible characters during the conversions can be
  87 parametrized through the following enumeration type:
  88 </p>
  89 <dl>
  90 <dt><u>Type:</u> <b>enum iconv_ilseq_handler</b>
  91 <a name="IDX147"></a>
  92 </dt>
  93 <dd><p>This type specifies how unconvertible characters in the input are handled.
  94 </p></dd></dl>
  95
  96 <dl>
  97 <dt><u>Constant:</u> enum iconv_ilseq_handler <b>iconveh_error</b>
  98 <a name="IDX148"></a>
  99 </dt>
 100 <dd><p>This handler causes the function to return with <code>errno</code> set to
 101 <code>EILSEQ</code>.
 102 </p></dd></dl>
 103
 104 <dl>
 105 <dt><u>Constant:</u> enum iconv_ilseq_handler <b>iconveh_question_mark</b>
 106 <a name="IDX149"></a>
 107 </dt>
 108 <dd><p>This handler produces one question mark &lsquo;<samp>?</samp>&rsquo; per unconvertible character.
 109 </p></dd></dl>
 110
 111 <dl>
 112 <dt><u>Constant:</u> enum iconv_ilseq_handler <b>iconveh_question_replacement_character</b>
 113 <a name="IDX150"></a>
 114 </dt>
 115 <dd><p>This handler produces one U+FFFD per unconvertible character if that
 116 fits in the target encoding, otherwise one question mark &lsquo;<samp>?</samp>&rsquo; per
 117 unconvertible character.
 118 </p></dd></dl>
 119
 120 <dl>
 121 <dt><u>Constant:</u> enum iconv_ilseq_handler <b>iconveh_escape_sequence</b>
 122 <a name="IDX151"></a>
 123 </dt>
 124 <dd><p>This handler produces an escape sequence <code>\u<var>xxxx</var></code> or
 125 <code>\U<var>xxxxxxxx</var></code> for each unconvertible character.
 126 </p></dd></dl>
 127
 128 <a name="IDX152"></a>
 129 <p>The following functions convert between strings in a specified encoding and
 130 Unicode strings.
 131 </p>
 132 <dl>
 133 <dt><u>Function:</u> uint8_t * <b>u8_conv_from_encoding</b><i> (const&nbsp;char&nbsp;*<var>fromcode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>, const&nbsp;char&nbsp;*<var>src</var>, size_t&nbsp;<var>srclen</var>, size_t&nbsp;*<var>offsets</var>, uint8_t&nbsp;*<var>resultbuf</var>, size_t&nbsp;*<var>lengthp</var>)</i>
 134 <a name="IDX153"></a>
 135 </dt>
 136 <dt><u>Function:</u> uint16_t * <b>u16_conv_from_encoding</b><i> (const&nbsp;char&nbsp;*<var>fromcode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>, const&nbsp;char&nbsp;*<var>src</var>, size_t&nbsp;<var>srclen</var>, size_t&nbsp;*<var>offsets</var>, uint16_t&nbsp;*<var>resultbuf</var>, size_t&nbsp;*<var>lengthp</var>)</i>
 137 <a name="IDX154"></a>
 138 </dt>
 139 <dt><u>Function:</u> uint32_t * <b>u32_conv_from_encoding</b><i> (const&nbsp;char&nbsp;*<var>fromcode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>, const&nbsp;char&nbsp;*<var>src</var>, size_t&nbsp;<var>srclen</var>, size_t&nbsp;*<var>offsets</var>, uint32_t&nbsp;*<var>resultbuf</var>, size_t&nbsp;*<var>lengthp</var>)</i>
 140 <a name="IDX155"></a>
 141 </dt>
 142 <dd><p>Converts an entire string, possibly including NUL bytes, from one encoding
 143 to UTF-8 encoding.
 144 </p>
 145 <p>Converts a memory region given in encoding <var>fromcode</var>.  <var>fromcode</var> is
 146 as for the <code>iconv_open</code> function.
 147 </p>
 148 <p>The input is in the memory region between <var>src</var> (inclusive) and
 149 <code><var>src</var> + <var>srclen</var></code> (exclusive).
 150 </p>
 151 <p>If <var>offsets</var> is not NULL, it should point to an array of <var>srclen</var>
 152 integers; this array is filled with offsets into the result, i.e. the
 153 character starting at <code><var>src</var>[i]</code> corresponds to the character starting
 154 at <code><var>result</var>[<var>offsets</var>[i]]</code>, and other offsets are set to
 155 <code>(size_t)(-1)</code>.
 156 </p>
 157 <p><code><var>resultbuf</var></code> and <code>*<var>lengthp</var></code> should be a scratch
 158 buffer and its size, or <code><var>resultbuf</var></code> can be NULL.
 159 </p>
 160 <p>May erase the contents of the memory at <code><var>resultbuf</var></code>.
 161 </p>
 162 <p>If successful: The resulting Unicode string (non-NULL) is returned and
 163 its length stored in <code>*<var>lengthp</var></code>.  The resulting string is
 164 <code><var>resultbuf</var></code> if no dynamic memory allocation was necessary,
 165 or a freshly allocated memory block otherwise.
 166 </p>
 167 <p>In case of error: NULL is returned and <code>errno</code> is set.
 168 Particular <code>errno</code> values: <code>EINVAL</code>, <code>EILSEQ</code>, <code>ENOMEM</code>.
 169 </p></dd></dl>
 170
 171 <dl>
 172 <dt><u>Function:</u> char * <b>u8_conv_to_encoding</b><i> (const&nbsp;char&nbsp;*<var>tocode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>, const&nbsp;uint8_t&nbsp;*<var>src</var>, size_t&nbsp;<var>srclen</var>, size_t&nbsp;*<var>offsets</var>, char&nbsp;*<var>resultbuf</var>, size_t&nbsp;*<var>lengthp</var>)</i>
 173 <a name="IDX156"></a>
 174 </dt>
 175 <dt><u>Function:</u> char * <b>u16_conv_to_encoding</b><i> (const&nbsp;char&nbsp;*<var>tocode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>, const&nbsp;uint16_t&nbsp;*<var>src</var>, size_t&nbsp;<var>srclen</var>, size_t&nbsp;*<var>offsets</var>, char&nbsp;*<var>resultbuf</var>, size_t&nbsp;*<var>lengthp</var>)</i>
 176 <a name="IDX157"></a>
 177 </dt>
 178 <dt><u>Function:</u> char * <b>u32_conv_to_encoding</b><i> (const&nbsp;char&nbsp;*<var>tocode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>, const&nbsp;uint32_t&nbsp;*<var>src</var>, size_t&nbsp;<var>srclen</var>, size_t&nbsp;*<var>offsets</var>, char&nbsp;*<var>resultbuf</var>, size_t&nbsp;*<var>lengthp</var>)</i>
 179 <a name="IDX158"></a>
 180 </dt>
 181 <dd><p>Converts an entire Unicode string, possibly including NUL units, from UTF-8
 182 encoding to a given encoding.
 183 </p>
 184 <p>Converts a memory region to encoding <var>tocode</var>.  <var>tocode</var> is as for
 185 the <code>iconv_open</code> function.
 186 </p>
 187 <p>The input is in the memory region between <var>src</var> (inclusive) and
 188 <code><var>src</var> + <var>srclen</var></code> (exclusive).
 189 </p>
 190 <p>If <var>offsets</var> is not NULL, it should point to an array of <var>srclen</var>
 191 integers; this array is filled with offsets into the result, i.e. the
 192 character starting at <code><var>src</var>[i]</code> corresponds to the character starting
 193 at <code><var>result</var>[<var>offsets</var>[i]]</code>, and other offsets are set to
 194 <code>(size_t)(-1)</code>.
 195 </p>
 196 <p><code><var>resultbuf</var></code> and <code>*<var>lengthp</var></code> should be a scratch
 197 buffer and its size, or <code><var>resultbuf</var></code> can be NULL.
 198 </p>
 199 <p>May erase the contents of the memory at <code><var>resultbuf</var></code>.
 200 </p>
 201 <p>If successful: The resulting Unicode string (non-NULL) is returned and
 202 its length stored in <code>*<var>lengthp</var></code>.  The resulting string is
 203 <code><var>resultbuf</var></code> if no dynamic memory allocation was necessary,
 204 or a freshly allocated memory block otherwise.
 205 </p>
 206 <p>In case of error: NULL is returned and <code>errno</code> is set.
 207 Particular <code>errno</code> values: <code>EINVAL</code>, <code>EILSEQ</code>, <code>ENOMEM</code>.
 208 </p></dd></dl>
 209
 210 <p>The following functions convert between NUL terminated strings in a specified
 211 encoding and NUL terminated Unicode strings.
 212 </p>
 213 <dl>
 214 <dt><u>Function:</u> uint8_t * <b>u8_strconv_from_encoding</b><i> (const&nbsp;char&nbsp;*<var>string</var>, const&nbsp;char&nbsp;*<var>fromcode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>)</i>
 215 <a name="IDX159"></a>
 216 </dt>
 217 <dt><u>Function:</u> uint16_t * <b>u16_strconv_from_encoding</b><i> (const&nbsp;char&nbsp;*<var>string</var>, const&nbsp;char&nbsp;*<var>fromcode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>)</i>
 218 <a name="IDX160"></a>
 219 </dt>
 220 <dt><u>Function:</u> uint32_t * <b>u32_strconv_from_encoding</b><i> (const&nbsp;char&nbsp;*<var>string</var>, const&nbsp;char&nbsp;*<var>fromcode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>)</i>
 221 <a name="IDX161"></a>
 222 </dt>
 223 <dd><p>Converts a NUL terminated string from a given encoding.
 224 </p>
 225 <p>The result is <code>malloc</code> allocated, or NULL (with <var>errno</var> set) in case of error.
 226 </p>
 227 <p>Particular <code>errno</code> values: <code>EILSEQ</code>, <code>ENOMEM</code>.
 228 </p></dd></dl>
 229
 230 <dl>
 231 <dt><u>Function:</u> char * <b>u8_strconv_to_encoding</b><i> (const&nbsp;uint8_t&nbsp;*<var>string</var>, const&nbsp;char&nbsp;*<var>tocode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>)</i>
 232 <a name="IDX162"></a>
 233 </dt>
 234 <dt><u>Function:</u> char * <b>u16_strconv_to_encoding</b><i> (const&nbsp;uint16_t&nbsp;*<var>string</var>, const&nbsp;char&nbsp;*<var>tocode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>)</i>
 235 <a name="IDX163"></a>
 236 </dt>
 237 <dt><u>Function:</u> char * <b>u32_strconv_to_encoding</b><i> (const&nbsp;uint32_t&nbsp;*<var>string</var>, const&nbsp;char&nbsp;*<var>tocode</var>, enum&nbsp;iconv_ilseq_handler&nbsp;<var>handler</var>)</i>
 238 <a name="IDX164"></a>
 239 </dt>
 240 <dd><p>Converts a NUL terminated string to a given encoding.
 241 </p>
 242 <p>The result is <code>malloc</code> allocated, or NULL (with <code>errno</code> set) in case of error.
 243 </p>
 244 <p>Particular <code>errno</code> values: <code>EILSEQ</code>, <code>ENOMEM</code>.
 245 </p></dd></dl>
 246
 247 <p>The following functions are shorthands that convert between NUL terminated
 248 strings in locale encoding and NUL terminated Unicode strings.
 249 </p>
 250 <dl>
 251 <dt><u>Function:</u> uint8_t * <b>u8_strconv_from_locale</b><i> (const&nbsp;char&nbsp;*<var>string</var>)</i>
 252 <a name="IDX165"></a>
 253 </dt>
 254 <dt><u>Function:</u> uint16_t * <b>u16_strconv_from_locale</b><i> (const&nbsp;char&nbsp;*<var>string</var>)</i>
 255 <a name="IDX166"></a>
 256 </dt>
 257 <dt><u>Function:</u> uint32_t * <b>u32_strconv_from_locale</b><i> (const&nbsp;char&nbsp;*<var>string</var>)</i>
 258 <a name="IDX167"></a>
 259 </dt>
 260 <dd><p>Converts a NUL terminated string from the locale encoding.
 261 </p>
 262 <p>The result is <code>malloc</code> allocated, or NULL (with <code>errno</code> set) in case of error.
 263 </p>
 264 <p>Particular <code>errno</code> values: <code>ENOMEM</code>.
 265 </p></dd></dl>
 266
 267 <dl>
 268 <dt><u>Function:</u> char * <b>u8_strconv_to_locale</b><i> (const&nbsp;uint8_t&nbsp;*<var>string</var>)</i>
 269 <a name="IDX168"></a>
 270 </dt>
 271 <dt><u>Function:</u> char * <b>u16_strconv_to_locale</b><i> (const&nbsp;uint16_t&nbsp;*<var>string</var>)</i>
 272 <a name="IDX169"></a>
 273 </dt>
 274 <dt><u>Function:</u> char * <b>u32_strconv_to_locale</b><i> (const&nbsp;uint32_t&nbsp;*<var>string</var>)</i>
 275 <a name="IDX170"></a>
 276 </dt>
 277 <dd><p>Converts a NUL terminated string to the locale encoding.
 278 </p>
 279 <p>The result is <code>malloc</code> allocated, or NULL (with <code>errno</code> set) in case of error.
 280 </p>
 281 <p>Particular <code>errno</code> values: <code>ENOMEM</code>.
 282 </p></dd></dl>
 283 <hr size="6">
 284 <table cellpadding="1" cellspacing="1" border="0">
 285 <tr><td valign="middle" align="left">[<a href="libunistring_4.html#SEC10" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
 286 <td valign="middle" align="left">[<a href="libunistring_6.html#SEC31" title="Next chapter"> &gt;&gt; </a>]</td>
 287 <td valign="middle" align="left"> &nbsp; </td>
 288 <td valign="middle" align="left"> &nbsp; </td>
 289 <td valign="middle" align="left"> &nbsp; </td>
 290 <td valign="middle" align="left"> &nbsp; </td>
 291 <td valign="middle" align="left"> &nbsp; </td>
 292 <td valign="middle" align="left">[<a href="libunistring_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
 293 <td valign="middle" align="left">[<a href="libunistring_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
 294 <td valign="middle" align="left">[<a href="libunistring_21.html#SEC92" title="Index">Index</a>]</td>
 295 <td valign="middle" align="left">[<a href="libunistring_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
 296 </tr></table>
 297 <p>
 298  <font size="-1">
 299   This document was generated by <em>Bruno Haible</em> on <em>October, 16 2022</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
 300  </font>
 301  <br>
 302
 303 </p>
 304 </body>
 305 </html>