| <!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.14 (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" title="Character Set Conversion"> |
| <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 using <code class="function">iconv()</code></p> |
| </td> |
| <td valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsynopsisdiv" title="Synopsis"> |
| <a name="glib-Character-Set-Conversion.synopsis"></a><h2>Synopsis</h2> |
| <pre class="synopsis"> |
| #include <glib.h> |
| |
| <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#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * <a class="link" href="glib-Character-Set-Conversion.html#g-filename-from-uri" title="g_filename_from_uri ()">g_filename_from_uri</a> (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *uri</code></em>, |
| <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **hostname</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-uri" title="g_filename_to_uri ()">g_filename_to_uri</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>, |
| <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *hostname</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" title="Description"> |
| <a name="glib-Character-Set-Conversion.description"></a><h2>Description</h2> |
| <p> |
| </p> |
| <div class="refsect2" title="File Name Encodings"> |
| <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, |
| then the actual file name on disk would look like this: |
| </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 |
| <code class="function">readdir(3)</code> or from <code class="function"><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></code>, |
| 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 <code class="function">open(2)</code> or |
| <code class="function">fopen(3)</code>. |
| </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 <code class="function"><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></code> |
| and <code class="function"><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></code> |
| 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" title="Checklist for Application Writers"> |
| <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 <code class="function">readdir(3)</code> or |
| <code class="function"><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></code>, |
| you do not need to do any conversion to pass that |
| file name to functions like <code class="function">open(2)</code>, |
| <code class="function">rename(2)</code>, or |
| <code class="function">fopen(3)</code> — 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 <code class="function"><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></code>. |
| 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 <code class="function"><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></code>. |
| Pass the converted file name to functions like |
| <code class="function">fopen(3)</code>. 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> |
| </div> |
| <div class="refsect1" title="Details"> |
| <a name="glib-Character-Set-Conversion.details"></a><h2>Details</h2> |
| <div class="refsect2" title="g_convert ()"> |
| <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" title="g_convert_with_fallback ()"> |
| <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" title="GIConv"> |
| <a name="GIConv"></a><h3>GIConv</h3> |
| <pre class="programlisting">typedef struct _GIConv GIConv;</pre> |
| <p> |
| The <span class="structname">GIConv</span> struct wraps an |
| <code class="function"><code class="function">iconv()</code></code> conversion descriptor. It contains private data |
| and should only be accessed using the following functions. |
| </p> |
| </div> |
| <hr> |
| <div class="refsect2" title="g_convert_with_iconv ()"> |
| <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" title="G_CONVERT_ERROR"> |
| <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" title="g_iconv_open ()"> |
| <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" title="g_iconv ()"> |
| <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" title="g_iconv_close ()"> |
| <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" title="g_locale_to_utf8 ()"> |
| <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" title="g_filename_to_utf8 ()"> |
| <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" title="g_filename_from_utf8 ()"> |
| <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" title="g_filename_from_uri ()"> |
| <a name="g-filename-from-uri"></a><h3>g_filename_from_uri ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * g_filename_from_uri (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *uri</code></em>, |
| <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> **hostname</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 an escaped ASCII-encoded URI to a local filename in the |
| encoding used for filenames. |
| </p> |
| <div class="variablelist"><table border="0"> |
| <col align="left" valign="top"> |
| <tbody> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>uri</code></em> :</span></p></td> |
| <td>a uri describing a filename (escaped, encoded in ASCII). |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td> |
| <td>Location to store hostname for the URI, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>. |
| If there is no hostname in the URI, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> will be |
| stored in this location. |
| </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> a newly-allocated string holding the resulting |
| filename, 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" title="g_filename_to_uri ()"> |
| <a name="g-filename-to-uri"></a><h3>g_filename_to_uri ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * g_filename_to_uri (<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>, |
| <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *hostname</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 an absolute filename to an escaped ASCII-encoded URI, with the path |
| component following Section 3.3. of RFC 2396. |
| </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 filename specified in the GLib file name encoding, |
| which is the on-disk file name bytes on Unix, and UTF-8 on |
| Windows |
| </td> |
| </tr> |
| <tr> |
| <td><p><span class="term"><em class="parameter"><code>hostname</code></em> :</span></p></td> |
| <td>A UTF-8 encoded hostname, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> for none. |
| </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> a newly-allocated string holding the resulting |
| URI, 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" title="g_get_filename_charsets ()"> |
| <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" title="g_filename_display_name ()"> |
| <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" title="g_filename_display_basename ()"> |
| <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" title="g_locale_from_utf8 ()"> |
| <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" title="enum GConvertError"> |
| <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" title="g_get_charset ()"> |
| <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.14</div> |
| </body> |
| </html> |