<refentry id="glib-Character-Set-Conversion">
<refmeta>
<refentrytitle>Character Set Conversion</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Character Set Conversion</refname><refpurpose>convert strings between different character sets using <function><link linkend="iconv">iconv</link>()</function>.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


<link linkend="gchar">gchar</link>*      <link linkend="g-convert">g_convert</link>                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-convert-with-fallback">g_convert_with_fallback</link>         (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gchar">gchar</link> *fallback,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-convert-with-iconv">g_convert_with_iconv</link>            (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
#define     <link linkend="G-CONVERT-ERROR-CAPS">G_CONVERT_ERROR</link>
<link linkend="GIConv">GIConv</link>      <link linkend="g-iconv-open">g_iconv_open</link>                    (const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset);
<link linkend="size-t">size_t</link>      <link linkend="g-iconv">g_iconv</link>                         (<link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gchar">gchar</link> **inbuf,
                                             <link linkend="gsize">gsize</link> *inbytes_left,
                                             <link linkend="gchar">gchar</link> **outbuf,
                                             <link linkend="gsize">gsize</link> *outbytes_left);
<link linkend="gint">gint</link>        <link linkend="g-iconv-close">g_iconv_close</link>                   (<link linkend="GIConv">GIConv</link> converter);
<link linkend="gchar">gchar</link>*      <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>                (const <link linkend="gchar">gchar</link> *opsysstring,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-to-utf8">g_filename_to_utf8</link>              (const <link linkend="gchar">gchar</link> *opsysstring,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-from-utf8">g_filename_from_utf8</link>            (const <link linkend="gchar">gchar</link> *utf8string,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-from-uri">g_filename_from_uri</link>             (const char *uri,
                                             char **hostname,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-to-uri">g_filename_to_uri</link>               (const char *filename,
                                             const char *hostname,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-locale-from-utf8">g_locale_from_utf8</link>              (const <link linkend="gchar">gchar</link> *utf8string,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
enum        <link linkend="GConvertError">GConvertError</link>;

<link linkend="gboolean">gboolean</link>    <link linkend="g-get-charset">g_get_charset</link>                   (G_CONST_RETURN char **charset);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-convert">g_convert ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_convert                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string from one character set to another.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry>           the string to convert
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string
</entry></row>
<row><entry align="right"><parameter>to_codeset</parameter>&nbsp;:</entry>
<entry>    name of character set into which to convert <parameter>str</parameter>
</entry></row>
<row><entry align="right"><parameter>from_codeset</parameter>&nbsp;:</entry>
<entry>  character set of <parameter>str</parameter>.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>         location to store the error occuring, or <literal>NULL</literal> to ignore
                errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <link linkend="g-free">g_free</link>(). Otherwise <literal>NULL</literal> and <parameter>error</parameter> will be set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-convert-with-fallback">g_convert_with_fallback ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_convert_with_fallback         (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gchar">gchar</link> *fallback,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
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 <parameter>fallback</parameter> will be honored. Some
systems may do a approximate conversion from <parameter>from_codeset</parameter>
to <parameter>to_codeset</parameter> in their <function><link linkend="iconv">iconv</link>()</function> functions, 
in which case GLib will simply return that approximate conversion.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry>          the string to convert
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>          the length of the string
</entry></row>
<row><entry align="right"><parameter>to_codeset</parameter>&nbsp;:</entry>
<entry>   name of character set into which to convert <parameter>str</parameter>
</entry></row>
<row><entry align="right"><parameter>from_codeset</parameter>&nbsp;:</entry>
<entry> character set of <parameter>str</parameter>.
</entry></row>
<row><entry align="right"><parameter>fallback</parameter>&nbsp;:</entry>
<entry>     UTF-8 string to use in place of character not
               present in the target encoding. (This must be
               in the target encoding), if <literal>NULL</literal>, characters
               not in the target encoding will be represented
               as Unicode escapes \x{XXXX} or \x{XXXXXX}.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>   location to store the number of bytes in the
               input string that were successfully converted, or <literal>NULL</literal>.
               Even if the conversion was successful, this may be 
               less than <parameter>len</parameter> if there were partial characters
               at the end of the input.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
               including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>        location to store the error occuring, or <literal>NULL</literal> to ignore
               errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <link linkend="g-free">g_free</link>(). Otherwise <literal>NULL</literal> and <parameter>error</parameter> will be set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-convert-with-iconv">g_convert_with_iconv ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_convert_with_iconv            (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string from one character set to another.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry>           the string to convert
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string
</entry></row>
<row><entry align="right"><parameter>converter</parameter>&nbsp;:</entry>
<entry>     conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>()
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>         location to store the error occuring, or <literal>NULL</literal> to ignore
                errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <link linkend="g-free">g_free</link>(). Otherwise <literal>NULL</literal> and <parameter>error</parameter> will be set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-CONVERT-ERROR-CAPS">G_CONVERT_ERROR</title>
<programlisting>#define G_CONVERT_ERROR g_convert_error_quark()
</programlisting>
<para>
Error domain for character set conversions. Errors in this domain will
be from the <link linkend="GConvertError">GConvertError</link> enumeration. See <link linkend="GError">GError</link> for information on 
error domains.
</para></refsect2>
<refsect2>
<title><anchor id="g-iconv-open">g_iconv_open ()</title>
<programlisting><link linkend="GIConv">GIConv</link>      g_iconv_open                    (const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset);</programlisting>
<para>
Same as the standard UNIX routine <function><link linkend="iconv-open">iconv_open</link>()</function>, but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.
</para>
<para>
GLib provides <link linkend="g-convert">g_convert</link>() and <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() which are likely
more convenient than the raw iconv wrappers.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>to_codeset</parameter>&nbsp;:</entry>
<entry> destination codeset
</entry></row>
<row><entry align="right"><parameter>from_codeset</parameter>&nbsp;:</entry>
<entry> source codeset
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a "conversion descriptor"
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-iconv">g_iconv ()</title>
<programlisting><link linkend="size-t">size_t</link>      g_iconv                         (<link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gchar">gchar</link> **inbuf,
                                             <link linkend="gsize">gsize</link> *inbytes_left,
                                             <link linkend="gchar">gchar</link> **outbuf,
                                             <link linkend="gsize">gsize</link> *outbytes_left);</programlisting>
<para>
Same as the standard UNIX routine <function><link linkend="iconv">iconv</link>()</function>, but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.
</para>
<para>
GLib provides <link linkend="g-convert">g_convert</link>() and <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() which are likely
more convenient than the raw iconv wrappers.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>converter</parameter>&nbsp;:</entry>
<entry> conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>()
</entry></row>
<row><entry align="right"><parameter>inbuf</parameter>&nbsp;:</entry>
<entry> bytes to convert
</entry></row>
<row><entry align="right"><parameter>inbytes_left</parameter>&nbsp;:</entry>
<entry> inout parameter, bytes remaining to convert in <parameter>inbuf</parameter>
</entry></row>
<row><entry align="right"><parameter>outbuf</parameter>&nbsp;:</entry>
<entry> converted output bytes
</entry></row>
<row><entry align="right"><parameter>outbytes_left</parameter>&nbsp;:</entry>
<entry> inout parameter, bytes available to fill in <parameter>outbuf</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> count of non-reversible conversions, or -1 on error
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-iconv-close">g_iconv_close ()</title>
<programlisting><link linkend="gint">gint</link>        g_iconv_close                   (<link linkend="GIConv">GIConv</link> converter);</programlisting>
<para>
Same as the standard UNIX routine <function><link linkend="iconv-close">iconv_close</link>()</function>, but
may be implemented via libiconv on UNIX flavors that lack
a native implementation. Should be called to clean up
the conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>() when
you are done converting things.
</para>
<para>
GLib provides <link linkend="g-convert">g_convert</link>() and <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() which are likely
more convenient than the raw iconv wrappers.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>converter</parameter>&nbsp;:</entry>
<entry> a conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>()
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> -1 on error, 0 on success
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-locale-to-utf8">g_locale_to_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_locale_to_utf8                (const <link linkend="gchar">gchar</link> *opsysstring,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
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 current locale into a UTF-8 string.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>opsysstring</parameter>&nbsp;:</entry>
<entry>   a string in the encoding of the current locale
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string, or -1 if the string is
                nul-terminated.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>         location to store the error occuring, or <literal>NULL</literal> to ignore
                errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The converted string, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-to-utf8">g_filename_to_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_to_utf8              (const <link linkend="gchar">gchar</link> *opsysstring,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string which is in the encoding used for filenames
into a UTF-8 string.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>opsysstring</parameter>&nbsp;:</entry>
<entry>   a string in the encoding for filenames
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string, or -1 if the string is
                nul-terminated.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>         location to store the error occuring, or <literal>NULL</literal> to ignore
                errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The converted string, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-from-utf8">g_filename_from_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_from_utf8            (const <link linkend="gchar">gchar</link> *utf8string,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string from UTF-8 to the encoding used for filenames.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>utf8string</parameter>&nbsp;:</entry>
<entry>    a UTF-8 encoded string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string, or -1 if the string is
                nul-terminated.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>         location to store the error occuring, or <literal>NULL</literal> to ignore
                errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The converted string, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-from-uri">g_filename_from_uri ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_from_uri             (const char *uri,
                                             char **hostname,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts an escaped UTF-8 encoded URI to a local filename in the
encoding used for filenames.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>uri</parameter>&nbsp;:</entry>
<entry> a uri describing a filename (escaped, encoded in UTF-8).
</entry></row>
<row><entry align="right"><parameter>hostname</parameter>&nbsp;:</entry>
<entry> Location to store hostname for the URI, or <literal>NULL</literal>.
           If there is no hostname in the URI, <literal>NULL</literal> will be
           stored in this location.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated string holding the resulting
              filename, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-to-uri">g_filename_to_uri ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_to_uri               (const char *filename,
                                             const char *hostname,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts an absolute filename to an escaped UTF-8 encoded URI.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> an absolute filename specified in the encoding
           used for filenames by the operating system.
</entry></row>
<row><entry align="right"><parameter>hostname</parameter>&nbsp;:</entry>
<entry> A UTF-8 encoded hostname, or <literal>NULL</literal> for none.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly-allocated string holding the resulting
              URI, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-locale-from-utf8">g_locale_from_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_locale_from_utf8              (const <link linkend="gchar">gchar</link> *utf8string,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
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 current locale.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>utf8string</parameter>&nbsp;:</entry>
<entry>    a UTF-8 encoded string 
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string, or -1 if the string is
                nul-terminated.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry>         location to store the error occuring, or <literal>NULL</literal> to ignore
                errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The converted string, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GConvertError">enum GConvertError</title>
<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;
</programlisting>
<para>
Error codes returned by character set conversion routines.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_CONVERT_ERROR_NO_CONVERSION</literal></entry>
<entry>Conversion between the requested character sets
is not supported.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</literal></entry>
<entry>Invalid byte sequence in conversion input.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_FAILED</literal></entry>
<entry>Conversion failed for some reason.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_PARTIAL_INPUT</literal></entry>
<entry>Partial character sequence at end of input.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_BAD_URI</literal></entry>
<entry>URI is invalid.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_NOT_ABSOLUTE_PATH</literal></entry>
<entry>Pathname is not an absolute path.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-charset">g_get_charset ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_get_charset                   (G_CONST_RETURN char **charset);</programlisting>
<para>
Obtains the character set for the current locale; you might use
this character set as an argument to <link linkend="g-convert">g_convert</link>(), to convert from
the current locale's encoding to some other encoding. (Frequently
<link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() and <link linkend="g-locale-from-utf8">g_locale_from_utf8</link>() are nice shortcuts,
though.)
</para>
<para>
The return value is <literal>TRUE</literal> if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling <link linkend="g-convert">g_convert</link>().
</para>
<para>
The string returned in <parameter>charset</parameter> is not allocated, and should not be
freed.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>charset</parameter>&nbsp;:</entry>
<entry> return location for character set name
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the returned charset is UTF-8
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>
