docs/reference/glib/html/glib-Character-Set-Conversion.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Character Set Conversion</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-utilities.html" title="GLib Utilities">
   9 <link rel="prev" href="glib-String-Utility-Functions.html" title="String Utility Functions">
  10 <link rel="next" href="glib-Unicode-Manipulation.html" title="Unicode Manipulation">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-String-Utility-Functions.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Unicode-Manipulation.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Character-Set-Conversion.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Character-Set-Conversion.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Character-Set-Conversion"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Character-Set-Conversion.top_of_page"></a>Character Set Conversion</span></h2>
  34 <p>Character Set Conversion — convert strings between different character sets</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Character-Set-Conversion.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()">g_convert</a>                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
  44                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  45                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *to_codeset</code></em>,
  46                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *from_codeset</code></em>,
  47                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  48                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  49                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  50 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-convert-with-fallback" title="g_convert_with_fallback ()">g_convert_with_fallback</a>             (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  52                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *to_codeset</code></em>,
  53                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *from_codeset</code></em>,
  54                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *fallback</code></em>,
  55                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  56                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  57                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  58                     <a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv">GIConv</a>;
  59 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-convert-with-iconv" title="g_convert_with_iconv ()">g_convert_with_iconv</a>                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
  60                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  61                                                          <em class="parameter"><code><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="type">GIConv</span></a> converter</code></em>,
  62                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  63                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  64                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  65 #define             <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR:CAPS" title="G_CONVERT_ERROR">G_CONVERT_ERROR</a>
  66 <a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="returnvalue">GIConv</span></a>              <a class="link" href="glib-Character-Set-Conversion.html#g-iconv-open" title="g_iconv_open ()">g_iconv_open</a>                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *to_codeset</code></em>,
  67                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *from_codeset</code></em>);
  68 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               <a class="link" href="glib-Character-Set-Conversion.html#g-iconv" title="g_iconv ()">g_iconv</a>                             (<em class="parameter"><code><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="type">GIConv</span></a> converter</code></em>,
  69                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **inbuf</code></em>,
  70                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *inbytes_left</code></em>,
  71                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **outbuf</code></em>,
  72                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *outbytes_left</code></em>);
  73 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Character-Set-Conversion.html#g-iconv-close" title="g_iconv_close ()">g_iconv_close</a>                       (<em class="parameter"><code><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="type">GIConv</span></a> converter</code></em>);
  74 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-locale-to-utf8" title="g_locale_to_utf8 ()">g_locale_to_utf8</a>                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *opsysstring</code></em>,
  75                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  76                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  77                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  78                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  79 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-filename-to-utf8" title="g_filename_to_utf8 ()">g_filename_to_utf8</a>                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *opsysstring</code></em>,
  80                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  81                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  82                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  83                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  84 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-filename-from-utf8" title="g_filename_from_utf8 ()">g_filename_from_utf8</a>                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *utf8string</code></em>,
  85                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  86                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  87                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  88                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  89 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Character-Set-Conversion.html#g-get-filename-charsets" title="g_get_filename_charsets ()">g_get_filename_charsets</a>             (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> ***charsets</code></em>);
  90 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-filename-display-name" title="g_filename_display_name ()">g_filename_display_name</a>             (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *filename</code></em>);
  91 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-filename-display-basename" title="g_filename_display_basename ()">g_filename_display_basename</a>         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *filename</code></em>);
  92 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-locale-from-utf8" title="g_locale_from_utf8 ()">g_locale_from_utf8</a>                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *utf8string</code></em>,
  93                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
  94                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
  95                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
  96                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);
  97 enum                <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError">GConvertError</a>;
  98
  99 <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            <a class="link" href="glib-Character-Set-Conversion.html#g-get-charset" title="g_get_charset ()">g_get_charset</a>                       (<em class="parameter"><code>const <span class="type">char</span> **charset</code></em>);
 100 <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             <a class="link" href="glib-Character-Set-Conversion.html#g-get-codeset" title="g_get_codeset ()">g_get_codeset</a>                       (<em class="parameter"><code><span class="type">void</span></code></em>);
 101 </pre>
 102 </div>
 103 <div class="refsect1">
 104 <a name="glib-Character-Set-Conversion.description"></a><h2>Description</h2>
 105 <p>
 106 The <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a> family of function wraps the functionality of <code class="function">iconv()</code>. In
 107 addition to pure character set conversions, GLib has functions to deal
 108 with the extra complications of encodings for file names.
 109 </p>
 110 <p>
 111 </p>
 112 <div class="refsect2">
 113 <a name="file-name-encodings"></a><h3>File Name Encodings</h3>
 114 <p>
 115 Historically, Unix has not had a defined encoding for file
 116 names:  a file name is valid as long as it does not have path
 117 separators in it ("/").  However, displaying file names may
 118 require conversion:  from the character set in which they were
 119 created, to the character set in which the application
 120 operates.  Consider the Spanish file name
 121 "<code class="filename">Presentación.sxi</code>".  If the
 122 application which created it uses ISO-8859-1 for its encoding,
 123 </p>
 124 <a name="filename-iso8859-1"></a><pre class="programlisting">
 125 Character:  P  r  e  s  e  n  t  a  c  i  ó  n  .  s  x  i
 126 Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
 127 </pre>
 128 <p>
 129 However, if the application use UTF-8, the actual file name on
 130 disk would look like this:
 131 </p>
 132 <a name="filename-utf-8"></a><pre class="programlisting">
 133 Character:  P  r  e  s  e  n  t  a  c  i  ó     n  .  s  x  i
 134 Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
 135 </pre>
 136 <p>
 137 Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
 138 that use Glib do the same thing.  If you get a file name from
 139 the file system, for example, from readdir(3) or from <a class="link" href="glib-File-Utilities.html#g-dir-read-name" title="g_dir_read_name ()"><code class="function">g_dir_read_name()</code></a>,
 140 and you wish to display the file name to the user, you
 141 <span class="emphasis"><em>will</em></span> need to convert it into UTF-8.  The
 142 opposite case is when the user types the name of a file he
 143 wishes to save:  the toolkit will give you that string in
 144 UTF-8 encoding, and you will need to convert it to the
 145 character set used for file names before you can create the
 146 file with open(2) or fopen(3).
 147 </p>
 148 <p>
 149 By default, Glib assumes that file names on disk are in UTF-8
 150 encoding.  This is a valid assumption for file systems which
 151 were created relatively recently:  most applications use UTF-8
 152 encoding for their strings, and that is also what they use for
 153 the file names they create.  However, older file systems may
 154 still contain file names created in "older" encodings, such as
 155 ISO-8859-1. In this case, for compatibility reasons, you may
 156 want to instruct Glib to use that particular encoding for file
 157 names rather than UTF-8.  You can do this by specifying the
 158 encoding for file names in the <a class="link" href="glib-running.html#G_FILENAME_ENCODING" title="G_FILENAME_ENCODING"><code class="envar">G_FILENAME_ENCODING</code></a>
 159 environment variable.  For example, if your installation uses
 160 ISO-8859-1 for file names, you can put this in your
 161 <code class="filename">~/.profile</code>:
 162 </p>
 163 <pre class="programlisting">
 164 export G_FILENAME_ENCODING=ISO-8859-1
 165 </pre>
 166 <p>
 167 Glib provides the functions <a class="link" href="glib-Character-Set-Conversion.html#g-filename-to-utf8" title="g_filename_to_utf8 ()"><code class="function">g_filename_to_utf8()</code></a> and
 168 <a class="link" href="glib-Character-Set-Conversion.html#g-filename-from-utf8" title="g_filename_from_utf8 ()"><code class="function">g_filename_from_utf8()</code></a> to perform the necessary conversions. These
 169 functions convert file names from the encoding specified in
 170 <code class="envar">G_FILENAME_ENCODING</code> to UTF-8 and vice-versa.
 171 <a class="xref" href="glib-Character-Set-Conversion.html#file-name-encodings-diagram" title="Figure 2. Conversion between File Name Encodings">Figure 2, “Conversion between File Name Encodings”</a> illustrates how
 172 these functions are used to convert between UTF-8 and the
 173 encoding for file names in the file system.
 174 </p>
 175 <div class="figure">
 176 <a name="file-name-encodings-diagram"></a><p class="title"><b>Figure 2. Conversion between File Name Encodings</b></p>
 177 <div class="figure-contents"><div><img src="file-name-encodings.png" alt="Conversion between File Name Encodings"></div></div>
 178 </div>
 179 <br class="figure-break"><div class="refsect3">
 180 <a name="file-name-encodings-checklist"></a><h4>Checklist for Application Writers</h4>
 181 <p>
 182 This section is a practical summary of the detailed
 183 description above.  You can use this as a checklist of
 184 things to do to make sure your applications process file
 185 name encodings correctly.
 186 </p>
 187 <div class="orderedlist"><ol class="orderedlist" type="1">
 188 <li class="listitem"><p>
 189 If you get a file name from the file system from a function
 190 such as readdir(3) or <a href="http://library.gnome.org/devel/gtk/GtkFileChooser.html#gtk-file-chooser-get-filename"><code class="function">gtk_file_chooser_get_filename()</code></a>,
 191 you do not need to do any conversion to pass that
 192 file name to functions like open(2), rename(2), or
 193 fopen(3) — those are "raw" file names which the file
 194 system understands.
 195 </p></li>
 196 <li class="listitem"><p>
 197 If you need to display a file name, convert it to UTF-8 first by
 198 using <a class="link" href="glib-Character-Set-Conversion.html#g-filename-to-utf8" title="g_filename_to_utf8 ()"><code class="function">g_filename_to_utf8()</code></a>. If conversion fails, display a string like
 199 "<code class="literal">Unknown file name</code>". <span class="emphasis"><em>Do not</em></span>
 200 convert this string back into the encoding used for file names if you
 201 wish to pass it to the file system; use the original file name instead.
 202 For example, the document window of a word processor could display
 203 "Unknown file name" in its title bar but still let the user save the
 204 file, as it would keep the raw file name internally. This can happen
 205 if the user has not set the <code class="envar">G_FILENAME_ENCODING</code>
 206 environment variable even though he has files whose names are not
 207 encoded in UTF-8.
 208 </p></li>
 209 <li class="listitem"><p>
 210 If your user interface lets the user type a file name for saving or
 211 renaming, convert it to the encoding used for file names in the file
 212 system by using <a class="link" href="glib-Character-Set-Conversion.html#g-filename-from-utf8" title="g_filename_from_utf8 ()"><code class="function">g_filename_from_utf8()</code></a>. Pass the converted file name
 213 to functions like fopen(3). If conversion fails, ask the user to enter
 214 a different file name. This can happen if the user types Japanese
 215 characters when <code class="envar">G_FILENAME_ENCODING</code> is set to
 216 <code class="literal">ISO-8859-1</code>, for example.
 217 </p></li>
 218 </ol></div>
 219 </div>
 220 </div>
 221 <p>
 222 </p>
 223 </div>
 224 <div class="refsect1">
 225 <a name="glib-Character-Set-Conversion.details"></a><h2>Details</h2>
 226 <div class="refsect2">
 227 <a name="g-convert"></a><h3>g_convert ()</h3>
 228 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_convert                           (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 229                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 230                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *to_codeset</code></em>,
 231                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *from_codeset</code></em>,
 232                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 233                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 234                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 235 <p>
 236 Converts a string from one character set to another.
 237 </p>
 238 <p>
 239 Note that you should use <a class="link" href="glib-Character-Set-Conversion.html#g-iconv" title="g_iconv ()"><code class="function">g_iconv()</code></a> for streaming
 240 conversions<sup>[<a href="glib-Character-Set-Conversion.html#ftn.streaming-state" class="footnoteref">3</a>]</sup>.
 241 </p>
 242 <div class="variablelist"><table border="0">
 243 <col align="left" valign="top">
 244 <tbody>
 245 <tr>
 246 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 247 <td>the string to convert</td>
 248 </tr>
 249 <tr>
 250 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 251 <td>the length of the string, or -1 if the string is
 252 nul-terminated<sup>[<a name="nul-unsafe" href="#ftn.nul-unsafe" class="footnote">2</a>]</sup>.</td>
 253 </tr>
 254 <tr>
 255 <td><p><span class="term"><em class="parameter"><code>to_codeset</code></em> :</span></p></td>
 256 <td>name of character set into which to convert <em class="parameter"><code>str</code></em>
 257 </td>
 258 </tr>
 259 <tr>
 260 <td><p><span class="term"><em class="parameter"><code>from_codeset</code></em> :</span></p></td>
 261 <td>character set of <em class="parameter"><code>str</code></em>.</td>
 262 </tr>
 263 <tr>
 264 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 265 <td>location to store the number of bytes in the
 266 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 267 Even if the conversion was successful, this may be
 268 less than <em class="parameter"><code>len</code></em> if there were partial characters
 269 at the end of the input. If the error
 270 <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
 271 stored will the byte offset after the last valid
 272 input sequence. <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span>
 273 </td>
 274 </tr>
 275 <tr>
 276 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 277 <td>the number of bytes stored in the output buffer (not
 278 including the terminating nul). <span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span>
 279 </td>
 280 </tr>
 281 <tr>
 282 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 283 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 284 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 285 </tr>
 286 <tr>
 287 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 288 <td>If the conversion was successful, a newly allocated
 289 nul-terminated string, which must be freed with
 290 <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>. Otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> and <em class="parameter"><code>error</code></em> will be set.</td>
 291 </tr>
 292 </tbody>
 293 </table></div>
 294 </div>
 295 <hr>
 296 <div class="refsect2">
 297 <a name="g-convert-with-fallback"></a><h3>g_convert_with_fallback ()</h3>
 298 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_convert_with_fallback             (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 299                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 300                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *to_codeset</code></em>,
 301                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *from_codeset</code></em>,
 302                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *fallback</code></em>,
 303                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 304                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 305                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 306 <p>
 307 Converts a string from one character set to another, possibly
 308 including fallback sequences for characters not representable
 309 in the output. Note that it is not guaranteed that the specification
 310 for the fallback sequences in <em class="parameter"><code>fallback</code></em> will be honored. Some
 311 systems may do an approximate conversion from <em class="parameter"><code>from_codeset</code></em>
 312 to <em class="parameter"><code>to_codeset</code></em> in their <code class="function">iconv()</code> functions,
 313 in which case GLib will simply return that approximate conversion.
 314 </p>
 315 <p>
 316 Note that you should use <a class="link" href="glib-Character-Set-Conversion.html#g-iconv" title="g_iconv ()"><code class="function">g_iconv()</code></a> for streaming
 317 conversions<sup>[<a href="glib-Character-Set-Conversion.html#ftn.streaming-state" class="footnoteref">3</a>]</sup>.
 318 </p>
 319 <div class="variablelist"><table border="0">
 320 <col align="left" valign="top">
 321 <tbody>
 322 <tr>
 323 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 324 <td>the string to convert</td>
 325 </tr>
 326 <tr>
 327 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 328 <td>the length of the string, or -1 if the string is
 329 nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">2</a>]</sup>.</td>
 330 </tr>
 331 <tr>
 332 <td><p><span class="term"><em class="parameter"><code>to_codeset</code></em> :</span></p></td>
 333 <td>name of character set into which to convert <em class="parameter"><code>str</code></em>
 334 </td>
 335 </tr>
 336 <tr>
 337 <td><p><span class="term"><em class="parameter"><code>from_codeset</code></em> :</span></p></td>
 338 <td>character set of <em class="parameter"><code>str</code></em>.</td>
 339 </tr>
 340 <tr>
 341 <td><p><span class="term"><em class="parameter"><code>fallback</code></em> :</span></p></td>
 342 <td>UTF-8 string to use in place of character not
 343 present in the target encoding. (The string must be
 344 representable in the target encoding).
 345 If <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, characters not in the target encoding will
 346 be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.</td>
 347 </tr>
 348 <tr>
 349 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 350 <td>location to store the number of bytes in the
 351 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 352 Even if the conversion was successful, this may be
 353 less than <em class="parameter"><code>len</code></em> if there were partial characters
 354 at the end of the input.</td>
 355 </tr>
 356 <tr>
 357 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 358 <td>the number of bytes stored in the output buffer (not
 359 including the terminating nul).</td>
 360 </tr>
 361 <tr>
 362 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 363 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 364 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 365 </tr>
 366 <tr>
 367 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 368 <td>If the conversion was successful, a newly allocated
 369 nul-terminated string, which must be freed with
 370 <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>. Otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> and <em class="parameter"><code>error</code></em> will be set.</td>
 371 </tr>
 372 </tbody>
 373 </table></div>
 374 </div>
 375 <hr>
 376 <div class="refsect2">
 377 <a name="GIConv"></a><h3>GIConv</h3>
 378 <pre class="programlisting">typedef struct _GIConv GIConv;</pre>
 379 </div>
 380 <hr>
 381 <div class="refsect2">
 382 <a name="g-convert-with-iconv"></a><h3>g_convert_with_iconv ()</h3>
 383 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_convert_with_iconv                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *str</code></em>,
 384                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 385                                                          <em class="parameter"><code><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="type">GIConv</span></a> converter</code></em>,
 386                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 387                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 388                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 389 <p>
 390 Converts a string from one character set to another.
 391 </p>
 392 <p>
 393 Note that you should use <a class="link" href="glib-Character-Set-Conversion.html#g-iconv" title="g_iconv ()"><code class="function">g_iconv()</code></a> for streaming
 394 conversions<sup>[<a name="streaming-state" href="#ftn.streaming-state" class="footnote">3</a>]</sup>.
 395 </p>
 396 <div class="variablelist"><table border="0">
 397 <col align="left" valign="top">
 398 <tbody>
 399 <tr>
 400 <td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
 401 <td>the string to convert</td>
 402 </tr>
 403 <tr>
 404 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 405 <td>the length of the string, or -1 if the string is
 406 nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">2</a>]</sup>.</td>
 407 </tr>
 408 <tr>
 409 <td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td>
 410 <td>conversion descriptor from <a class="link" href="glib-Character-Set-Conversion.html#g-iconv-open" title="g_iconv_open ()"><code class="function">g_iconv_open()</code></a>
 411 </td>
 412 </tr>
 413 <tr>
 414 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 415 <td>location to store the number of bytes in the
 416 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 417 Even if the conversion was successful, this may be
 418 less than <em class="parameter"><code>len</code></em> if there were partial characters
 419 at the end of the input. If the error
 420 <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
 421 stored will the byte offset after the last valid
 422 input sequence.</td>
 423 </tr>
 424 <tr>
 425 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 426 <td>the number of bytes stored in the output buffer (not
 427 including the terminating nul).</td>
 428 </tr>
 429 <tr>
 430 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 431 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 432 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 433 </tr>
 434 <tr>
 435 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 436 <td>If the conversion was successful, a newly allocated
 437 nul-terminated string, which must be freed with
 438 <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>. Otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> and <em class="parameter"><code>error</code></em> will be set.</td>
 439 </tr>
 440 </tbody>
 441 </table></div>
 442 </div>
 443 <hr>
 444 <div class="refsect2">
 445 <a name="G-CONVERT-ERROR:CAPS"></a><h3>G_CONVERT_ERROR</h3>
 446 <pre class="programlisting">#define G_CONVERT_ERROR g_convert_error_quark()
 447 </pre>
 448 <p>
 449 Error domain for character set conversions. Errors in this domain will
 450 be from the <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> enumeration. See <a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> for information on
 451 error domains.
 452 </p>
 453 </div>
 454 <hr>
 455 <div class="refsect2">
 456 <a name="g-iconv-open"></a><h3>g_iconv_open ()</h3>
 457 <pre class="programlisting"><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="returnvalue">GIConv</span></a>              g_iconv_open                        (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *to_codeset</code></em>,
 458                                                          <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *from_codeset</code></em>);</pre>
 459 <p>
 460 Same as the standard UNIX routine <code class="function">iconv_open()</code>, but
 461 may be implemented via libiconv on UNIX flavors that lack
 462 a native implementation.
 463 </p>
 464 <p>
 465 GLib provides <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a> and <a class="link" href="glib-Character-Set-Conversion.html#g-locale-to-utf8" title="g_locale_to_utf8 ()"><code class="function">g_locale_to_utf8()</code></a> which are likely
 466 more convenient than the raw iconv wrappers.
 467 </p>
 468 <div class="variablelist"><table border="0">
 469 <col align="left" valign="top">
 470 <tbody>
 471 <tr>
 472 <td><p><span class="term"><em class="parameter"><code>to_codeset</code></em> :</span></p></td>
 473 <td>destination codeset</td>
 474 </tr>
 475 <tr>
 476 <td><p><span class="term"><em class="parameter"><code>from_codeset</code></em> :</span></p></td>
 477 <td>source codeset</td>
 478 </tr>
 479 <tr>
 480 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 481 <td>a "conversion descriptor", or (GIConv)-1 if
 482 opening the converter failed.</td>
 483 </tr>
 484 </tbody>
 485 </table></div>
 486 </div>
 487 <hr>
 488 <div class="refsect2">
 489 <a name="g-iconv"></a><h3>g_iconv ()</h3>
 490 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="returnvalue">gsize</span></a>               g_iconv                             (<em class="parameter"><code><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="type">GIConv</span></a> converter</code></em>,
 491                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **inbuf</code></em>,
 492                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *inbytes_left</code></em>,
 493                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **outbuf</code></em>,
 494                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *outbytes_left</code></em>);</pre>
 495 <p>
 496 Same as the standard UNIX routine <code class="function">iconv()</code>, but
 497 may be implemented via libiconv on UNIX flavors that lack
 498 a native implementation.
 499 </p>
 500 <p>
 501 GLib provides <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a> and <a class="link" href="glib-Character-Set-Conversion.html#g-locale-to-utf8" title="g_locale_to_utf8 ()"><code class="function">g_locale_to_utf8()</code></a> which are likely
 502 more convenient than the raw iconv wrappers.
 503 </p>
 504 <div class="variablelist"><table border="0">
 505 <col align="left" valign="top">
 506 <tbody>
 507 <tr>
 508 <td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td>
 509 <td>conversion descriptor from <a class="link" href="glib-Character-Set-Conversion.html#g-iconv-open" title="g_iconv_open ()"><code class="function">g_iconv_open()</code></a>
 510 </td>
 511 </tr>
 512 <tr>
 513 <td><p><span class="term"><em class="parameter"><code>inbuf</code></em> :</span></p></td>
 514 <td>bytes to convert</td>
 515 </tr>
 516 <tr>
 517 <td><p><span class="term"><em class="parameter"><code>inbytes_left</code></em> :</span></p></td>
 518 <td>inout parameter, bytes remaining to convert in <em class="parameter"><code>inbuf</code></em>
 519 </td>
 520 </tr>
 521 <tr>
 522 <td><p><span class="term"><em class="parameter"><code>outbuf</code></em> :</span></p></td>
 523 <td>converted output bytes</td>
 524 </tr>
 525 <tr>
 526 <td><p><span class="term"><em class="parameter"><code>outbytes_left</code></em> :</span></p></td>
 527 <td>inout parameter, bytes available to fill in <em class="parameter"><code>outbuf</code></em>
 528 </td>
 529 </tr>
 530 <tr>
 531 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 532 <td>count of non-reversible conversions, or -1 on error</td>
 533 </tr>
 534 </tbody>
 535 </table></div>
 536 </div>
 537 <hr>
 538 <div class="refsect2">
 539 <a name="g-iconv-close"></a><h3>g_iconv_close ()</h3>
 540 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_iconv_close                       (<em class="parameter"><code><a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv"><span class="type">GIConv</span></a> converter</code></em>);</pre>
 541 <p>
 542 Same as the standard UNIX routine <code class="function">iconv_close()</code>, but
 543 may be implemented via libiconv on UNIX flavors that lack
 544 a native implementation. Should be called to clean up
 545 the conversion descriptor from <a class="link" href="glib-Character-Set-Conversion.html#g-iconv-open" title="g_iconv_open ()"><code class="function">g_iconv_open()</code></a> when
 546 you are done converting things.
 547 </p>
 548 <p>
 549 GLib provides <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a> and <a class="link" href="glib-Character-Set-Conversion.html#g-locale-to-utf8" title="g_locale_to_utf8 ()"><code class="function">g_locale_to_utf8()</code></a> which are likely
 550 more convenient than the raw iconv wrappers.
 551 </p>
 552 <div class="variablelist"><table border="0">
 553 <col align="left" valign="top">
 554 <tbody>
 555 <tr>
 556 <td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td>
 557 <td>a conversion descriptor from <a class="link" href="glib-Character-Set-Conversion.html#g-iconv-open" title="g_iconv_open ()"><code class="function">g_iconv_open()</code></a>
 558 </td>
 559 </tr>
 560 <tr>
 561 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 562 <td>-1 on error, 0 on success</td>
 563 </tr>
 564 </tbody>
 565 </table></div>
 566 </div>
 567 <hr>
 568 <div class="refsect2">
 569 <a name="g-locale-to-utf8"></a><h3>g_locale_to_utf8 ()</h3>
 570 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_locale_to_utf8                    (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *opsysstring</code></em>,
 571                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 572                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 573                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 574                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 575 <p>
 576 Converts a string which is in the encoding used for strings by
 577 the C runtime (usually the same as that used by the operating
 578 system) in the <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a> into a
 579 UTF-8 string.
 580 </p>
 581 <div class="variablelist"><table border="0">
 582 <col align="left" valign="top">
 583 <tbody>
 584 <tr>
 585 <td><p><span class="term"><em class="parameter"><code>opsysstring</code></em> :</span></p></td>
 586 <td>a string in the encoding of the current locale. On Windows
 587 this means the system codepage.</td>
 588 </tr>
 589 <tr>
 590 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 591 <td>the length of the string, or -1 if the string is
 592 nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">2</a>]</sup>.</td>
 593 </tr>
 594 <tr>
 595 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 596 <td>location to store the number of bytes in the
 597 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 598 Even if the conversion was successful, this may be
 599 less than <em class="parameter"><code>len</code></em> if there were partial characters
 600 at the end of the input. If the error
 601 <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
 602 stored will the byte offset after the last valid
 603 input sequence.</td>
 604 </tr>
 605 <tr>
 606 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 607 <td>the number of bytes stored in the output buffer (not
 608 including the terminating nul).</td>
 609 </tr>
 610 <tr>
 611 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 612 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 613 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 614 </tr>
 615 <tr>
 616 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 617 <td>The converted string, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on an error.</td>
 618 </tr>
 619 </tbody>
 620 </table></div>
 621 </div>
 622 <hr>
 623 <div class="refsect2">
 624 <a name="g-filename-to-utf8"></a><h3>g_filename_to_utf8 ()</h3>
 625 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_filename_to_utf8                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *opsysstring</code></em>,
 626                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 627                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 628                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 629                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 630 <p>
 631 Converts a string which is in the encoding used by GLib for
 632 filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
 633 for filenames; on other platforms, this function indirectly depends on
 634 the <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a>.
 635 </p>
 636 <div class="variablelist"><table border="0">
 637 <col align="left" valign="top">
 638 <tbody>
 639 <tr>
 640 <td><p><span class="term"><em class="parameter"><code>opsysstring</code></em> :</span></p></td>
 641 <td>a string in the encoding for filenames</td>
 642 </tr>
 643 <tr>
 644 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 645 <td>the length of the string, or -1 if the string is
 646 nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">2</a>]</sup>.</td>
 647 </tr>
 648 <tr>
 649 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 650 <td>location to store the number of bytes in the
 651 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 652 Even if the conversion was successful, this may be
 653 less than <em class="parameter"><code>len</code></em> if there were partial characters
 654 at the end of the input. If the error
 655 <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
 656 stored will the byte offset after the last valid
 657 input sequence.</td>
 658 </tr>
 659 <tr>
 660 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 661 <td>the number of bytes stored in the output buffer (not
 662 including the terminating nul).</td>
 663 </tr>
 664 <tr>
 665 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 666 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 667 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 668 </tr>
 669 <tr>
 670 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 671 <td>The converted string, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on an error.</td>
 672 </tr>
 673 </tbody>
 674 </table></div>
 675 </div>
 676 <hr>
 677 <div class="refsect2">
 678 <a name="g-filename-from-utf8"></a><h3>g_filename_from_utf8 ()</h3>
 679 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_filename_from_utf8                (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *utf8string</code></em>,
 680                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 681                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 682                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 683                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 684 <p>
 685 Converts a string from UTF-8 to the encoding GLib uses for
 686 filenames. Note that on Windows GLib uses UTF-8 for filenames;
 687 on other platforms, this function indirectly depends on the
 688 <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a>.
 689 </p>
 690 <div class="variablelist"><table border="0">
 691 <col align="left" valign="top">
 692 <tbody>
 693 <tr>
 694 <td><p><span class="term"><em class="parameter"><code>utf8string</code></em> :</span></p></td>
 695 <td>a UTF-8 encoded string.</td>
 696 </tr>
 697 <tr>
 698 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 699 <td>the length of the string, or -1 if the string is
 700 nul-terminated.</td>
 701 </tr>
 702 <tr>
 703 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 704 <td>location to store the number of bytes in the
 705 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 706 Even if the conversion was successful, this may be
 707 less than <em class="parameter"><code>len</code></em> if there were partial characters
 708 at the end of the input. If the error
 709 <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
 710 stored will the byte offset after the last valid
 711 input sequence.</td>
 712 </tr>
 713 <tr>
 714 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 715 <td>the number of bytes stored in the output buffer (not
 716 including the terminating nul).</td>
 717 </tr>
 718 <tr>
 719 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 720 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 721 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 722 </tr>
 723 <tr>
 724 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 725 <td>The converted string, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on an error.</td>
 726 </tr>
 727 </tbody>
 728 </table></div>
 729 </div>
 730 <hr>
 731 <div class="refsect2">
 732 <a name="g-get-filename-charsets"></a><h3>g_get_filename_charsets ()</h3>
 733 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_get_filename_charsets             (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> ***charsets</code></em>);</pre>
 734 <p>
 735 Determines the preferred character sets used for filenames.
 736 The first character set from the <em class="parameter"><code>charsets</code></em> is the filename encoding, the
 737 subsequent character sets are used when trying to generate a displayable
 738 representation of a filename, see <a class="link" href="glib-Character-Set-Conversion.html#g-filename-display-name" title="g_filename_display_name ()"><code class="function">g_filename_display_name()</code></a>.
 739 </p>
 740 <p>
 741 On Unix, the character sets are determined by consulting the
 742 environment variables <code class="envar">G_FILENAME_ENCODING</code> and
 743 <code class="envar">G_BROKEN_FILENAMES</code>. On Windows, the character set
 744 used in the GLib API is always UTF-8 and said environment variables
 745 have no effect.
 746 </p>
 747 <p>
 748 <code class="envar">G_FILENAME_ENCODING</code> may be set to a comma-separated list
 749 of character set names. The special token "@locale" is taken to
 750 mean the character set for the <a class="link" href="glib-running.html#setlocale" title="Locale">current
 751 locale</a>. If <code class="envar">G_FILENAME_ENCODING</code> is not set, but
 752 <code class="envar">G_BROKEN_FILENAMES</code> is, the character set of the current
 753 locale is taken as the filename encoding. If neither environment variable
 754 is set, UTF-8 is taken as the filename encoding, but the character
 755 set of the current locale is also put in the list of encodings.
 756 </p>
 757 <p>
 758 The returned <em class="parameter"><code>charsets</code></em> belong to GLib and must not be freed.
 759 </p>
 760 <p>
 761 Note that on Unix, regardless of the locale character set or
 762 <code class="envar">G_FILENAME_ENCODING</code> value, the actual file names present
 763 on a system might be in any random encoding or just gibberish.
 764 </p>
 765 <div class="variablelist"><table border="0">
 766 <col align="left" valign="top">
 767 <tbody>
 768 <tr>
 769 <td><p><span class="term"><em class="parameter"><code>charsets</code></em> :</span></p></td>
 770 <td>return location for the <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>-terminated list of encoding names</td>
 771 </tr>
 772 <tr>
 773 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 774 <td>
 775 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the filename encoding is UTF-8.</td>
 776 </tr>
 777 </tbody>
 778 </table></div>
 779 <p class="since">Since 2.6</p>
 780 </div>
 781 <hr>
 782 <div class="refsect2">
 783 <a name="g-filename-display-name"></a><h3>g_filename_display_name ()</h3>
 784 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_filename_display_name             (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *filename</code></em>);</pre>
 785 <p>
 786 Converts a filename into a valid UTF-8 string. The conversion is
 787 not necessarily reversible, so you should keep the original around
 788 and use the return value of this function only for display purposes.
 789 Unlike <a class="link" href="glib-Character-Set-Conversion.html#g-filename-to-utf8" title="g_filename_to_utf8 ()"><code class="function">g_filename_to_utf8()</code></a>, the result is guaranteed to be non-<a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>
 790 even if the filename actually isn't in the GLib file name encoding.
 791 </p>
 792 <p>
 793 If GLib cannot make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
 794 replaces unknown characters with U+FFFD, the Unicode replacement character.
 795 You can search the result for the UTF-8 encoding of this character (which is
 796 "\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
 797 encoding.
 798 </p>
 799 <p>
 800 If you know the whole pathname of the file you should use
 801 <a class="link" href="glib-Character-Set-Conversion.html#g-filename-display-basename" title="g_filename_display_basename ()"><code class="function">g_filename_display_basename()</code></a>, since that allows location-based
 802 translation of filenames.
 803 </p>
 804 <div class="variablelist"><table border="0">
 805 <col align="left" valign="top">
 806 <tbody>
 807 <tr>
 808 <td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
 809 <td>a pathname hopefully in the GLib file name encoding</td>
 810 </tr>
 811 <tr>
 812 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 813 <td>a newly allocated string containing
 814 a rendition of the filename in valid UTF-8</td>
 815 </tr>
 816 </tbody>
 817 </table></div>
 818 <p class="since">Since 2.6</p>
 819 </div>
 820 <hr>
 821 <div class="refsect2">
 822 <a name="g-filename-display-basename"></a><h3>g_filename_display_basename ()</h3>
 823 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_filename_display_basename         (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *filename</code></em>);</pre>
 824 <p>
 825 Returns the display basename for the particular filename, guaranteed
 826 to be valid UTF-8. The display name might not be identical to the filename,
 827 for instance there might be problems converting it to UTF-8, and some files
 828 can be translated in the display.
 829 </p>
 830 <p>
 831 If GLib cannot make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
 832 replaces unknown characters with U+FFFD, the Unicode replacement character.
 833 You can search the result for the UTF-8 encoding of this character (which is
 834 "\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
 835 encoding.
 836 </p>
 837 <p>
 838 You must pass the whole absolute pathname to this functions so that
 839 translation of well known locations can be done.
 840 </p>
 841 <p>
 842 This function is preferred over <a class="link" href="glib-Character-Set-Conversion.html#g-filename-display-name" title="g_filename_display_name ()"><code class="function">g_filename_display_name()</code></a> if you know the
 843 whole path, as it allows translation.
 844 </p>
 845 <div class="variablelist"><table border="0">
 846 <col align="left" valign="top">
 847 <tbody>
 848 <tr>
 849 <td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
 850 <td>an absolute pathname in the GLib file name encoding</td>
 851 </tr>
 852 <tr>
 853 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 854 <td>a newly allocated string containing
 855 a rendition of the basename of the filename in valid UTF-8</td>
 856 </tr>
 857 </tbody>
 858 </table></div>
 859 <p class="since">Since 2.6</p>
 860 </div>
 861 <hr>
 862 <div class="refsect2">
 863 <a name="g-locale-from-utf8"></a><h3>g_locale_from_utf8 ()</h3>
 864 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_locale_from_utf8                  (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *utf8string</code></em>,
 865                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
 866                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_read</code></em>,
 867                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> *bytes_written</code></em>,
 868                                                          <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="struct GError"><span class="type">GError</span></a> **error</code></em>);</pre>
 869 <p>
 870 Converts a string from UTF-8 to the encoding used for strings by
 871 the C runtime (usually the same as that used by the operating
 872 system) in the <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a>. On
 873 Windows this means the system codepage.
 874 </p>
 875 <div class="variablelist"><table border="0">
 876 <col align="left" valign="top">
 877 <tbody>
 878 <tr>
 879 <td><p><span class="term"><em class="parameter"><code>utf8string</code></em> :</span></p></td>
 880 <td>a UTF-8 encoded string</td>
 881 </tr>
 882 <tr>
 883 <td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
 884 <td>the length of the string, or -1 if the string is
 885 nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">2</a>]</sup>.</td>
 886 </tr>
 887 <tr>
 888 <td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
 889 <td>location to store the number of bytes in the
 890 input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 891 Even if the conversion was successful, this may be
 892 less than <em class="parameter"><code>len</code></em> if there were partial characters
 893 at the end of the input. If the error
 894 <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
 895 stored will the byte offset after the last valid
 896 input sequence.</td>
 897 </tr>
 898 <tr>
 899 <td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
 900 <td>the number of bytes stored in the output buffer (not
 901 including the terminating nul).</td>
 902 </tr>
 903 <tr>
 904 <td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
 905 <td>location to store the error occurring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
 906 errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError"><span class="type">GConvertError</span></a> may occur.</td>
 907 </tr>
 908 <tr>
 909 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 910 <td>The converted string, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on an error.</td>
 911 </tr>
 912 </tbody>
 913 </table></div>
 914 </div>
 915 <hr>
 916 <div class="refsect2">
 917 <a name="GConvertError"></a><h3>enum GConvertError</h3>
 918 <pre class="programlisting">typedef enum {
 919   G_CONVERT_ERROR_NO_CONVERSION,
 920   G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
 921   G_CONVERT_ERROR_FAILED,
 922   G_CONVERT_ERROR_PARTIAL_INPUT,
 923   G_CONVERT_ERROR_BAD_URI,
 924   G_CONVERT_ERROR_NOT_ABSOLUTE_PATH
 925 } GConvertError;
 926 </pre>
 927 <p>
 928 Error codes returned by character set conversion routines.
 929 </p>
 930 <div class="variablelist"><table border="0">
 931 <col align="left" valign="top">
 932 <tbody>
 933 <tr>
 934 <td><p><a name="G-CONVERT-ERROR-NO-CONVERSION:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_NO_CONVERSION</code></span></p></td>
 935 <td>Conversion between the requested character
 936     sets is not supported.
 937 </td>
 938 </tr>
 939 <tr>
 940 <td><p><a name="G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</code></span></p></td>
 941 <td>Invalid byte sequence in conversion input.
 942 </td>
 943 </tr>
 944 <tr>
 945 <td><p><a name="G-CONVERT-ERROR-FAILED:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_FAILED</code></span></p></td>
 946 <td>Conversion failed for some reason.
 947 </td>
 948 </tr>
 949 <tr>
 950 <td><p><a name="G-CONVERT-ERROR-PARTIAL-INPUT:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_PARTIAL_INPUT</code></span></p></td>
 951 <td>Partial character sequence at end of input.
 952 </td>
 953 </tr>
 954 <tr>
 955 <td><p><a name="G-CONVERT-ERROR-BAD-URI:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_BAD_URI</code></span></p></td>
 956 <td>URI is invalid.
 957 </td>
 958 </tr>
 959 <tr>
 960 <td><p><a name="G-CONVERT-ERROR-NOT-ABSOLUTE-PATH:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_NOT_ABSOLUTE_PATH</code></span></p></td>
 961 <td>Pathname is not an absolute path.
 962 </td>
 963 </tr>
 964 </tbody>
 965 </table></div>
 966 </div>
 967 <hr>
 968 <div class="refsect2">
 969 <a name="g-get-charset"></a><h3>g_get_charset ()</h3>
 970 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a>            g_get_charset                       (<em class="parameter"><code>const <span class="type">char</span> **charset</code></em>);</pre>
 971 <p>
 972 Obtains the character set for the <a class="link" href="glib-running.html#setlocale" title="Locale">current
 973 locale</a>; you might use this character set as an argument to
 974 <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a>, to convert from the current locale's encoding to some
 975 other encoding. (Frequently <a class="link" href="glib-Character-Set-Conversion.html#g-locale-to-utf8" title="g_locale_to_utf8 ()"><code class="function">g_locale_to_utf8()</code></a> and <a class="link" href="glib-Character-Set-Conversion.html#g-locale-from-utf8" title="g_locale_from_utf8 ()"><code class="function">g_locale_from_utf8()</code></a>
 976 are nice shortcuts, though.)
 977 </p>
 978 <p>
 979 On Windows the character set returned by this function is the
 980 so-called system default ANSI code-page. That is the character set
 981 used by the "narrow" versions of C library and Win32 functions that
 982 handle file names. It might be different from the character set
 983 used by the C library's current locale.
 984 </p>
 985 <p>
 986 The return value is <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the locale's encoding is UTF-8, in that
 987 case you can perhaps avoid calling <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a>.
 988 </p>
 989 <p>
 990 The string returned in <em class="parameter"><code>charset</code></em> is not allocated, and should not be
 991 freed.
 992 </p>
 993 <div class="variablelist"><table border="0">
 994 <col align="left" valign="top">
 995 <tbody>
 996 <tr>
 997 <td><p><span class="term"><em class="parameter"><code>charset</code></em> :</span></p></td>
 998 <td>return location for character set name</td>
 999 </tr>
1000 <tr>
1001 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1002 <td>
1003 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the returned charset is UTF-8</td>
1004 </tr>
1005 </tbody>
1006 </table></div>
1007 </div>
1008 <hr>
1009 <div class="refsect2">
1010 <a name="g-get-codeset"></a><h3>g_get_codeset ()</h3>
1011 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> *             g_get_codeset                       (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
1012 <p>
1013 Gets the character set for the current locale.
1014 </p>
1015 <div class="variablelist"><table border="0">
1016 <col align="left" valign="top">
1017 <tbody><tr>
1018 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
1019 <td>a newly allocated string containing the name
1020 of the character set. This string must be freed with <a class="link" href="glib-Memory-Allocation.html#g-free" title="g_free ()"><code class="function">g_free()</code></a>.</td>
1021 </tr></tbody>
1022 </table></div>
1023 </div>
1024 </div>
1025 <div class="footnotes">
1026 <br><hr width="100" align="left">
1027 <div class="footnote"><p><sup>[<a id="ftn.nul-unsafe" href="#nul-unsafe" class="para">2</a>] </sup>
1028 Note that some encodings may allow nul bytes to
1029 occur inside strings. In that case, using -1 for
1030 the <em class="parameter"><code>len</code></em> parameter is unsafe.
1031 </p></div>
1032 <div class="footnote"><p><sup>[<a id="ftn.streaming-state" href="#streaming-state" class="para">3</a>] </sup>
1033 Despite the fact that <em class="parameter"><code>byes_read</code></em> can return information about partial
1034 characters, the <code class="literal">g_convert_...</code> functions
1035 are not generally suitable for streaming. If the underlying converter
1036 being used maintains internal state, then this won't be preserved
1037 across successive calls to <a class="link" href="glib-Character-Set-Conversion.html#g-convert" title="g_convert ()"><code class="function">g_convert()</code></a>, <a class="link" href="glib-Character-Set-Conversion.html#g-convert-with-iconv" title="g_convert_with_iconv ()"><code class="function">g_convert_with_iconv()</code></a> or
1038 <a class="link" href="glib-Character-Set-Conversion.html#g-convert-with-fallback" title="g_convert_with_fallback ()"><code class="function">g_convert_with_fallback()</code></a>. (An example of this is the GNU C converter
1039 for CP1255 which does not emit a base character until it knows that
1040 the next character is not a mark that could combine with the base
1041 character.)
1042  </p></div>
1043 </div>
1044 </div>
1045 <div class="footer">
1046 <hr>
1047           Generated by GTK-Doc V1.18</div>
1048 </body>
1049 </html>