<part>
  <title>GIO Overview</title>

  <chapter> 
    <title>Introduction</title>

  <para>
    GIO is striving to provide a modern, easy-to-use VFS API that sits
    at the right level in the library stack. The goal is to overcome the
    shortcomings of GnomeVFS and provide an API that is so good that
    developers prefer it over raw POSIX calls. Among other things
    that means using GObject. It also means not cloning the POSIX 
    API, but providing higher-level, document-centric interfaces.
  </para>

  <para>
    The abstract file system model of GIO consists of a number of
    interfaces and base classes for I/O and files:
    <variablelist>
       <varlistentry>
         <term>GFile</term>
         <listitem><para>reference to a file</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GFileInfo</term>
         <listitem><para>information about a file or filesystem</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GFileEnumerator</term>
         <listitem><para>list files in directories</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GDrive</term>
         <listitem><para>represents a drive</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GVolume</term>
         <listitem><para>represents a file system in an abstract way</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GMount</term>
         <listitem><para>represents a mounted file system</para></listitem>
       </varlistentry>
    </variablelist>
    Then there is a number of stream classes, similar to the input and
    output stream hierarchies that can be found in frameworks like Java:
    <variablelist>
       <varlistentry>
         <term>GInputStream</term>
         <listitem><para>read data</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GOutputStream</term>
         <listitem><para>write data</para></listitem>
       </varlistentry>
       <varlistentry>
         <term>GSeekable</term>
         <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
       </varlistentry>
    </variablelist>
    There are interfaces related to applications and the types
    of files they handle:
    <variablelist>
       <varlistentry>
          <term>GAppInfo</term>
          <listitem><para>information about an installed application</para></listitem>
       </varlistentry>
       <varlistentry>
          <term>GIcon</term>
          <listitem><para>abstract type for file and application icons</para></listitem>
       </varlistentry>
    </variablelist>
    Beyond these, GIO provides facilities for file monitoring,
    asynchronous I/O and filename completion. In addition to the 
    interfaces, GIO provides implementations for the local case. 
    Implementations for various network file systems are provided 
    by the GVFS package as loadable modules.
  </para>

  <para>
    Other design choices which consciously break with the GnomeVFS
    design are to move backends out-of-process, which minimizes the
    dependency bloat and makes the whole system more robust. The backends
    are not included in GIO, but in the separate GVFS package. The GVFS 
    package also contains the GVFS daemon, which spawn further mount 
    daemons for each individual connection.
  </para>

  <figure id="gvfs-overview">
    <title>GIO in the GTK+ library stack</title>
    <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
  </figure>

  <para>
    The GIO model of I/O is stateful: if an application establishes e.g. 
    a SFTP connection to a server, it becomes available to all applications 
    in the session; the user does not have to enter his password over 
    and over again.
  </para>
  <para>
    One of the big advantages of putting the VFS in the GLib layer 
    is that GTK+ can directly use it, e.g. in the filechooser.
  </para>
  </chapter>

  <chapter>
    <title>Compiling GIO applications</title>

    <para>
      GIO comes with a <filename>gio-2.0.pc</filename> file that you
      should use together with <literal>pkg-config</literal> to obtain
      the necessary information about header files and libraries. See
      the <literal>pkg-config</literal> man page or the GLib documentation 
      for more information on how to use <literal>pkg-config</literal> 
      to compile your application.
    </para>

    <para>
      If you are using GIO on UNIX-like systems, you may want to use
      UNIX-specific GIO interfaces such as #GUnixInputStream, 
      #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo. 
      To do so, use the <filename>gio-unix-2.0.pc</filename> file 
      instead of <filename>gio-2.0.pc</filename>
    </para>
  </chapter>

  <chapter>
    <title>Running GIO applications</title>

    <para>
      GIO inspects a few of environment variables in addition to the
      ones used by GLib.
    </para>

    <formalpara>
      <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>

      <para>
        GIO uses these environment variables to locate MIME information. 
        For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
        and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
      </para>
    </formalpara>

    <para>
      The following environment variables are only useful for debugging
      GIO itself or modules that it loads. They should not be set in a
      production environment.
    </para>
    <formalpara>
      <title><envar>GIO_USE_VFS</envar></title>

      <para>
        This environment variable can be set to the name of a #GVfs 
        implementation to override the default for debugging purposes.
        The #GVfs implementation for local files that is included in GIO 
        has the name "local", the implementation in the gvfs module has 
        the name "gvfs". 
      </para>
    </formalpara>

    <formalpara>
      <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
        
      <para>
        This variable can be set to the name of a #GVolumeMonitor 
        implementation to override the default for debugging purposes.
        The #GVolumeMonitor implementation for local files that is included
        in GIO has the name "unix", the hal-based implementation in the
        gvfs module has the name "hal".
      </para>
    </formalpara>

    <formalpara>
      <title><envar>GVFS_INOTIFY_DIAG</envar></title>

      <para>
        When this environment variable is set and GIO has been built
        with inotify support, a dump of diagnostic inotify information 
        will be written every 20 seconds to a file named
        <filename>/tmp/gvfsdid.<replaceable>pid</replaceable></filename>.
      </para>
    </formalpara>

  </chapter>

</part>
