# GIO Overview

## Introduction

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.

The abstract file system model of GIO consists of a number of interfaces and base classes for I/O and files:

GFile

  reference to a file

GFileInfo

  information about a file or filesystem

GFileEnumerator

  list files in directories

GDrive

  represents a drive

GVolume

  represents a file system in an abstract way

GMount

  represents a mounted file system

Then there is a number of stream classes, similar to the input and output stream hierarchies that can be found in frameworks like Java:

GInputStream

  read data

GOutputStream

  write data

GIOStream

  read and write data

GSeekable

  interface optionally implemented by streams to support seeking

There are interfaces related to applications and the types of files they handle:

GAppInfo

  information about an installed application

GIcon

  abstract type for file and application icons

There is a framework for storing and retrieving application settings:

GSettings

  stores and retrieves application settings

There is support for network programming, including name resolution, lowlevel socket APIs and highlevel client and server helper classes:

GSocket

  lowlevel platform independent socket object

GResolver

  asynchronous and cancellable DNS resolver

GSocketClient

  high-level network client helper

GSocketService

  high-level network server helper

GSocketConnection

  network connection stream

There is support for connecting to D-Bus, sending and receiving messages, owning and watching bus names, and making objects available on the bus:

GDBusConnection

  a D-Bus connection

GDBusMethodInvocation

  for handling remove calls

GDBusServer

  helper for accepting connections

GDBusProxy

  proxy to access D-Bus interfaces on a remote object

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.

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.

### GIO in the GTK+ library stack

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.

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.

## Compiling GIO applications

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

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 `gio-unix-2.0.pc` file instead of `gio-2.0.pc`

Since GIO is based on GObject, you need to call g_type_init() before you can use any GIO functions. If your application uses GTK+, this is already taken care of by gtk_init().

## Running GIO applications

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

### `XDG_DATA_HOME`, `XDG_DATA_DIRS`

GIO uses these environment variables to locate MIME information. For more information, see the Shared MIME-info Database and the Base Directory Specification.

### `GVFS_DISABLE_FUSE`

This variable can be set to keep #Gvfs from starting the fuse backend, which may be unwanted or unnecessary in certain situations.

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.

### `GIO_USE_VFS`

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".

### `GIO_USE_VOLUME_MONITOR`

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".

### `GIO_USE_TLS`

This variable can be set to the name of a #GTlsBackend implementation to override the default for debugging purposes. GIO does not include a #GTlsBackend implementation, the gnutls-based implementation in the glib-networking module has the name "gnutls".

### `GVFS_INOTIFY_DIAG`

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 `/tmp/gvfsdid.pid`.

### `GIO_EXTRA_MODULES`

When this environment variable is set to a path, or a set of paths separated by a colon, GIO will attempt to load modules from within the path.

### `GSETTINGS_BACKEND`

This variable can be set to the name of a #GSettingsBackend implementation to override the default for debugging purposes. The memory-based implementation that is included in GIO has the name "memory", the one in dconf has the name "dconf-settings".

### `GSETTINGS_SCHEMA_DIR`

This variable can be set to the name of a directory that is considered in addition to the `glib-2.0/schemas` subdirectories of the XDG system data dirs when looking for compiled schemas for #GSettings.

### `DBUS_SYSTEM_BUS_ADDRESS`

This variable is consulted to find the address of the D-Bus system bus. For the format of D-Bus addresses, see the D-Bus specification.

Setting this variable overrides platform-specific ways of determining the system bus address.

### `DBUS_SESSION_BUS_ADDRESS`

This variable is consulted to find the address of the D-Bus session bus.

Setting this variable overrides platform-specific ways of determining the session bus address.

### `DBUS_STARTER_BUS_TYPE`

This variable is consulted to find out the 'starter' bus for an application that has been started via D-Bus activation. The possible values are 'system' or 'session'.

### `G_DBUS_DEBUG`

This variable can be set to a list of debug options, which cause GLib to print out different types of debugging information when using the D-Bus routines.

transport

  Show IO activity (e.g. reads and writes)

message

  Show all sent and received D-Bus messages

payload

  Show payload for all sent and received D-Bus messages (implies message)

call

  Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage

signal

  Show when a D-Bus signal is received

incoming

  Show when an incoming D-Bus method call is received

return

  Show when a reply is returned via the #GDBusMethodInvocation API

emission

  Trace g_dbus_connection_emit_signal() API usage

authentication

  Show information about connection authentication

address

  Show information about D-Bus address lookups and autolaunching

The special value `all` can be used to turn on all debug options. The special value `help` can be used to print a list of supported options to standard output.

### `G_DBUS_COOKIE_SHA1_KEYRING_DIR`

Can be used to override the directory used to store the keyring used in the `DBUS_COOKIE_SHA1` authentication mechanism. Normally the directory used is `.dbus-keyrings` in the user's home directory.

### `G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION`

If set, the permissions of the directory used to store the keyring used in the `DBUS_COOKIE_SHA1` authentication mechanism won't be checked. Normally the directory must be readable only by the user.

## Extending GIO

A lot of the functionality that is accessible through GIO is implemented in loadable modules, and modules provide a convenient way to extend GIO. In addition to the #GIOModule API which supports writing such modules, GIO has a mechanism to define extension points, and register implementations thereof, see #GIOExtensionPoint.

The following extension points are currently defined by GIO:

### G_VFS_EXTENSION_POINT_NAME

Allows to override the functionality of the #GVfs class. Implementations of this extension point must be derived from #GVfs. GIO uses the implementation with the highest priority that is active, see g_vfs_is_active().

GIO implements this extension point for local files, gvfs contains an implementation that supports all the backends in gvfs.

### G_VOLUME_MONITOR_EXTENSION_POINT_NAME

Allows to add more volume monitors. Implementations of this extension point must be derived from #GVolumeMonitor. GIO uses all registered extensions.

gvfs contains an implementation that works together with the #GVfs implementation in gvfs.

### G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME

Allows to override the 'native' volume monitor. Implementations of this extension point must be derived from #GNativeVolumeMonitor. GIO uses the implementation with the highest priority that is supported, as determined by the is_supported() vfunc in #GVolumeMonitorClass.

GIO implements this extension point for local mounts, gvfs contains a hal-based implementation.

### G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME

Allows to override the file monitor implementation for local files. Implementations of this extension point must be derived from #GLocalFileMonitor. GIO uses the implementation with the highest priority that is supported, as determined by the is_supported() vfunc in #GLocalFileMonitorClass.

GIO uses this extension point internally, to switch between its fam-based and inotify-based file monitoring implementations.

### G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME

Allows to override the directory monitor implementation for local files. Implementations of this extension point must be derived from #GLocalDirectoryMonitor. GIO uses the implementation with the highest priority that is supported, as determined by the is_supported() vfunc in #GLocalDirectoryMonitorClass.

GIO uses this extension point internally, to switch between its fam-based and inotify-based directory monitoring implementations.

### G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME

Unix-only. Allows to provide a way to associate default handlers with URI schemes. Implementations of this extension point must implement the #GDesktopAppInfoLookup interface. GIO uses the implementation with the highest priority.

This extension point has been discontinued in GLib 2.28. It is still available to keep API and ABI stability, but GIO is no longer using it for default handlers. Instead, the mime handler mechanism is used, together with x-scheme-handler pseudo-mimetypes.

### G_SETTINGS_BACKEND_EXTENSION_POINT_NAME

Allows to provide an alternative storage for #GSettings. Implementations of this extension point must derive from the #GSettingsBackend type. GIO contains a keyfile-based implementation of this extension point, another one is provided by dconf.

### G_PROXY_EXTENSION_POINT_NAME

Allows to provide implementations for network proxying. Implementations of this extension point must provide the #GProxy interface, and must be named after the network protocol they are proxying.

glib-networking contains an implementation of this extension point based on libproxy.

### G_TLS_BACKEND_EXTENSION_POINT_NAME

Allows to provide implementations for TLS support. Implementations of this extension point must implement the #GTlsBackend interface.

glib-networking contains an implementation of this extension point.