2 <title>GIO Overview</title>
5 <title>Introduction</title>
8 GIO is striving to provide a modern, easy-to-use VFS API that sits
9 at the right level in the library stack, as well as other generally
10 useful APIs for desktop applications (such as networking and
11 D-Bus support). The goal is to overcome the shortcomings of GnomeVFS
12 and provide an API that is so good that developers prefer it over raw
13 POSIX calls. Among other things that means using GObject. It also means
14 not cloning the POSIX API, but providing higher-level, document-centric
19 The abstract file system model of GIO consists of a number of
20 interfaces and base classes for I/O and files:
24 <listitem><para>reference to a file</para></listitem>
27 <term>GFileInfo</term>
28 <listitem><para>information about a file or filesystem</para></listitem>
31 <term>GFileEnumerator</term>
32 <listitem><para>list files in directories</para></listitem>
36 <listitem><para>represents a drive</para></listitem>
40 <listitem><para>represents a file system in an abstract way</para></listitem>
44 <listitem><para>represents a mounted file system</para></listitem>
47 Then there is a number of stream classes, similar to the input and
48 output stream hierarchies that can be found in frameworks like Java:
51 <term>GInputStream</term>
52 <listitem><para>read data</para></listitem>
55 <term>GOutputStream</term>
56 <listitem><para>write data</para></listitem>
59 <term>GIOStream</term>
60 <listitem><para>read and write data</para></listitem>
63 <term>GSeekable</term>
64 <listitem><para>interface optionally implemented by streams to support seeking</para></listitem>
67 There are interfaces related to applications and the types
72 <listitem><para>information about an installed application</para></listitem>
76 <listitem><para>abstract type for file and application icons</para></listitem>
79 There is a framework for storing and retrieving application settings:
82 <term>GSettings</term>
83 <listitem><para>stores and retrieves application settings</para></listitem>
86 There is support for network programming, including connectivity monitoring,
87 name resolution, lowlevel socket APIs and highlevel client and server
92 <listitem><para>lowlevel platform independent socket object</para></listitem>
95 <term>GResolver</term>
96 <listitem><para>asynchronous and cancellable DNS resolver</para></listitem>
99 <term>GSocketClient</term>
100 <listitem><para>high-level network client helper</para></listitem>
103 <term>GSocketService</term>
104 <listitem><para>high-level network server helper</para></listitem>
107 <term>GSocketConnection</term>
108 <listitem><para>network connection stream</para></listitem>
111 <term>GNetworkMonitor</term>
112 <listitem><para>network connectivity monitoring</para></listitem>
115 There is support for connecting to <link linkend="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</link>,
116 sending and receiving messages, owning and watching bus names,
117 and making objects available on the bus:
120 <term>GDBusConnection</term>
121 <listitem><para>a D-Bus connection</para></listitem>
125 <term>GDBusMethodInvocation</term>
126 <listitem><para>for handling remove calls</para></listitem>
130 <term>GDBusServer</term>
131 <listitem><para>helper for accepting connections</para></listitem>
135 <term>GDBusProxy</term>
136 <listitem><para>proxy to access D-Bus interfaces on a remote object</para></listitem>
140 Beyond these, GIO provides facilities for file monitoring,
141 asynchronous I/O and filename completion. In addition to the
142 interfaces, GIO provides implementations for the local case.
143 Implementations for various network file systems are provided
144 by the GVFS package as loadable modules.
148 Other design choices which consciously break with the GnomeVFS
149 design are to move backends out-of-process, which minimizes the
150 dependency bloat and makes the whole system more robust. The backends
151 are not included in GIO, but in the separate GVFS package. The GVFS
152 package also contains the GVFS daemon, which spawn further mount
153 daemons for each individual connection.
156 <figure id="gvfs-overview">
157 <title>GIO in the GTK+ library stack</title>
158 <graphic fileref="gvfs-overview.png" format="PNG"></graphic>
162 The GIO model of I/O is stateful: if an application establishes e.g.
163 a SFTP connection to a server, it becomes available to all applications
164 in the session; the user does not have to enter his password over
168 One of the big advantages of putting the VFS in the GLib layer
169 is that GTK+ can directly use it, e.g. in the filechooser.
174 <title>Writing GIO applications</title>
177 The information in the GLib <ulink url="http://developer.gnome.org/glib/stable/glib-programming.html">documentation</ulink> about writing GLib
178 applications is generally applicable when writing GIO applications.
181 <simplesect><title>Threads</title>
184 GDBus has its own private worker thread, so applications using
185 GDBus have at least 3 threads. GIO makes heavy use of the concept
186 of a <link linkend="g-main-context-push-thread-default">thread-default
187 main context</link> to execute callbacks of asynchronous
188 methods in the same context in which the operation was started.
193 <simplesect><title>Security</title>
196 When your program needs to carry out some privileged operation (say,
197 create a new user account), there are various ways in which you can go
201 Implement a daemon that offers the privileged operation. A convenient
202 way to do this is as a D-Bus system-bus service. The daemon will probably
203 need ways to check the identity and authorization of the caller before
204 executing the operation. <ulink url="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">polkit</ulink> is a framework that allows this.
207 Use a small helper that is executed with elevated privileges via
208 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.
211 Use a small helper that is executed with elevated privileges by
215 None of these approaches is the clear winner, they all have their
216 advantages and disadvantages.
220 When writing code that runs with elevated privileges, it is important
221 to follow some basic rules of secure programming. David Wheeler has an
222 excellent book on this topic,
223 <ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
227 When using GIO in code that runs with elevated privileges, you have to
228 be careful. GIO has extension points whose implementations get loaded
229 from modules (executable code in shared objects), which could allow
230 an attacker to sneak his own code into your application by tricking it
231 into loading the code as a module. However, GIO will never load modules
232 from your home directory except when explictly asked to do so via an
233 environment variable.
237 In most cases, your helper program should be so small that you don't
238 need GIO, whose APIs are largely designed to support full-blown desktop
239 applications. If you can't resist the convenience of these APIs, here
240 are some steps you should take:
243 Clear the environment, e.g. using the <function>clearenv()</function>
245 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
246 important to sanitize the environment.
247 See <xref linkend="running-gio-apps"/>
248 for a list of all environment variables affecting GIO. In particular,
249 <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.
252 Don't use GVfs, by setting <envar>GIO_USE_VFS=local</envar> in the environment.
253 The reason to avoid GVfs in security-sensitive programs is that it uses
254 many libraries which have not necessarily been audited for security problems.
255 Gvfs is also heavily distributed and relies on a session bus to be present.
265 <title>Compiling GIO applications</title>
268 GIO comes with a <filename>gio-2.0.pc</filename> file that you
269 should use together with <literal>pkg-config</literal> to obtain
270 the necessary information about header files and libraries. See
271 the <literal>pkg-config</literal> man page or the GLib documentation
272 for more information on how to use <literal>pkg-config</literal>
273 to compile your application.
277 If you are using GIO on UNIX-like systems, you may want to use
278 UNIX-specific GIO interfaces such as #GUnixInputStream,
279 #GUnixOutputStream, #GUnixMount or #GDesktopAppInfo.
280 To do so, use the <filename>gio-unix-2.0.pc</filename> file
281 instead of <filename>gio-2.0.pc</filename>
285 Since GIO is based on GObject, you need to call g_type_init()
286 before you can use any GIO functions. If your application uses
287 GTK+, this is already taken care of by gtk_init().
291 <chapter id="running-gio-apps">
292 <title>Running GIO applications</title>
295 GIO inspects a few of environment variables in addition to the
300 <title><envar>XDG_DATA_HOME</envar>, <envar>XDG_DATA_DIRS</envar></title>
303 GIO uses these environment variables to locate MIME information.
304 For more information, see the <ulink url="http://freedesktop.org/Standards/shared-mime-info-spec">Shared MIME-info Database</ulink>
305 and the <ulink url="http://freedesktop.org/Standards/basedir-spec">Base Directory Specification</ulink>.
310 <title><envar>GVFS_DISABLE_FUSE</envar></title>
313 This variable can be set to keep #Gvfs from starting the fuse backend,
314 which may be unwanted or unnecessary in certain situations.
319 The following environment variables are only useful for debugging
320 GIO itself or modules that it loads. They should not be set in a
321 production environment.
324 <title><envar>GIO_USE_VFS</envar></title>
327 This environment variable can be set to the name of a #GVfs
328 implementation to override the default for debugging purposes.
329 The #GVfs implementation for local files that is included in GIO
330 has the name "local", the implementation in the gvfs module has
336 <title><envar>GIO_USE_VOLUME_MONITOR</envar></title>
339 This variable can be set to the name of a #GVolumeMonitor
340 implementation to override the default for debugging purposes.
341 The #GVolumeMonitor implementation for local files that is included
342 in GIO has the name "unix", the hal-based implementation in the
343 gvfs module has the name "hal".
348 <title><envar>GIO_USE_TLS</envar></title>
351 This variable can be set to the name of a #GTlsBackend
352 implementation to override the default for debugging purposes.
353 GIO does not include a #GTlsBackend implementation, the gnutls-based
354 implementation in the glib-networking module has the name "gnutls".
359 <title><envar>GIO_EXTRA_MODULES</envar></title>
362 When this environment variable is set to a path, or a set of
363 paths separated by a colon, GIO will attempt to load
364 modules from within the path.
369 <title><envar>GSETTINGS_BACKEND</envar></title>
372 This variable can be set to the name of a #GSettingsBackend
373 implementation to override the default for debugging purposes.
374 The memory-based implementation that is included in GIO has
375 the name "memory", the one in dconf has the name "dconf-settings".
380 <title><envar>GSETTINGS_SCHEMA_DIR</envar></title>
383 This variable can be set to the name of a directory that is
384 considered in addition to the <filename>glib-2.0/schemas</filename>
385 subdirectories of the XDG system data dirs when looking
386 for compiled schemas for #GSettings.
391 <title><envar>DBUS_SYSTEM_BUS_ADDRESS</envar></title>
394 This variable is consulted to find the address of the D-Bus system
395 bus. For the format of D-Bus addresses, see the D-Bus
396 <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">specification</ulink>.
399 Setting this variable overrides platform-specific ways of determining
400 the system bus address.
405 <title><envar>DBUS_SESSION_BUS_ADDRESS</envar></title>
408 This variable is consulted to find the address of the D-Bus session bus.
411 Setting this variable overrides platform-specific ways of determining
412 the session bus address.
417 <title><envar>DBUS_STARTER_BUS_TYPE</envar></title>
420 This variable is consulted to find out the 'starter' bus for an
421 application that has been started via D-Bus activation. The possible
422 values are 'system' or 'session'.
427 <title><envar>G_DBUS_DEBUG</envar></title>
430 This variable can be set to a list of debug options, which
431 cause GLib to print out different types of debugging
432 information when using the D-Bus routines.
435 <term>transport</term>
436 <listitem><para>Show IO activity (e.g. reads and writes)</para></listitem>
440 <listitem><para>Show all sent and received D-Bus messages</para></listitem>
444 <listitem><para>Show payload for all sent and received D-Bus messages (implies message)</para></listitem>
448 <listitem><para>Trace g_dbus_connection_call() and g_dbus_connection_call_sync() API usage</para></listitem>
452 <listitem><para>Show when a D-Bus signal is received</para></listitem>
455 <term>incoming</term>
456 <listitem><para>Show when an incoming D-Bus method call is received</para></listitem>
460 <listitem><para>Show when a reply is returned via the #GDBusMethodInvocation API</para></listitem>
463 <term>emission</term>
464 <listitem><para>Trace g_dbus_connection_emit_signal() API usage</para></listitem>
467 <term>authentication</term>
468 <listitem><para>Show information about connection authentication</para></listitem>
472 <listitem><para>Show information about D-Bus address lookups and autolaunching</para></listitem>
475 The special value <literal>all</literal> can be used to turn
476 on all debug options. The special value
477 <literal>help</literal> can be used to print a list of
478 supported options to standard output.
483 <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR</envar></title>
486 Can be used to override the directory used to store the
487 keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
488 authentication mechanism. Normally the directory used is
489 <filename>.dbus-keyrings</filename> in the user's home
495 <title><envar>G_DBUS_COOKIE_SHA1_KEYRING_DIR_IGNORE_PERMISSION</envar></title>
498 If set, the permissions of the directory used to store the
499 keyring used in the <literal>DBUS_COOKIE_SHA1</literal>
500 authentication mechanism won't be checked. Normally the
501 directory must be readable only by the user.
506 <chapter id="extending-gio">
507 <title>Extending GIO</title>
510 A lot of the functionality that is accessible through GIO
511 is implemented in loadable modules, and modules provide a convenient
512 way to extend GIO. In addition to the #GIOModule API which supports
513 writing such modules, GIO has a mechanism to define extension points,
514 and register implementations thereof, see #GIOExtensionPoint.
517 The following extension points are currently defined by GIO:
521 <title>G_VFS_EXTENSION_POINT_NAME</title>
524 Allows to override the functionality of the #GVfs class.
525 Implementations of this extension point must be derived from #GVfs.
526 GIO uses the implementation with the highest priority that is active,
527 see g_vfs_is_active().
530 GIO implements this extension point for local files, gvfs contains
531 an implementation that supports all the backends in gvfs.
536 <title>G_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
539 Allows to add more volume monitors.
540 Implementations of this extension point must be derived from
541 #GVolumeMonitor. GIO uses all registered extensions.
544 gvfs contains an implementation that works together with the #GVfs
545 implementation in gvfs.
550 <title>G_NATIVE_VOLUME_MONITOR_EXTENSION_POINT_NAME</title>
553 Allows to override the 'native' volume monitor.
554 Implementations of this extension point must be derived from
555 #GNativeVolumeMonitor. GIO uses the implementation with
556 the highest priority that is supported, as determined by the
557 is_supported() vfunc in #GVolumeMonitorClass.
560 GIO implements this extension point for local mounts,
561 gvfs contains a hal-based implementation.
566 <title>G_LOCAL_FILE_MONITOR_EXTENSION_POINT_NAME</title>
569 Allows to override the file monitor implementation for
570 local files. Implementations of this extension point must
571 be derived from #GLocalFileMonitor. GIO uses the implementation
572 with the highest priority that is supported, as determined by the
573 is_supported() vfunc in #GLocalFileMonitorClass.
576 GIO uses this extension point internally, to switch between
577 its fam-based and inotify-based file monitoring implementations.
582 <title>G_LOCAL_DIRECTORY_MONITOR_EXTENSION_POINT_NAME</title>
585 Allows to override the directory monitor implementation for
586 local files. Implementations of this extension point must be
587 derived from #GLocalDirectoryMonitor. GIO uses the implementation
588 with the highest priority that is supported, as determined by the
589 is_supported() vfunc in #GLocalDirectoryMonitorClass.
592 GIO uses this extension point internally, to switch between
593 its fam-based and inotify-based directory monitoring implementations.
598 <title>G_DESKTOP_APP_INFO_LOOKUP_EXTENSION_POINT_NAME</title>
601 Unix-only. Allows to provide a way to associate default handlers
602 with URI schemes. Implementations of this extension point must
603 implement the #GDesktopAppInfoLookup interface. GIO uses the
604 implementation with the highest priority.
607 This extension point has been discontinued in GLib 2.28. It is
608 still available to keep API and ABI stability, but GIO is no
609 longer using it for default handlers. Instead, the mime handler
610 mechanism is used, together with x-scheme-handler pseudo-mimetypes.
615 <title>G_SETTINGS_BACKEND_EXTENSION_POINT_NAME</title>
618 Allows to provide an alternative storage for #GSettings.
619 Implementations of this extension point must derive from the
620 #GSettingsBackend type. GIO contains a keyfile-based
621 implementation of this extension point, another one is provided
627 <title>G_PROXY_EXTENSION_POINT_NAME</title>
630 Allows to provide implementations for network proxying.
631 Implementations of this extension point must provide the
632 #GProxy interface, and must be named after the network
633 protocol they are proxying.
636 glib-networking contains an implementation of this extension
637 point based on libproxy.
641 <title>G_TLS_BACKEND_EXTENSION_POINT_NAME</title>
644 Allows to provide implementations for TLS support.
645 Implementations of this extension point must implement
646 the #GTlsBackend interface.
649 glib-networking contains an implementation of this extension
655 <title>G_NETWORK_MONITOR_EXTENSION_POINT_NAME</title>
658 Allows to provide implementations for network connectivity
660 Implementations of this extension point must implement
661 the #GNetworkMonitorInterface interface.
664 GIO contains an implementation of this extension point
665 that is using the netlink interface of the Linux kernel.