luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 03:16:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move GIO overview to Markdown

Browse Source 
Helps: #3037
This commit is contained in:
Matthias Clasen 2023-10-09 23:24:09 +01:00 committed by Philip Withnall
parent c09f48bb28
commit fc29022f0b
5 changed files with 410 additions and 759 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/gio/gio-docs.xml
View File

@ -15,8 +15,6 @@
</releaseinfo>
</bookinfo>
<xi:include href="xml/overview.xml"/>
<part>
<title>API Reference</title>
<chapter id="file_ops">

3
docs/reference/gio/gio.toml.in
View File

@ -40,10 +40,13 @@ show_class_hierarchy = true
urlmap_file = "urlmap.js"
# The same order will be used when generating the index
content_files = [
"overview.md",
"migrating-gconf.md",
"migrating-gnome-vfs.md",
]
content_images = [
"gvfs-overview.png",
"menu-example.png",
"menu-model.png",
]

3
docs/reference/gio/meson.build
View File

@ -161,7 +161,6 @@ if get_option('gtk_doc')
)
content_files = [
'overview.xml',
'migrating-posix.xml',
'migrating-gdbus.xml',
'gio-querymodules.xml',
@ -196,7 +195,6 @@ if get_option('gtk_doc')
],
content_files : content_files,
expand_content_files : [
'overview.xml',
'migrating-posix.xml',
'migrating-gdbus.xml',
'gdbus-codegen.xml',
@ -235,6 +233,7 @@ endif
expand_content_files = [
'migrating-gconf.md',
'migrating-gnome-vfs.md',
'overview.md',
]
gio_gir = meson.current_source_dir() / 'Gio-2.0.gir'

406
docs/reference/gio/overview.md Normal file
View File

@ -0,0 +1,406 @@
Title: Overview
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007, 2008, 2010, 2011, 2012, 2013 Matthias Clasen
SPDX-FileCopyrightText: 2007, 2009 Alexander Larsson
SPDX-FileCopyrightText: 2008 A. Walton
SPDX-FileCopyrightText: 2010 David Zeuthen
SPDX-FileCopyrightText: 2013 Stef Walter
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
SPDX-FileCopyrightText: 2016 Colin Walters
SPDX-FileCopyrightText: 2020 Wouter Bolsterlee
SPDX-FileCopyrightText: 2022 Endless OS Foundation, LLC
# Overview
GIO is striving to provide a modern, easy-to-use VFS API that sits at the
right level in the library stack, as well as other generally useful APIs
for desktop applications (such as networking and D-Bus support). 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:
[iface@Gio.File]
: reference to a file
[class@Gio.FileInfo]
: information about a file or filesystem
[class@Gio.FileEnumerator]
: list files in directories
[iface@Gio.Drive]
: represents a drive
[iface@Gio.Volume]
: represents a file system in an abstract way
[iface@Gio.Mount]
: 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:
[class@Gio.InputStream]
: read data
[class@Gio.OutputStream]
: write data
[class@Gio.IOStream]
: read and write data
[iface@Gio.Seekable]
: interface optionally implemented by streams to support seeking
There are interfaces related to applications and the types of files they
handle:
[iface@Gio.AppInfo]
: information about an installed application
[iface@Gio.Icon]
: abstract type for file and application icons
There is a framework for storing and retrieving application settings:
[class@Gio.Settings]
: stores and retrieves application settings
There is support for network programming, including connectivity monitoring,
name resolution, lowlevel socket APIs and highlevel client and server helper
classes:
[class@Gio.Socket]
: lowlevel platform independent socket object
[class@Gio.Resolver]
: asynchronous and cancellable DNS resolver
[class@Gio.SocketClient]
: high-level network client helper
[class@Gio.SocketService]
: high-level network server helper
[class@Gio.SocketConnection]
: network connection stream
[iface@Gio.NetworkMonitor]
: network connectivity monitoring
There is support for connecting to
[D-Bus](https://www.freedesktop.org/wiki/Software/dbus/), sending and receiving
messages, owning and watching bus names, and making objects available on the bus:
[class@Gio.DBusConnection]
: a D-Bus connection
[class@Gio.DBusMethodInvocation]
: for handling remote calls
[class@Gio.DBusServer]
: helper for accepting connections
[class@Gio.DBusProxy]
: 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](./gvfs-overview.png)
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.
## Writing GIO applications
The information in the GLib documentation about writing GLib applications is
generally applicable when writing GIO applications.
### Threads
GDBus has its own private worker thread, so applications using GDBus have at
least 3 threads. GIO makes heavy use of the concept of a thread-default main
context to execute callbacks of asynchronous methods in the same context in
which the operation was started.
### Asynchronous Programming
Many GIO functions come in two versions: synchronous and asynchronous,
denoted by an `_async` suffix. It is important to use these appropriately:
synchronous calls should not be used from within a main loop which is shared
with other code, such as one in the application’s main thread. Synchronous
calls block until they complete, and I/O operations can take noticeable
amounts of time (even on ‘fast’ SSDs). Blocking a main loop iteration while
waiting for I/O means that other sources in the main loop will not be
dispatched, such as input and redraw handlers for the application’s UI. This
can cause the application to ‘freeze’ until I/O completes.
A few self-contained groups of functions, such as code generated by
gdbus-codegen, use a different convention: functions are asynchronous
default, and it is the synchronous version which has a `_sync` suffix. Aside
from naming differences, they should be treated the same way as functions
following the normal convention above.
The asynchronous (`_async`) versions of functions return control to the
caller immediately, after scheduling the I/O in the kernel and adding a
callback for it to the main loop. This callback will be invoked when the
operation has completed. From the callback, the paired `_finish` function
should be called to retrieve the return value of the I/O operation, and any
errors which occurred. For more information on using and implementing
asynchronous functions, see [iface@Gio.AsyncResult] and [class@Gio.Task].
By starting multiple asynchronous operations in succession, they will be
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
worker thread pool).
The synchronous versions of functions can be used early in application
startup when there is no main loop to block, for example to load initial
configuration files. They can also be used for I/O on files which are
guaranteed to be small and on the local disk. Note that the user’s home
directory is not guaranteed to be on the local disk. Security
When your program needs to carry out some privileged operation (say, create
a new user account), there are various ways in which you can go about this:
- Implement a daemon that offers the privileged operation. A convenient way
to do this is as a D-Bus system-bus service. The daemon will probably need
ways to check the identity and authorization of the caller before
executing the operation.
[polkit](https://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html)
is a framework that allows this.
- Use a small helper that is executed with elevated privileges via pkexec.
[`pkexec`](https://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html)
is a small program launcher that is part of polkit.
- Use a small helper that is executed with elevated privileges by being suid
root.
None of these approaches is the clear winner, they all have their advantages
and disadvantages.
When writing code that runs with elevated privileges, it is important to
follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
[Secure Programming for Linux and Unix HOWTO](https://dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html).
When using GIO in code that runs with elevated privileges, you have to be
careful. GIO has extension points whose implementations get loaded from
modules (executable code in shared objects), which could allow an attacker
to sneak his own code into your application by tricking it into loading the
code as a module. However, GIO will never load modules from your home
directory except when explicitly asked to do so via an environment variable.
In most cases, your helper program should be so small that you don't need
GIO, whose APIs are largely designed to support full-blown desktop
applications. If you can't resist the convenience of these APIs, here are
some steps you should take:
- Clear the environment, e.g. using the `clearenv()` function. David Wheeler
has a good
[explanation](https://dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html)
for why it is important to sanitize the environment. See the section on
running GIO applications for a list of all environment variables affecting
GIO. In particular, `PATH` (used to locate binaries), `GIO_EXTRA_MODULES`
(used to locate loadable modules) and `DBUS_{SYSTEM,SESSION}_BUS_ADDRESS`
(used to locate the D-Bus system and session bus) are important.
- Don't use GVfs, by setting `GIO_USE_VFS=local` in the environment. The
reason to avoid GVfs in security-sensitive programs is that it uses many
libraries which have not necessarily been audited for security problems.
Gvfs is also heavily distributed and relies on a session bus to be
present.
## 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`.
## Running GIO applications
GIO inspects a few 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](https://specifications.freedesktop.org/shared-mime-info-spec/latest/)
and the [Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/).
- `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.
- `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". Most
commonly, system software will set this to "local" to avoid having `GFile`
APIs perform unnecessary D-Bus calls. The special value help can be used
to print a list of available implementations to standard output.
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_FILE_MONITOR`. This variable can be set to the name of a
GFileMonitor implementation to override the default for debugging
purposes. The GFileMonitor implementation for local files that is included
in GIO on Linux has the name "inotify", others that are built are built as
modules (depending on the platform) are called "fam" and "fen". The
special value help can be used to print a list of available
implementations to standard output.
- `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 udisks2-based implementation in
the gvfs module has the name "udisks2". The special value help can be used
to print a list of available implementations to standard output.
- `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". The special value
help can be used to print a list of available implementations to standard
output.
- `GIO_USE_PORTALS`. This variable can be set to override detection of portals
and force them to be used to provide various bits of GIO functionality, for
testing and debugging. This variable is not intended to be used in production.
- `GIO_MODULE_DIR`. When this environment variable is set to a path, GIO
will load modules from this alternate directory instead of the directory
built into GIO. This is useful when running tests, for example. This
environment variable is ignored when running in a setuid program.
- `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 additional
modules from within the path. This environment variable is ignored when
running in a setuid program.
- `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". The special value
help can be used to print a list of available implementations to standard
output.
- `GSETTINGS_SCHEMA_DIR`. This variable can be set to the names of
directories to consider when looking for compiled schemas for GSettings,
in addition to the `glib-2.0/schemas` subdirectories of the XDG system
data dirs. To specify multiple directories, use `G_SEARCHPATH_SEPARATOR_S`
as a separator.
- `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](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
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
- `all`: Turn on all debug options
- `help`: Print a list of supported options to the 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 [`class@Gio.IOModule`] API which supports writing such modules, GIO has a
mechanism to define extension points, and register implementations thereof,
see [`struct@Gio.IOExtensionPoint`].
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 udisks2-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.
- `G_NETWORK_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
implementations for network connectivity monitoring. Implementations of
this extension point must implement the GNetworkMonitorInterface
interface. GIO contains an implementation of this extension point that is
using the netlink interface of the Linux kernel.

755
docs/reference/gio/overview.xml
View File

@ -1,755 +0,0 @@
<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, as well as other generally
useful APIs for desktop applications (such as networking and
D-Bus support). 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>GIOStream</term>
<listitem><para>read and 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>
There is a framework for storing and retrieving application settings:
<variablelist>
<varlistentry>
<term>GSettings</term>
<listitem><para>stores and retrieves application settings</para></listitem>
</varlistentry>
</variablelist>
There is support for network programming, including connectivity monitoring,
name resolution, lowlevel socket APIs and highlevel client and server
helper classes:
<variablelist>
<varlistentry>
<term>GSocket</term>
<listitem><para>lowlevel platform independent socket object</para></listitem>
</varlistentry>
<varlistentry>
<term>GResolver</term>
<listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketClient</term>
<listitem><para>high-level network client helper</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketService</term>
<listitem><para>high-level network server helper</para></listitem>
</varlistentry>
<varlistentry>
<term>GSocketConnection</term>
<listitem><para>network connection stream</para></listitem>
</varlistentry>
<varlistentry>
<term>GNetworkMonitor</term>
<listitem><para>network connectivity monitoring</para></listitem>
</varlistentry>
</variablelist>
There is support for connecting to <ulink url="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
sending and receiving messages, owning and watching bus names,
and making objects available on the bus:
<variablelist>
<varlistentry>
<term>GDBusConnection</term>
<listitem><para>a D-Bus connection</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusMethodInvocation</term>
<listitem><para>for handling remote calls</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusServer</term>
<listitem><para>helper for accepting connections</para></listitem>
</varlistentry>
<varlistentry>
<term>GDBusProxy</term>
<listitem><para>proxy to access D-Bus interfaces on a remote object</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 their 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>Writing GIO applications</title>
<para>
The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
applications is generally applicable when writing GIO applications.
</para>
<simplesect><title>Threads</title>
<para>
GDBus has its own private worker thread, so applications using
GDBus have at least 3 threads. GIO makes heavy use of the concept
of a <link linkend="g-main-context-push-thread-default">thread-default
main context</link> to execute callbacks of asynchronous
methods in the same context in which the operation was started.
</para>
</simplesect>
<simplesect id="async-programming"><title>Asynchronous Programming</title>
<para>
Many GIO functions come in two versions: synchronous and asynchronous,
denoted by an <code>_async</code> suffix. It is important to use these
appropriately: synchronous calls should not be used from
within a main loop which is shared with other code, such as one in the
application’s main thread. Synchronous calls block until they complete,
and I/O operations can take noticeable amounts of time (even on ‘fast’
SSDs). Blocking a main loop iteration while waiting for I/O means that
other sources in the main loop will not be dispatched, such as input and
redraw handlers for the application’s UI. This can cause the application
to ‘freeze’ until I/O completes.
</para>
<para>
A few self-contained groups of functions, such as code generated by
<link linkend="gdbus-codegen"><application>gdbus-codegen</application></link>,
use a different convention: functions are asynchronous default, and it is
the <emphasis>synchronous</emphasis> version which has a
<code>_sync</code>
suffix. Aside from naming differences, they should be treated the same
way as functions following the normal convention above.
</para>
<para>
The asynchronous (<code>_async</code>) versions of functions return
control to the caller immediately, after scheduling the I/O in the kernel
and adding a callback for it to the main loop. This callback will be
invoked when the operation has completed. From the callback, the paired
<code>_finish</code> function should be called to retrieve the return
value of the I/O operation, and any errors which occurred. For more
information on using and implementing asynchronous functions, see
<link linkend="GAsyncResult.description"><type>GAsyncResult</type></link>
and <link linkend="GTask.description"><type>GTask</type></link>.
</para>
<para>
By starting multiple asynchronous operations in succession, they will be
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
worker thread pool).
</para>
<para>
The synchronous versions of functions can be used early in application
startup when there is no main loop to block, for example to load initial
configuration files. They can also be used for I/O on files which are
guaranteed to be small and on the local disk. Note that the user’s home
directory is not guaranteed to be on the local disk.
</para>
</simplesect>
<simplesect><title>Security</title>
<para>
When your program needs to carry out some privileged operation (say,
create a new user account), there are various ways in which you can go
about this:
<itemizedlist>
<listitem><para>
Implement a daemon that offers the privileged operation. A convenient
way to do this is as a D-Bus system-bus service. The daemon will probably
need ways to check the identity and authorization of the caller before
executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
</para></listitem>
<listitem><para>
Use a small helper that is executed with elevated privileges via
pkexec. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html">pkexec</ulink> is a small program launcher that is part of polkit.
</para></listitem>
<listitem><para>
Use a small helper that is executed with elevated privileges by
being suid root.
</para></listitem>
</itemizedlist>
None of these approaches is the clear winner, they all have their
advantages and disadvantages.
</para>
<para>
When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
</para>
<para>
When using GIO in code that runs with elevated privileges, you have to
be careful. GIO has extension points whose implementations get loaded
from modules (executable code in shared objects), which could allow
an attacker to sneak their own code into your application by tricking it
into loading the code as a module. However, GIO will never load modules
from your home directory except when explicitly asked to do so via an
environment variable.
</para>
<para>
In most cases, your helper program should be so small that you don't
need GIO, whose APIs are largely designed to support full-blown desktop
applications. If you can't resist the convenience of these APIs, here
are some steps you should take:
<itemizedlist>
<listitem><para>
Clear the environment, e.g. using the <function>clearenv()</function>
function.
David Wheeler has a good <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html">explanation</ulink> for why it is
important to sanitize the environment.
See <xref linkend="running-gio-apps"/>
for a list of all environment variables affecting GIO. In particular,
<envar>PATH</envar> (used to locate binaries), <envar>GIO_EXTRA_MODULES</envar> (used to locate loadable modules) and <envar>DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</envar> (used to locate the D-Bus system and session bus) are important.
</para></listitem>
<listitem><para>
Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
The reason to avoid GVfs in security-sensitive programs is that it uses
many libraries which have not necessarily been audited for security problems.
Gvfs is also heavily distributed and relies on a session bus to be present.
</para></listitem>
</itemizedlist>
</para>
</simplesect>
</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 id="running-gio-apps">
<title>Running GIO applications</title>
<para>
GIO inspects a few 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>
<formalpara>
<title><envar>GVFS_DISABLE_FUSE</envar></title>
<para>
This variable can be set to keep #Gvfs from starting the fuse backend,
which may be unwanted or unnecessary in certain situations.
</para>
</formalpara>
<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". Most commonly, system software will set this to "local"
to avoid having `GFile` APIs perform unnecessary D-Bus calls.
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</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_FILE_MONITOR</envar></title>
<para>
This variable can be set to the name of a #GFileMonitor
implementation to override the default for debugging purposes.
The #GFileMonitor implementation for local files that is included
in GIO on Linux has the name <literal>inotify</literal>, others that are built
are built as modules (depending on the platform) are called
<literal>kqueue</literal> and <literal>win32filemonitor</literal>.
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</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 udisks2-based implementation in the
gvfs module has the name "udisks2".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_TLS</envar></title>
<para>
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".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_USE_PORTALS</envar></title>
<para>
This variable can be set to override detection of portals and force them
to be used to provide various bits of GIO functionality, for testing and
debugging. This variable is not intended to be used in production.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_MODULE_DIR</envar></title>
<para>
When this environment variable is set to a path, GIO will load
modules from this alternate directory instead of the directory
built into GIO. This is useful when running tests, for example.
</para>
<para>
This environment variable is ignored when running in a setuid program.
</para>
</formalpara>
<formalpara>
<title><envar>GIO_EXTRA_MODULES</envar></title>
<para>
When this environment variable is set to a path, or a set of
paths separated by a colon, GIO will attempt to load
additional modules from within the path.
</para>
<para>
This environment variable is ignored when running in a setuid program.
</para>
</formalpara>
<formalpara>
<title><envar>GSETTINGS_BACKEND</envar></title>
<para>
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".
</para><para>
The special value <literal>help</literal> can be used to print a list of
available implementations to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
<para>
This variable can be set to the names of directories to consider when looking for compiled schemas for #GSettings,
in addition to the <filename>glib-2.0/schemas</filename>
subdirectories of the XDG system data dirs. To specify multiple directories, use <constant>G_SEARCHPATH_SEPARATOR_S</constant> as a separator.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
<para>
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
<ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
</para>
<para>
Setting this variable overrides platform-specific ways of determining
the system bus address.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
<para>
This variable is consulted to find the address of the D-Bus session bus.
</para>
<para>
Setting this variable overrides platform-specific ways of determining
the session bus address.
</para>
</formalpara>
<formalpara>
<title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
<para>
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'.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_DEBUG</envar></title>
<para>
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.
<variablelist>
<varlistentry>
<term>transport</term>
<listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
</varlistentry>
<varlistentry>
<term>message</term>
<listitem><para>Show all sent and received D-Bus messages</para></listitem>
</varlistentry>
<varlistentry>
<term>payload</term>
<listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
</varlistentry>
<varlistentry>
<term>call</term>
<listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
</varlistentry>
<varlistentry>
<term>signal</term>
<listitem><para>Show when a D-Bus signal is received</para></listitem>
</varlistentry>
<varlistentry>
<term>incoming</term>
<listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
</varlistentry>
<varlistentry>
<term>return</term>
<listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
</varlistentry>
<varlistentry>
<term>emission</term>
<listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
</varlistentry>
<varlistentry>
<term>authentication</term>
<listitem><para>Show information about connection authentication</para></listitem>
</varlistentry>
<varlistentry>
<term>address</term>
<listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn
on all debug options. The special value
<literal>help</literal> can be used to print a list of
supported options to standard output.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
<para>
Can be used to override the directory used to store the
keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
authentication mechanism. Normally the directory used is
<filename>.dbus-keyrings</filename> in the user's home
directory.
</para>
</formalpara>
<formalpara>
<title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
<para>
If set, the permissions of the directory used to store the
keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
authentication mechanism won't be checked. Normally the
directory must be readable only by the user.
</para>
</formalpara>
</chapter>
<chapter id="extending-gio">
<title>Extending GIO</title>
<para>
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.
</para>
<para>
The following extension points are currently defined by GIO:
</para>
<formalpara>
<title>G_VFS_EXTENSION_POINT_NAME</title>
<para>
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().
</para>
<para>
GIO implements this extension point for local files, gvfs contains
an implementation that supports all the backends in gvfs.
</para>
</formalpara>
<formalpara>
<title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to add more volume monitors.
Implementations of this extension point must be derived from
#GVolumeMonitor. GIO uses all registered extensions.
</para>
<para>
gvfs contains an implementation that works together with the #GVfs
implementation in gvfs.
</para>
</formalpara>
<formalpara>
<title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
<para>
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.
</para>
<para>
GIO implements this extension point for local mounts,
gvfs contains a udisks2-based implementation.
</para>
</formalpara>
<formalpara>
<title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
<para>
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.
</para>
<para>
GIO uses this extension point internally, to switch between
its kqueue-based and inotify-based file monitoring implementations.
</para>
</formalpara>
<formalpara>
<title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
<para>
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.
</para>
<para>
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.
</para>
</formalpara>
<formalpara>
<title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
<para>
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.
</para>
</formalpara>
<formalpara>
<title>G_PROXY_EXTENSION_POINT_NAME</title>
<para>
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.
</para>
<para>
glib-networking contains an implementation of this extension
point based on libproxy.
</para>
</formalpara>
<formalpara>
<title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for TLS support.
Implementations of this extension point must implement
the #GTlsBackend interface.
</para>
<para>
glib-networking contains an implementation of this extension
point.
</para>
</formalpara>
<formalpara>
<title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
<para>
Allows to provide implementations for network connectivity
monitoring.
Implementations of this extension point must implement
the #GNetworkMonitorInterface interface.
</para>
<para>
GIO contains an implementation of this extension point
that is using the netlink interface of the Linux kernel.
</para>
</formalpara>
</chapter>
</part>