RubyGems - gio2 - Versions diffs - 0.90.3-x86-mingw32 - Mend

gio2 0.90.3-x86-mingw32

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (856) hide show

data/vendor/local/share/gtk-doc/html/glib/glib-Caches.html ADDED

@@ -0,0 +1,398 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Caches</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GLib Reference Manual">
+<link rel="up" href="glib-data-types.html" title="GLib Data Types">
+<link rel="prev" href="glib-Relations-and-Tuples.html" title="Relations and Tuples">
+<link rel="next" href="glib-Memory-Allocators.html" title="Memory Allocators">
+<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
+<tr valign="middle">
+<td><a accesskey="p" href="glib-Relations-and-Tuples.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GLib Reference Manual</th>
+<td><a accesskey="n" href="glib-Memory-Allocators.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr>
+<tr><td colspan="5" class="shortcuts">
+<a href="#glib-Caches.synopsis" class="shortcut">Top</a>
+                   |
+                  <a href="#glib-Caches.description" class="shortcut">Description</a>
+</td></tr>
+</table>
+<div class="refentry">
+<a name="glib-Caches"></a><div class="titlepage"></div>
+<div class="refnamediv"><table width="100%"><tr>
+<td valign="top">
+<h2><span class="refentrytitle"><a name="glib-Caches.top_of_page"></a>Caches</span></h2>
+<p>Caches — caches allow sharing of complex data structures
+                    to save resources</p>
+</td>
+<td valign="top" align="right"></td>
+</tr></table></div>
+<div class="refsynopsisdiv">
+<a name="glib-Caches.synopsis"></a><h2>Synopsis</h2>
+<pre class="synopsis">
+#include &lt;glib.h&gt;
+                    <a class="link" href="glib-Caches.html#GCache" title="GCache">GCache</a>;
+<a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="returnvalue">GCache</span></a> *            <a class="link" href="glib-Caches.html#g-cache-new" title="g_cache_new ()">g_cache_new</a>                         (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheNewFunc" title="GCacheNewFunc ()"><span class="type">GCacheNewFunc</span></a> value_new_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheDestroyFunc" title="GCacheDestroyFunc ()"><span class="type">GCacheDestroyFunc</span></a> value_destroy_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheDupFunc" title="GCacheDupFunc ()"><span class="type">GCacheDupFunc</span></a> key_dup_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheDestroyFunc" title="GCacheDestroyFunc ()"><span class="type">GCacheDestroyFunc</span></a> key_destroy_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHashFunc" title="GHashFunc ()"><span class="type">GHashFunc</span></a> hash_key_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHashFunc" title="GHashFunc ()"><span class="type">GHashFunc</span></a> hash_value_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GEqualFunc" title="GEqualFunc ()"><span class="type">GEqualFunc</span></a> key_equal_func</code></em>);
+<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Caches.html#g-cache-insert" title="g_cache_insert ()">g_cache_insert</a>                      (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> key</code></em>);
+<span class="returnvalue">void</span>                <a class="link" href="glib-Caches.html#g-cache-remove" title="g_cache_remove ()">g_cache_remove</a>                      (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> value</code></em>);
+<span class="returnvalue">void</span>                <a class="link" href="glib-Caches.html#g-cache-destroy" title="g_cache_destroy ()">g_cache_destroy</a>                     (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>);
+<span class="returnvalue">void</span>                <a class="link" href="glib-Caches.html#g-cache-key-foreach" title="g_cache_key_foreach ()">g_cache_key_foreach</a>                 (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHFunc" title="GHFunc ()"><span class="type">GHFunc</span></a> func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
+<span class="returnvalue">void</span>                <a class="link" href="glib-Caches.html#g-cache-value-foreach" title="g_cache_value_foreach ()">g_cache_value_foreach</a>               (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHFunc" title="GHFunc ()"><span class="type">GHFunc</span></a> func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
+<span class="returnvalue">void</span>                (<a class="link" href="glib-Caches.html#GCacheDestroyFunc" title="GCacheDestroyFunc ()">*GCacheDestroyFunc</a>)                (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);
+<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (<a class="link" href="glib-Caches.html#GCacheDupFunc" title="GCacheDupFunc ()">*GCacheDupFunc</a>)                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);
+<a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (<a class="link" href="glib-Caches.html#GCacheNewFunc" title="GCacheNewFunc ()">*GCacheNewFunc</a>)                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> key</code></em>);
+</pre>
+</div>
+<div class="refsect1">
+<a name="glib-Caches.description"></a><h2>Description</h2>
+<p>
+A <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> allows sharing of complex data structures, in order to
+save system resources.
+</p>
+<p>
+GTK+ uses caches for <a href="http://library.gnome.org/devel/gtk/unstable/GtkStyle.html"><span class="type">GtkStyles</span></a> and <a href="http://library.gnome.org/devel/gdk/unstable/gdk3-Graphics-Contexts.html#GdkGC"><span class="type">GdkGCs</span></a>. These consume a lot of
+resources, so a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> is used to see if a <a href="http://library.gnome.org/devel/gtk/unstable/GtkStyle.html"><span class="type">GtkStyle</span></a> or <a href="http://library.gnome.org/devel/gdk/unstable/gdk3-Graphics-Contexts.html#GdkGC"><span class="type">GdkGC</span></a> with
+the required properties already exists. If it does, then the
+existing object is used instead of creating a new one.
+</p>
+<p>
+<a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> uses keys and values. A <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key describes the properties
+of a particular resource. A <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value is the actual resource.
+</p>
+</div>
+<div class="refsect1">
+<a name="glib-Caches.details"></a><h2>Details</h2>
+<div class="refsect2">
+<a name="GCache"></a><h3>GCache</h3>
+<pre class="programlisting">typedef struct _GCache GCache;</pre>
+<p>
+The <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> struct is an opaque data structure containing
+information about a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>. It should only be accessed via the
+following functions.
+</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-cache-new"></a><h3>g_cache_new ()</h3>
+<pre class="programlisting"><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="returnvalue">GCache</span></a> *            g_cache_new                         (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheNewFunc" title="GCacheNewFunc ()"><span class="type">GCacheNewFunc</span></a> value_new_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheDestroyFunc" title="GCacheDestroyFunc ()"><span class="type">GCacheDestroyFunc</span></a> value_destroy_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheDupFunc" title="GCacheDupFunc ()"><span class="type">GCacheDupFunc</span></a> key_dup_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Caches.html#GCacheDestroyFunc" title="GCacheDestroyFunc ()"><span class="type">GCacheDestroyFunc</span></a> key_destroy_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHashFunc" title="GHashFunc ()"><span class="type">GHashFunc</span></a> hash_key_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHashFunc" title="GHashFunc ()"><span class="type">GHashFunc</span></a> hash_value_func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GEqualFunc" title="GEqualFunc ()"><span class="type">GEqualFunc</span></a> key_equal_func</code></em>);</pre>
+<p>
+Creates a new <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>value_new_func</code></em> :</span></p></td>
+<td>a function to create a new object given a key.
+                 This is called by <a class="link" href="glib-Caches.html#g-cache-insert" title="g_cache_insert ()"><code class="function">g_cache_insert()</code></a> if an object
+                 with the given key does not already exist.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>value_destroy_func</code></em> :</span></p></td>
+<td>a function to destroy an object. It is called
+                     by <a class="link" href="glib-Caches.html#g-cache-remove" title="g_cache_remove ()"><code class="function">g_cache_remove()</code></a> when the object is no
+                     longer needed (i.e. its reference count drops
+                     to 0).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>key_dup_func</code></em> :</span></p></td>
+<td>a function to copy a key. It is called by
+               <a class="link" href="glib-Caches.html#g-cache-insert" title="g_cache_insert ()"><code class="function">g_cache_insert()</code></a> if the key does not already exist in
+               the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>key_destroy_func</code></em> :</span></p></td>
+<td>a function to destroy a key. It is called by
+                   <a class="link" href="glib-Caches.html#g-cache-remove" title="g_cache_remove ()"><code class="function">g_cache_remove()</code></a> when the object is no longer
+                   needed (i.e. its reference count drops to 0).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>hash_key_func</code></em> :</span></p></td>
+<td>a function to create a hash value from a key.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>hash_value_func</code></em> :</span></p></td>
+<td>a function to create a hash value from a value.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>key_equal_func</code></em> :</span></p></td>
+<td>a function to compare two keys. It should return
+                 <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if the two keys are equivalent.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td>a new <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-cache-insert"></a><h3>g_cache_insert ()</h3>
+<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_cache_insert                      (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> key</code></em>);</pre>
+<p>
+Gets the value corresponding to the given key, creating it if
+necessary. It first checks if the value already exists in the
+<a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>, by using the <em class="parameter"><code>key_equal_func</code></em> function passed to
+<a class="link" href="glib-Caches.html#g-cache-new" title="g_cache_new ()"><code class="function">g_cache_new()</code></a>. If it does already exist it is returned, and its
+reference count is increased by one. If the value does not currently
+exist, if is created by calling the <em class="parameter"><code>value_new_func</code></em>. The key is
+duplicated by calling <em class="parameter"><code>key_dup_func</code></em> and the duplicated key and value
+are inserted into the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>cache</code></em> :</span></p></td>
+<td>a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
+<td>a key describing a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> object.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td>a pointer to a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-cache-remove"></a><h3>g_cache_remove ()</h3>
+<pre class="programlisting"><span class="returnvalue">void</span>                g_cache_remove                      (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gconstpointer" title="gconstpointer"><span class="type">gconstpointer</span></a> value</code></em>);</pre>
+<p>
+Decreases the reference count of the given value. If it drops to 0
+then the value and its corresponding key are destroyed, using the
+<em class="parameter"><code>value_destroy_func</code></em> and <em class="parameter"><code>key_destroy_func</code></em> passed to <a class="link" href="glib-Caches.html#g-cache-new" title="g_cache_new ()"><code class="function">g_cache_new()</code></a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>cache</code></em> :</span></p></td>
+<td>a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
+<td>the value to remove.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-cache-destroy"></a><h3>g_cache_destroy ()</h3>
+<pre class="programlisting"><span class="returnvalue">void</span>                g_cache_destroy                     (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>);</pre>
+<p>
+Frees the memory allocated for the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</p>
+<p>
+Note that it does not destroy the keys and values which were
+contained in the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody><tr>
+<td><p><span class="term"><em class="parameter"><code>cache</code></em> :</span></p></td>
+<td>a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr></tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-cache-key-foreach"></a><h3>g_cache_key_foreach ()</h3>
+<pre class="programlisting"><span class="returnvalue">void</span>                g_cache_key_foreach                 (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHFunc" title="GHFunc ()"><span class="type">GHFunc</span></a> func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
+<p>
+Calls the given function for each of the keys in the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</p>
+<p>
+NOTE <em class="parameter"><code>func</code></em> is passed three parameters, the value and key of a cache
+entry and the <em class="parameter"><code>user_data</code></em>. The order of value and key is different
+from the order in which <a class="link" href="glib-Hash-Tables.html#g-hash-table-foreach" title="g_hash_table_foreach ()"><code class="function">g_hash_table_foreach()</code></a> passes key-value
+pairs to its callback function !
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>cache</code></em> :</span></p></td>
+<td>a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
+<td>the function to call with each <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
+<td>user data to pass to the function.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-cache-value-foreach"></a><h3>g_cache_value_foreach ()</h3>
+<pre class="programlisting"><span class="returnvalue">void</span>                g_cache_value_foreach               (<em class="parameter"><code><a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> *cache</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Hash-Tables.html#GHFunc" title="GHFunc ()"><span class="type">GHFunc</span></a> func</code></em>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
+<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
+<h3 class="title">Warning</h3>
+<p><code class="literal">g_cache_value_foreach</code> has been deprecated since version 2.10 and should not be used in newly-written code. The reason is that it passes pointers to internal
+                 data structures to <em class="parameter"><code>func</code></em>; use <a class="link" href="glib-Caches.html#g-cache-key-foreach" title="g_cache_key_foreach ()"><code class="function">g_cache_key_foreach()</code></a>
+                 instead</p>
+</div>
+<p>
+Calls the given function for each of the values in the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>cache</code></em> :</span></p></td>
+<td>a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
+<td>the function to call with each <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
+<td>user data to pass to the function.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="GCacheDestroyFunc"></a><h3>GCacheDestroyFunc ()</h3>
+<pre class="programlisting"><span class="returnvalue">void</span>                (*GCacheDestroyFunc)                (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);</pre>
+<p>
+Specifies the type of the <em class="parameter"><code>value_destroy_func</code></em> and <em class="parameter"><code>key_destroy_func</code></em>
+functions passed to <a class="link" href="glib-Caches.html#g-cache-new" title="g_cache_new ()"><code class="function">g_cache_new()</code></a>. The functions are passed a
+pointer to the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key or <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value and should free any
+memory and other resources associated with it.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody><tr>
+<td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
+<td>the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value to destroy.
+</td>
+</tr></tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="GCacheDupFunc"></a><h3>GCacheDupFunc ()</h3>
+<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (*GCacheDupFunc)                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> value</code></em>);</pre>
+<p>
+Specifies the type of the <em class="parameter"><code>key_dup_func</code></em> function passed to
+<a class="link" href="glib-Caches.html#g-cache-new" title="g_cache_new ()"><code class="function">g_cache_new()</code></a>. The function is passed a key
+(<span class="emphasis"><em>not</em></span> a value as the prototype implies) and
+should return a duplicate of the key.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>value</code></em> :</span></p></td>
+<td>the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key to destroy (<span class="emphasis"><em>not</em></span> a
+        <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value as it seems).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td>a copy of the <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="GCacheNewFunc"></a><h3>GCacheNewFunc ()</h3>
+<pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            (*GCacheNewFunc)                    (<em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> key</code></em>);</pre>
+<p>
+Specifies the type of the <em class="parameter"><code>value_new_func</code></em> function passed to
+<a class="link" href="glib-Caches.html#g-cache-new" title="g_cache_new ()"><code class="function">g_cache_new()</code></a>. It is passed a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key and should create the
+value corresponding to the key.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>key</code></em> :</span></p></td>
+<td>a <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> key.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td>a new <a class="link" href="glib-Caches.html#GCache" title="GCache"><span class="type">GCache</span></a> value corresponding to the key.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>

data/vendor/local/share/gtk-doc/html/glib/glib-Character-Set-Conversion.html ADDED

@@ -0,0 +1,1094 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<title>Character Set Conversion</title>
+<meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
+<link rel="home" href="index.html" title="GLib Reference Manual">
+<link rel="up" href="glib-utilities.html" title="GLib Utilities">
+<link rel="prev" href="glib-String-Utility-Functions.html" title="String Utility Functions">
+<link rel="next" href="glib-Unicode-Manipulation.html" title="Unicode Manipulation">
+<meta name="generator" content="GTK-Doc V1.15.1 (XML mode)">
+<link rel="stylesheet" href="style.css" type="text/css">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
+<tr valign="middle">
+<td><a accesskey="p" href="glib-String-Utility-Functions.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
+<td><a accesskey="u" href="glib-utilities.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
+<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
+<th width="100%" align="center">GLib Reference Manual</th>
+<td><a accesskey="n" href="glib-Unicode-Manipulation.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
+</tr>
+<tr><td colspan="5" class="shortcuts">
+<a href="#glib-Character-Set-Conversion.synopsis" class="shortcut">Top</a>
+                   |
+                  <a href="#glib-Character-Set-Conversion.description" class="shortcut">Description</a>
+</td></tr>
+</table>
+<div class="refentry">
+<a name="glib-Character-Set-Conversion"></a><div class="titlepage"></div>
+<div class="refnamediv"><table width="100%"><tr>
+<td valign="top">
+<h2><span class="refentrytitle"><a name="glib-Character-Set-Conversion.top_of_page"></a>Character Set Conversion</span></h2>
+<p>Character Set Conversion — Convert strings between different character sets</p>
+</td>
+<td valign="top" align="right"></td>
+</tr></table></div>
+<div class="refsynopsisdiv">
+<a name="glib-Character-Set-Conversion.synopsis"></a><h2>Synopsis</h2>
+<pre class="synopsis">
+#include &lt;glib.h&gt;
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+                    <a class="link" href="glib-Character-Set-Conversion.html#GIConv" title="GIConv">GIConv</a>;
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+#define             <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR:CAPS" title="G_CONVERT_ERROR">G_CONVERT_ERROR</a>
+<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>,
+                                                         <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>);
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **inbuf</code></em>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **outbuf</code></em>,
+                                                         <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>);
+<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>);
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+<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>G_CONST_RETURN <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> ***charsets</code></em>);
+<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>);
+<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>);
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);
+enum                <a class="link" href="glib-Character-Set-Conversion.html#GConvertError" title="enum GConvertError">GConvertError</a>;
+<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>G_CONST_RETURN <span class="type">char</span> **charset</code></em>);
+</pre>
+</div>
+<div class="refsect1">
+<a name="glib-Character-Set-Conversion.description"></a><h2>Description</h2>
+<p>
+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
+addition to pure character set conversions, GLib has functions to deal
+with the extra complications of encodings for file names.
+</p>
+<p>
+</p>
+<div class="refsect2">
+<a name="file-name-encodings"></a><h3>File Name Encodings</h3>
+<p>
+Historically, Unix has not had a defined encoding for file
+names:  a file name is valid as long as it does not have path
+separators in it ("/").  However, displaying file names may
+require conversion:  from the character set in which they were
+created, to the character set in which the application
+operates.  Consider the Spanish file name
+"<code class="filename">Presentación.sxi</code>".  If the
+application which created it uses ISO-8859-1 for its encoding,
+</p>
+<a name="filename-iso8859-1"></a><pre class="programlisting">
+Character:  P  r  e  s  e  n  t  a  c  i  ó  n  .  s  x  i
+Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
+</pre>
+<p>
+However, if the application use UTF-8, the actual file name on
+disk would look like this:
+</p>
+<a name="filename-utf-8"></a><pre class="programlisting">
+Character:  P  r  e  s  e  n  t  a  c  i  ó     n  .  s  x  i
+Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
+</pre>
+<p>
+Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
+that use Glib do the same thing.  If you get a file name from
+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>,
+and you wish to display the file name to the user, you
+<span class="emphasis"><em>will</em></span> need to convert it into UTF-8.  The
+opposite case is when the user types the name of a file he
+wishes to save:  the toolkit will give you that string in
+UTF-8 encoding, and you will need to convert it to the
+character set used for file names before you can create the
+file with open(2) or fopen(3).
+</p>
+<p>
+By default, Glib assumes that file names on disk are in UTF-8
+encoding.  This is a valid assumption for file systems which
+were created relatively recently:  most applications use UTF-8
+encoding for their strings, and that is also what they use for
+the file names they create.  However, older file systems may
+still contain file names created in "older" encodings, such as
+ISO-8859-1. In this case, for compatibility reasons, you may
+want to instruct Glib to use that particular encoding for file
+names rather than UTF-8.  You can do this by specifying the
+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>
+environment variable.  For example, if your installation uses
+ISO-8859-1 for file names, you can put this in your
+<code class="filename">~/.profile</code>:
+</p>
+<pre class="programlisting">
+export G_FILENAME_ENCODING=ISO-8859-1
+</pre>
+<p>
+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
+<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
+functions convert file names from the encoding specified in
+<code class="envar">G_FILENAME_ENCODING</code> to UTF-8 and vice-versa.
+<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
+these functions are used to convert between UTF-8 and the
+encoding for file names in the file system.
+</p>
+<div class="figure">
+<a name="file-name-encodings-diagram"></a><p class="title"><b>Figure 2. Conversion between File Name Encodings</b></p>
+<div class="figure-contents"><div><img src="file-name-encodings.png" alt="Conversion between File Name Encodings"></div></div>
+</div>
+<br class="figure-break"><div class="refsect3">
+<a name="file-name-encodings-checklist"></a><h4>Checklist for Application Writers</h4>
+<p>
+This section is a practical summary of the detailed
+description above.  You can use this as a checklist of
+things to do to make sure your applications process file
+name encodings correctly.
+</p>
+<div class="orderedlist"><ol class="orderedlist" type="1">
+<li class="listitem"><p>
+If you get a file name from the file system from a function
+such as readdir(3) or <a href="http://library.gnome.org/devel/gtk/unstable/GtkFileChooser.html#gtk-file-chooser-get-filename"><code class="function">gtk_file_chooser_get_filename()</code></a>,
+you do not need to do any conversion to pass that
+file name to functions like open(2), rename(2), or
+fopen(3) — those are "raw" file names which the file
+system understands.
+</p></li>
+<li class="listitem"><p>
+If you need to display a file name, convert it to UTF-8 first by
+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
+"<code class="literal">Unknown file name</code>". <span class="emphasis"><em>Do not</em></span>
+convert this string back into the encoding used for file names if you
+wish to pass it to the file system; use the original file name instead.
+For example, the document window of a word processor could display
+"Unknown file name" in its title bar but still let the user save the
+file, as it would keep the raw file name internally. This can happen
+if the user has not set the <code class="envar">G_FILENAME_ENCODING</code>
+environment variable even though he has files whose names are not
+encoded in UTF-8.
+</p></li>
+<li class="listitem"><p>
+If your user interface lets the user type a file name for saving or
+renaming, convert it to the encoding used for file names in the file
+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
+to functions like fopen(3). If conversion fails, ask the user to enter
+a different file name. This can happen if the user types Japanese
+characters when <code class="envar">G_FILENAME_ENCODING</code> is set to
+<code class="literal">ISO-8859-1</code>, for example.
+</p></li>
+</ol></div>
+</div>
+</div>
+<p>
+</p>
+</div>
+<div class="refsect1">
+<a name="glib-Character-Set-Conversion.details"></a><h2>Details</h2>
+<div class="refsect2">
+<a name="g-convert"></a><h3>g_convert ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string from one character set to another.
+</p>
+<p>
+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
+conversions<sup>[<a href="glib-Character-Set-Conversion.html#ftn.streaming-state" class="footnoteref">2</a>]</sup>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
+<td>the string to convert
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+                nul-terminated<sup>[<a name="nul-unsafe" href="#ftn.nul-unsafe" class="footnote">1</a>]</sup>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>to_codeset</code></em> :</span></p></td>
+<td>name of character set into which to convert <em class="parameter"><code>str</code></em>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>from_codeset</code></em> :</span></p></td>
+<td>character set of <em class="parameter"><code>str</code></em>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+                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>.
+                Even if the conversion was successful, this may be
+                less than <em class="parameter"><code>len</code></em> if there were partial characters
+                at the end of the input. If the error
+                <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
+                stored will the byte offset after the last valid
+                input sequence.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+                including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+                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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> If the conversion was successful, a newly allocated
+              nul-terminated string, which must be freed with
+              <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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-convert-with-fallback"></a><h3>g_convert_with_fallback ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string from one character set to another, possibly
+including fallback sequences for characters not representable
+in the output. Note that it is not guaranteed that the specification
+for the fallback sequences in <em class="parameter"><code>fallback</code></em> will be honored. Some
+systems may do an approximate conversion from <em class="parameter"><code>from_codeset</code></em>
+to <em class="parameter"><code>to_codeset</code></em> in their <code class="function">iconv()</code> functions,
+in which case GLib will simply return that approximate conversion.
+</p>
+<p>
+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
+conversions<sup>[<a href="glib-Character-Set-Conversion.html#ftn.streaming-state" class="footnoteref">2</a>]</sup>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
+<td>the string to convert
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+               nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">1</a>]</sup>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>to_codeset</code></em> :</span></p></td>
+<td>name of character set into which to convert <em class="parameter"><code>str</code></em>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>from_codeset</code></em> :</span></p></td>
+<td>character set of <em class="parameter"><code>str</code></em>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>fallback</code></em> :</span></p></td>
+<td>UTF-8 string to use in place of character not
+               present in the target encoding. (The string must be
+               representable in the target encoding).
+                  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
+                  be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+               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>.
+               Even if the conversion was successful, this may be
+               less than <em class="parameter"><code>len</code></em> if there were partial characters
+               at the end of the input.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+               including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+               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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> If the conversion was successful, a newly allocated
+              nul-terminated string, which must be freed with
+              <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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="GIConv"></a><h3>GIConv</h3>
+<pre class="programlisting">typedef struct _GIConv GIConv;</pre>
+<p>
+</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-convert-with-iconv"></a><h3>g_convert_with_iconv ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string from one character set to another.
+</p>
+<p>
+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
+conversions<sup>[<a name="streaming-state" href="#ftn.streaming-state" class="footnote">2</a>]</sup>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>str</code></em> :</span></p></td>
+<td>the string to convert
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+                nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">1</a>]</sup>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td>
+<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>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+                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>.
+                Even if the conversion was successful, this may be
+                less than <em class="parameter"><code>len</code></em> if there were partial characters
+                at the end of the input. If the error
+                <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
+                stored will the byte offset after the last valid
+                input sequence.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+                including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+                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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> If the conversion was successful, a newly allocated
+              nul-terminated string, which must be freed with
+              <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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="G-CONVERT-ERROR:CAPS"></a><h3>G_CONVERT_ERROR</h3>
+<pre class="programlisting">#define G_CONVERT_ERROR g_convert_error_quark()
+</pre>
+<p>
+Error domain for character set conversions. Errors in this domain will
+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="GError"><span class="type">GError</span></a> for information on
+error domains.
+</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-iconv-open"></a><h3>g_iconv_open ()</h3>
+<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>,
+                                                         <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>
+<p>
+Same as the standard UNIX routine <code class="function">iconv_open()</code>, but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation.
+</p>
+<p>
+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
+more convenient than the raw iconv wrappers.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>to_codeset</code></em> :</span></p></td>
+<td>destination codeset
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>from_codeset</code></em> :</span></p></td>
+<td>source codeset
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> a "conversion descriptor", or (GIConv)-1 if
+ opening the converter failed.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-iconv"></a><h3>g_iconv ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **inbuf</code></em>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **outbuf</code></em>,
+                                                         <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>
+<p>
+Same as the standard UNIX routine <code class="function">iconv()</code>, but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation.
+</p>
+<p>
+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
+more convenient than the raw iconv wrappers.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td>
+<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>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>inbuf</code></em> :</span></p></td>
+<td>bytes to convert
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>inbytes_left</code></em> :</span></p></td>
+<td>inout parameter, bytes remaining to convert in <em class="parameter"><code>inbuf</code></em>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>outbuf</code></em> :</span></p></td>
+<td>converted output bytes
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>outbytes_left</code></em> :</span></p></td>
+<td>inout parameter, bytes available to fill in <em class="parameter"><code>outbuf</code></em>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> count of non-reversible conversions, or -1 on error
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-iconv-close"></a><h3>g_iconv_close ()</h3>
+<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>
+<p>
+Same as the standard UNIX routine <code class="function">iconv_close()</code>, but
+may be implemented via libiconv on UNIX flavors that lack
+a native implementation. Should be called to clean up
+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
+you are done converting things.
+</p>
+<p>
+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
+more convenient than the raw iconv wrappers.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>converter</code></em> :</span></p></td>
+<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>
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> -1 on error, 0 on success
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-locale-to-utf8"></a><h3>g_locale_to_utf8 ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string which is in the encoding used for strings by
+the C runtime (usually the same as that used by the operating
+system) in the <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a> into a
+UTF-8 string.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>opsysstring</code></em> :</span></p></td>
+<td>a string in the encoding of the current locale. On Windows
+                this means the system codepage.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+                nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">1</a>]</sup>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+                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>.
+                Even if the conversion was successful, this may be
+                less than <em class="parameter"><code>len</code></em> if there were partial characters
+                at the end of the input. If the error
+                <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
+                stored will the byte offset after the last valid
+                input sequence.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+                including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+                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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-filename-to-utf8"></a><h3>g_filename_to_utf8 ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string which is in the encoding used by GLib for
+filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
+for filenames; on other platforms, this function indirectly depends on
+the <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>opsysstring</code></em> :</span></p></td>
+<td>a string in the encoding for filenames
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+                nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">1</a>]</sup>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+                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>.
+                Even if the conversion was successful, this may be
+                less than <em class="parameter"><code>len</code></em> if there were partial characters
+                at the end of the input. If the error
+                <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
+                stored will the byte offset after the last valid
+                input sequence.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+                including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+                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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-filename-from-utf8"></a><h3>g_filename_from_utf8 ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string from UTF-8 to the encoding GLib uses for
+filenames. Note that on Windows GLib uses UTF-8 for filenames;
+on other platforms, this function indirectly depends on the
+<a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a>.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>utf8string</code></em> :</span></p></td>
+<td>a UTF-8 encoded string.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+                nul-terminated.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+                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>.
+                Even if the conversion was successful, this may be
+                less than <em class="parameter"><code>len</code></em> if there were partial characters
+                at the end of the input. If the error
+                <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
+                stored will the byte offset after the last valid
+                input sequence.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+                including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+                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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-get-filename-charsets"></a><h3>g_get_filename_charsets ()</h3>
+<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>G_CONST_RETURN <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> ***charsets</code></em>);</pre>
+<p>
+Determines the preferred character sets used for filenames.
+The first character set from the <em class="parameter"><code>charsets</code></em> is the filename encoding, the
+subsequent character sets are used when trying to generate a displayable
+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>.
+</p>
+<p>
+On Unix, the character sets are determined by consulting the
+environment variables <code class="envar">G_FILENAME_ENCODING</code> and
+<code class="envar">G_BROKEN_FILENAMES</code>. On Windows, the character set
+used in the GLib API is always UTF-8 and said environment variables
+have no effect.
+</p>
+<p>
+<code class="envar">G_FILENAME_ENCODING</code> may be set to a comma-separated list
+of character set names. The special token "@locale" is taken to
+mean the character set for the <a class="link" href="glib-running.html#setlocale" title="Locale">current
+locale</a>. If <code class="envar">G_FILENAME_ENCODING</code> is not set, but
+<code class="envar">G_BROKEN_FILENAMES</code> is, the character set of the current
+locale is taken as the filename encoding. If neither environment variable
+is set, UTF-8 is taken as the filename encoding, but the character
+set of the current locale is also put in the list of encodings.
+</p>
+<p>
+The returned <em class="parameter"><code>charsets</code></em> belong to GLib and must not be freed.
+</p>
+<p>
+Note that on Unix, regardless of the locale character set or
+<code class="envar">G_FILENAME_ENCODING</code> value, the actual file names present
+on a system might be in any random encoding or just gibberish.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>charsets</code></em> :</span></p></td>
+<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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> <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>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 2.6</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-filename-display-name"></a><h3>g_filename_display_name ()</h3>
+<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>
+<p>
+Converts a filename into a valid UTF-8 string. The conversion is
+not necessarily reversible, so you should keep the original around
+and use the return value of this function only for display purposes.
+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>
+even if the filename actually isn't in the GLib file name encoding.
+</p>
+<p>
+If GLib can not make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
+replaces unknown characters with U+FFFD, the Unicode replacement character.
+You can search the result for the UTF-8 encoding of this character (which is
+"\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
+encoding.
+</p>
+<p>
+If you know the whole pathname of the file you should use
+<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
+translation of filenames.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
+<td>a pathname hopefully in the GLib file name encoding
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> a newly allocated string containing
+  a rendition of the filename in valid UTF-8
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 2.6</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-filename-display-basename"></a><h3>g_filename_display_basename ()</h3>
+<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>
+<p>
+Returns the display basename for the particular filename, guaranteed
+to be valid UTF-8. The display name might not be identical to the filename,
+for instance there might be problems converting it to UTF-8, and some files
+can be translated in the display.
+</p>
+<p>
+If GLib can not make sense of the encoding of <em class="parameter"><code>filename</code></em>, as a last resort it
+replaces unknown characters with U+FFFD, the Unicode replacement character.
+You can search the result for the UTF-8 encoding of this character (which is
+"\357\277\275" in octal notation) to find out if <em class="parameter"><code>filename</code></em> was in an invalid
+encoding.
+</p>
+<p>
+You must pass the whole absolute pathname to this functions so that
+translation of well known locations can be done.
+</p>
+<p>
+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
+whole path, as it allows translation.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>filename</code></em> :</span></p></td>
+<td>an absolute pathname in the GLib file name encoding
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> a newly allocated string containing
+  a rendition of the basename of the filename in valid UTF-8
+</td>
+</tr>
+</tbody>
+</table></div>
+<p class="since">Since 2.6</p>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-locale-from-utf8"></a><h3>g_locale_from_utf8 ()</h3>
+<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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gssize" title="gssize"><span class="type">gssize</span></a> len</code></em>,
+                                                         <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>,
+                                                         <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>,
+                                                         <em class="parameter"><code><a class="link" href="glib-Error-Reporting.html#GError" title="GError"><span class="type">GError</span></a> **error</code></em>);</pre>
+<p>
+Converts a string from UTF-8 to the encoding used for strings by
+the C runtime (usually the same as that used by the operating
+system) in the <a class="link" href="glib-running.html#setlocale" title="Locale">current locale</a>. On
+Windows this means the system codepage.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>utf8string</code></em> :</span></p></td>
+<td>a UTF-8 encoded string
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>len</code></em> :</span></p></td>
+<td>the length of the string, or -1 if the string is
+                nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">1</a>]</sup>.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em> :</span></p></td>
+<td>location to store the number of bytes in the
+                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>.
+                Even if the conversion was successful, this may be
+                less than <em class="parameter"><code>len</code></em> if there were partial characters
+                at the end of the input. If the error
+                <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
+                stored will the byte offset after the last valid
+                input sequence.
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em> :</span></p></td>
+<td>the number of bytes stored in the output buffer (not
+                including the terminating nul).
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>error</code></em> :</span></p></td>
+<td>location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> to ignore
+                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>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<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>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="GConvertError"></a><h3>enum GConvertError</h3>
+<pre class="programlisting">typedef enum
+{
+  G_CONVERT_ERROR_NO_CONVERSION,
+  G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
+  G_CONVERT_ERROR_FAILED,
+  G_CONVERT_ERROR_PARTIAL_INPUT,
+  G_CONVERT_ERROR_BAD_URI,
+  G_CONVERT_ERROR_NOT_ABSOLUTE_PATH
+} GConvertError;
+</pre>
+<p>
+Error codes returned by character set conversion routines.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<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>
+<td>Conversion between the requested character
+    sets is not supported.
+</td>
+</tr>
+<tr>
+<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>
+<td>Invalid byte sequence in conversion input.
+</td>
+</tr>
+<tr>
+<td><p><a name="G-CONVERT-ERROR-FAILED:CAPS"></a><span class="term"><code class="literal">G_CONVERT_ERROR_FAILED</code></span></p></td>
+<td>Conversion failed for some reason.
+</td>
+</tr>
+<tr>
+<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>
+<td>Partial character sequence at end of input.
+</td>
+</tr>
+<tr>
+<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>
+<td>URI is invalid.
+</td>
+</tr>
+<tr>
+<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>
+<td>Pathname is not an absolute path.
+</td>
+</tr>
+</tbody>
+</table></div>
+</div>
+<hr>
+<div class="refsect2">
+<a name="g-get-charset"></a><h3>g_get_charset ()</h3>
+<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>G_CONST_RETURN <span class="type">char</span> **charset</code></em>);</pre>
+<p>
+Obtains the character set for the <a class="link" href="glib-running.html#setlocale" title="Locale">current
+locale</a>; you might use this character set as an argument to
+<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
+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>
+are nice shortcuts, though.)
+</p>
+<p>
+On Windows the character set returned by this function is the
+so-called system default ANSI code-page. That is the character set
+used by the "narrow" versions of C library and Win32 functions that
+handle file names. It might be different from the character set
+used by the C library's current locale.
+</p>
+<p>
+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
+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>.
+</p>
+<p>
+The string returned in <em class="parameter"><code>charset</code></em> is not allocated, and should not be
+freed.
+</p>
+<div class="variablelist"><table border="0">
+<col align="left" valign="top">
+<tbody>
+<tr>
+<td><p><span class="term"><em class="parameter"><code>charset</code></em> :</span></p></td>
+<td>return location for character set name
+</td>
+</tr>
+<tr>
+<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
+<td> <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>
+</tr>
+</tbody>
+</table></div>
+</div>
+</div>
+<div class="footnotes">
+<br><hr width="100" align="left">
+<div class="footnote"><p><sup>[<a name="ftn.nul-unsafe" href="#nul-unsafe" class="para">1</a>] </sup>
+                       Note that some encodings may allow nul bytes to
+                       occur inside strings. In that case, using -1 for
+                       the <em class="parameter"><code>len</code></em> parameter is unsafe.
+                     </p></div>
+<div class="footnote"><p><sup>[<a name="ftn.streaming-state" href="#streaming-state" class="para">2</a>] </sup>
+Despite the fact that <em class="parameter"><code>byes_read</code></em> can return information about partial
+characters, the <code class="literal">g_convert_...</code> functions
+are not generally suitable for streaming. If the underlying converter
+being used maintains internal state, then this won't be preserved
+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
+<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
+for CP1255 which does not emit a base character until it knows that
+the next character is not a mark that could combine with the base
+character.)
+ </p></div>
+</div>
+</div>
+<div class="footer">
+<hr>
+          Generated by GTK-Doc V1.15.1</div>
+</body>
+</html>