</para>
+ <refsect2 id="file-name-encodings">
+ <title>File Name Encodings</title>
+
+ <para>
+ 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
+ "<filename>Presentación.sxi</filename>". If the
+ application which created it uses ISO-8859-1 for its encoding,
+ then the actual file name on disk would look like this:
+ </para>
+
+ <programlisting id="filename-iso8859-1">
+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
+ </programlisting>
+
+ <para>
+ However, if the application use UTF-8, the actual file name on
+ disk would look like this:
+ </para>
+
+ <programlisting id="filename-utf-8">
+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
+ </programlisting>
+
+ <para>
+ 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
+ <function>readdir(3)</function> or from <link
+ linkend="g_dir_read_name"><function>g_dir_read_name()</function></link>,
+ and you wish to display the file name to the user, you
+ <emphasis>will</emphasis> 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 <function>open(2)</function> or
+ <function>fopen(3)</function>.
+ </para>
+
+ <para>
+ 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 <link
+ linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link>
+ environment variable. For example, if your installation uses
+ ISO-8859-1 for file names, you can put this in your
+ <filename>~/.profile</filename>:
+ </para>
+
+ <programlisting>
+export G_FILENAME_ENCODING=ISO-8859-1
+ </programlisting>
+
+ <para>
+ Glib provides the functions <link
+ linkend="g_filename_to_utf8"><function>g_filename_to_utf8()</function></link>
+ and <link
+ linkend="g_filename_from_utf8"><function>g_filename_from_utf8()</function></link>
+ to perform the necessary conversions. These functions convert
+ file names from the encoding specified in
+ <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa.
+ <xref linkend="file-name-encodings-diagram"/> illustrates how
+ these functions are used to convert between UTF-8 and the
+ encoding for file names in the file system.
+ </para>
+
+ <figure id="file-name-encodings-diagram">
+ <title>Conversion between File Name Encodings</title>
+ <graphic fileref="file-name-encodings.png" format="PNG"/>
+ </figure>
+
+ <refsect3 id="file-name-encodings-checklist">
+ <title>Checklist for Application Writers</title>
+
+ <para>
+ 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.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ If you get a file name from the file system from a
+ function such as <function>readdir(3)</function> or
+ <function>gtk_file_chooser_get_filename()</function>,
+ you do not need to do any conversion to pass that
+ file name to functions like <function>open(2)</function>,
+ <function>rename(2)</function>, or
+ <function>fopen(3)</function> — those are "raw"
+ file names which the file system understands.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ If you need to display a file name, convert it to UTF-8
+ first by using <link
+ linkend="g_filename_to_utf8"><function>g_filename_to_utf8()</function></link>.
+ If conversion fails, display a string like
+ "<literal>Unknown file name</literal>". <emphasis>Do
+ not</emphasis> 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 <envar>G_FILENAME_ENCODING</envar>
+ environment variable even though he has files whose
+ names are not encoded in UTF-8.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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 <link
+ linkend="g_filename_from_utf8"><function>g_filename_from_utf8()</function></link>.
+ Pass the converted file name to functions like
+ <function>fopen(3)</function>. If conversion fails, ask
+ the user to enter a different file name. This can
+ happen if the user types Japanese characters when
+ <envar>G_FILENAME_ENCODING</envar> is set to
+ <literal>ISO-8859-1</literal>, for example.
+ </para>
+ </listitem>
+ </orderedlist>
+ </refsect3>
+ </refsect2>
+
<!-- ##### SECTION See_Also ##### -->
<para>
@Returns:
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../glib-docs.sgml" "book" "refentry")
+End:
+-->
+
+
projects / platform / upstream / glib.git / commitdiff
