docs/reference/glib/tmpl/conversions.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Character Set Conversion
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 convert strings between different character sets using <function>iconv()</function>.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 </para>
  11
  12     <refsect2 id="file-name-encodings">
  13       <title>File Name Encodings</title>
  14
  15       <para>
  16         Historically, Unix has not had a defined encoding for file
  17         names:  a file name is valid as long as it does not have path
  18         separators in it ("/").  However, displaying file names may
  19         require conversion:  from the character set in which they were
  20         created, to the character set in which the application
  21         operates.  Consider the Spanish file name
  22         "<filename>Presentaci&oacute;n.sxi</filename>".  If the
  23         application which created it uses ISO-8859-1 for its encoding,
  24         then the actual file name on disk would look like this:
  25       </para>
  26
  27       <programlisting id="filename-iso8859-1">
  28 Character:  P  r  e  s  e  n  t  a  c  i  &oacute;  n  .  s  x  i
  29 Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
  30       </programlisting>
  31
  32       <para>
  33         However, if the application use UTF-8, the actual file name on
  34         disk would look like this:
  35       </para>
  36
  37       <programlisting id="filename-utf-8">
  38 Character:  P  r  e  s  e  n  t  a  c  i  &oacute;     n  .  s  x  i
  39 Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
  40       </programlisting>
  41
  42       <para>
  43         Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
  44         that use Glib do the same thing.  If you get a file name from
  45         the file system, for example, from
  46         <function>readdir(3)</function> or from <link
  47         linkend="g_dir_read_name"><function>g_dir_read_name()</function></link>,
  48         and you wish to display the file name to the user, you
  49         <emphasis>will</emphasis> need to convert it into UTF-8.  The
  50         opposite case is when the user types the name of a file he
  51         wishes to save:  the toolkit will give you that string in
  52         UTF-8 encoding, and you will need to convert it to the
  53         character set used for file names before you can create the
  54         file with <function>open(2)</function> or
  55         <function>fopen(3)</function>.
  56       </para>
  57
  58       <para>
  59         By default, Glib assumes that file names on disk are in UTF-8
  60         encoding.  This is a valid assumption for file systems which
  61         were created relatively recently:  most applications use UTF-8
  62         encoding for their strings, and that is also what they use for
  63         the file names they create.  However, older file systems may
  64         still contain file names created in "older" encodings, such as
  65         ISO-8859-1.  In this case, for compatibility reasons, you may
  66         want to instruct Glib to use that particular encoding for file
  67         names rather than UTF-8.  You can do this by specifying the
  68         encoding for file names in the <link
  69         linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link>
  70         environment variable.  For example, if your installation uses
  71         ISO-8859-1 for file names, you can put this in your
  72         <filename>~/.profile</filename>:
  73       </para>
  74
  75       <programlisting>
  76 export G_FILENAME_ENCODING=ISO-8859-1
  77       </programlisting>
  78
  79       <para>
  80         Glib provides the functions <link
  81         linkend="g_filename_to_utf8"><function>g_filename_to_utf8()</function></link>
  82         and <link
  83         linkend="g_filename_from_utf8"><function>g_filename_from_utf8()</function></link>
  84         to perform the necessary conversions.  These functions convert
  85         file names from the encoding specified in
  86         <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa.
  87         <xref linkend="file-name-encodings-diagram"/> illustrates how
  88         these functions are used to convert between UTF-8 and the
  89         encoding for file names in the file system.
  90       </para>
  91
  92       <figure id="file-name-encodings-diagram">
  93         <title>Conversion between File Name Encodings</title>
  94         <graphic fileref="file-name-encodings.png" format="PNG"/>
  95       </figure>
  96
  97       <refsect3 id="file-name-encodings-checklist">
  98         <title>Checklist for Application Writers</title>
  99
 100         <para>
 101           This section is a practical summary of the detailed
 102           description above.  You can use this as a checklist of
 103           things to do to make sure your applications process file
 104           name encodings correctly.
 105         </para>
 106
 107         <orderedlist>
 108           <listitem>
 109             <para>
 110               If you get a file name from the file system from a
 111               function such as <function>readdir(3)</function> or
 112               <function>gtk_file_chooser_get_filename()</function>,
 113               you do not need to do any conversion to pass that
 114               file name to functions like <function>open(2)</function>,
 115               <function>rename(2)</function>, or
 116               <function>fopen(3)</function> &mdash; those are "raw"
 117               file names which the file system understands.
 118             </para>
 119           </listitem>
 120
 121           <listitem>
 122             <para>
 123               If you need to display a file name, convert it to UTF-8
 124               first by using <link
 125               linkend="g_filename_to_utf8"><function>g_filename_to_utf8()</function></link>.
 126               If conversion fails, display a string like
 127               "<literal>Unknown file name</literal>".  <emphasis>Do
 128               not</emphasis> convert this string back into the
 129               encoding used for file names if you wish to pass it to
 130               the file system; use the original file name instead.
 131               For example, the document window of a word processor
 132               could display "Unknown file name" in its title bar but
 133               still let the user save the file, as it would keep the
 134               raw file name internally.  This can happen if the user
 135               has not set the <envar>G_FILENAME_ENCODING</envar>
 136               environment variable even though he has files whose
 137               names are not encoded in UTF-8.
 138             </para>
 139           </listitem>
 140
 141           <listitem>
 142             <para>
 143               If your user interface lets the user type a file name
 144               for saving or renaming, convert it to the encoding used
 145               for file names in the file system by using <link
 146               linkend="g_filename_from_utf8"><function>g_filename_from_utf8()</function></link>.
 147               Pass the converted file name to functions like
 148               <function>fopen(3)</function>.  If conversion fails, ask
 149               the user to enter a different file name.  This can
 150               happen if the user types Japanese characters when
 151               <envar>G_FILENAME_ENCODING</envar> is set to
 152               <literal>ISO-8859-1</literal>, for example.
 153             </para>
 154           </listitem>
 155         </orderedlist>
 156       </refsect3>
 157     </refsect2>
 158
 159 <!-- ##### SECTION See_Also ##### -->
 160 <para>
 161
 162 </para>
 163
 164 <!-- ##### FUNCTION g_convert ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @str:
 170 @len:
 171 @to_codeset:
 172 @from_codeset:
 173 @bytes_read:
 174 @bytes_written:
 175 @error:
 176 @Returns:
 177
 178
 179 <!-- ##### FUNCTION g_convert_with_fallback ##### -->
 180 <para>
 181
 182 </para>
 183
 184 @str:
 185 @len:
 186 @to_codeset:
 187 @from_codeset:
 188 @fallback:
 189 @bytes_read:
 190 @bytes_written:
 191 @error:
 192 @Returns:
 193
 194
 195 <!-- ##### STRUCT GIConv ##### -->
 196 <para>
 197 The <structname>GIConv</structname> struct wraps an
 198 <function>iconv()</function> conversion descriptor. It contains private data
 199 and should only be accessed using the following functions.
 200 </para>
 201
 202
 203 <!-- ##### FUNCTION g_convert_with_iconv ##### -->
 204 <para>
 205
 206 </para>
 207
 208 @str:
 209 @len:
 210 @converter:
 211 @bytes_read:
 212 @bytes_written:
 213 @error:
 214 @Returns:
 215
 216
 217 <!-- ##### MACRO G_CONVERT_ERROR ##### -->
 218 <para>
 219 Error domain for character set conversions. Errors in this domain will
 220 be from the #GConvertError enumeration. See #GError for information on
 221 error domains.
 222 </para>
 223
 224
 225
 226 <!-- ##### FUNCTION g_iconv_open ##### -->
 227 <para>
 228
 229 </para>
 230
 231 @to_codeset:
 232 @from_codeset:
 233 @Returns:
 234
 235
 236 <!-- ##### FUNCTION g_iconv ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @converter:
 242 @inbuf:
 243 @inbytes_left:
 244 @outbuf:
 245 @outbytes_left:
 246 @Returns:
 247
 248
 249 <!-- ##### FUNCTION g_iconv_close ##### -->
 250 <para>
 251
 252 </para>
 253
 254 @converter:
 255 @Returns:
 256
 257
 258 <!-- ##### FUNCTION g_locale_to_utf8 ##### -->
 259 <para>
 260
 261 </para>
 262
 263 @opsysstring:
 264 @len:
 265 @bytes_read:
 266 @bytes_written:
 267 @error:
 268 @Returns:
 269
 270
 271 <!-- ##### FUNCTION g_filename_to_utf8 ##### -->
 272 <para>
 273
 274 </para>
 275
 276 @opsysstring:
 277 @len:
 278 @bytes_read:
 279 @bytes_written:
 280 @error:
 281 @Returns:
 282
 283
 284 <!-- ##### FUNCTION g_filename_from_utf8 ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @utf8string:
 290 @len:
 291 @bytes_read:
 292 @bytes_written:
 293 @error:
 294 @Returns:
 295
 296
 297 <!-- ##### FUNCTION g_filename_from_uri ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @uri:
 303 @hostname:
 304 @error:
 305 @Returns:
 306
 307
 308 <!-- ##### FUNCTION g_filename_to_uri ##### -->
 309 <para>
 310
 311 </para>
 312
 313 @filename:
 314 @hostname:
 315 @error:
 316 @Returns:
 317
 318
 319 <!-- ##### FUNCTION g_locale_from_utf8 ##### -->
 320 <para>
 321
 322 </para>
 323
 324 @utf8string:
 325 @len:
 326 @bytes_read:
 327 @bytes_written:
 328 @error:
 329 @Returns:
 330
 331
 332 <!-- ##### ENUM GConvertError ##### -->
 333 <para>
 334 Error codes returned by character set conversion routines.
 335 </para>
 336
 337 @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets
 338 is not supported.
 339 @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input.
 340 @G_CONVERT_ERROR_FAILED: Conversion failed for some reason.
 341 @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input.
 342 @G_CONVERT_ERROR_BAD_URI: URI is invalid.
 343 @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path.
 344
 345 <!-- ##### FUNCTION g_get_charset ##### -->
 346 <para>
 347
 348 </para>
 349
 350 @charset:
 351 @Returns:
 352
 353
 354 <!--
 355 Local variables:
 356 mode: sgml
 357 sgml-parent-document: ("../glib-docs.sgml" "book" "refentry")
 358 End:
 359 -->
 360
 361