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

docs: Port GIO overview to gi-docgen linking syntax and fix a few typos

Browse Source 
Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This commit is contained in:
Philip Withnall 2025-01-21 12:35:23 +00:00
parent d760bfef00
commit 58c4ab46f2
No known key found for this signature in database
GPG Key ID: C5C42CFB268637CA
1 changed files with 86 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
docs/reference/gio/overview.md
View File

@ -17,7 +17,7 @@ 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
that means using [class@GObject.Object]. 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
@ -71,11 +71,11 @@ There is a framework for storing and retrieving application 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
name resolution, low-level socket APIs and high-level client and server helper
classes:
[class@Gio.Socket]
: lowlevel platform independent socket object
: low-level platform independent socket object
[class@Gio.Resolver]
: asynchronous and cancellable DNS resolver
@ -123,14 +123,15 @@ which spawn further mount daemons for each individual connection.
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.
session; the user does not have to enter their 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.
can directly use it, e.g. in the file chooser.
## Writing GIO applications
The information in the GLib documentation about writing GLib applications is
The information in the GLib documentation about
[writing GLib applications](https://docs.gtk.org/glib/programming.html) is
generally applicable when writing GIO applications.
### Threads
@ -153,7 +154,7 @@ 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
[`gdbus-codegen`](gdbus-codegen.html), 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.
@ -187,10 +188,10 @@ a new user account), there are various ways in which you can go about this:
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.
- 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
- 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
@ -204,13 +205,13 @@ excellent book on this topic,
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
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.
In most cases, your helper program should be so small that you don't need
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
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
@ -221,7 +222,7 @@ some steps you should take:
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
- 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
@ -231,10 +232,11 @@ some steps you should take:
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
libraries. See the [pkg-config man page](man:pkg-config(1)) or the
[GLib documentation](https://docs.gtk.org/glib/compiling.html) 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
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 as well as
`gio-2.0.pc` (or, in GIR namespace terms, `GioUnix-2.0` as well as `Gio-2.0`).
@ -253,9 +255,9 @@ GIO inspects a few environment variables in addition to the ones used by GLib.
- `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
`local`, the implementation in the GVfs module has the name `gvfs`. Most
commonly, system software will set this to `local` to avoid having [iface@Gio.File]
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
@ -263,38 +265,38 @@ 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
[class@Gio.FileMonitor] implementation to override the default for debugging
purposes. The [class@Gio.FileMonitor] 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 `kqueue` and `win32`. 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
[class@Gio.VolumeMonitor] implementation to override the default for debugging
purposes. The [class@Gio.VolumeMonitor] 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_MEMORY_MONITOR`. This variable can be set to the name of a
GMemoryMonitory implementation to override the default for debugging
[iface@Gio.MemoryMonitor] implementation to override the default for debugging
purposes. The available implementations included in GIO have the names
"dbus", "portal" and "win32". The special value "help" can be used
`dbus`, `portal` and `win32`. The special value `help` can be used
to print a list of available implementations to standard output.
- `GIO_USE_NETWORK_MONITOR`. This variable can be set to the name of a
GNetworkMonitor implementation to override the default for debugging
[iface@Gio.NetworkMonitor] implementation to override the default for debugging
purposes. The available implementations included in GIO have the names
"netlink", "networkmanager" and "portal". The special value "help" can
`netlink`, `networkmanager` and `portal`. The special value `help` can
be used to print a list of available implementations to standard output.
- `GIO_USE_POWER_PROFILE_MONITOR`. This variable can be set to the name of a
GPowerProfileMonitor implementation to override the default for debugging
[iface@Gio.PowerProfileMonitor] implementation to override the default for debugging
purposes. The available implementations included in GIO have the names
"dbus" and "portal". The special value "help" can be used to print a list
`dbus` and `portal`. 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
- `GIO_USE_TLS`. This variable can be set to the name of a [iface@Gio.TlsBackend]
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
not include a [iface@Gio.TlsBackend] 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
@ -302,26 +304,26 @@ environment.
- `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.
environment variable is ignored when running in a SUID 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.
running in a SUID program.
- `GNOTIFICATION_BACKEND`. This variable can be set to the name of a
GNotificationBackend implementation to override the default for debugging
`GNotificationBackend` implementation to override the default for debugging
purposes. The implementations that are included in GIO have the names
"freedesktop", "cocoa", "gtk" and "portal". The special value "help" can
`freedesktop`, `cocoa`, `gtk` and `portal`. The special value `help` can
be used to print a list of available implementations to standard output.
- `GSETTINGS_BACKEND`. This variable can be set to the name of a
GSettingsBackend implementation to override the default for debugging
[class@Gio.SettingsBackend] 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
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,
directories to consider when looking for compiled schemas for [class@Gio.Settings],
in addition to the `glib-2.0/schemas` subdirectories of the XDG system
data dirs. To specify multiple directories, use `G_SEARCHPATH_SEPARATOR_S`
data directories. 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
@ -332,32 +334,32 @@ environment.
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'.
‘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)
- `transport`: Show I/O 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
- `call`: Trace [method@Gio.DBusConnection.call] and
[method@Gio.DBusConnection.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
- `return`: Show when a reply is returned via the [class@Gio.DBusMethodInvocation] API
- `emission`: Trace [method@Gio.DBusConnection.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
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
`DBUS_COOKIE_SHA1` authentication mechanism won’t be checked. Normally the
directory must be readable only by the user.
## Extending GIO
@ -371,77 +373,77 @@ 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
[class@Gio.Vfs] class. Implementations of this extension point must be derived from
[class@Gio.Vfs]. GIO uses the implementation with the highest priority that is
active, see [method@Gio.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.
[class@Gio.VolumeMonitor]. GIO uses all registered extensions. gvfs contains an
implementation that works together with the [class@Gio.Vfs] 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
‘native’ volume monitor. Implementations of this extension point must be
derived from [class@Gio.NativeVolumeMonitor]. GIO uses the implementation with the
highest priority that is supported, as determined by
`GVolumeMonitorClass.is_supported()`. 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
point must be derived from `GLocalFileMonitor`. GIO uses the implementation
with the highest priority that is supported, as determined by
`GLocalFileMonitorClass.is_supported()`. GIO uses this extension
point internally, to switch between its poll-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
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
by `GLocalDirectoryMonitorClass.is_supported()`. GIO uses
this extension point internally, to switch between its poll-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
`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.
using it for default handlers. Instead, the MIME handler mechanism is
used, together with `x-scheme-handler` pseudo-MIME-types.
- `G_NOTIFICATION_BACKEND_EXTENSION_POINT_NAME`. Allows to provide an
alternative implementation for sending notifications. Implementations of
this extension point must derive from the GNotificationBackend type. GIO
this extension point must derive from the `GNotificationBackend` type. GIO
contains implementations based on the freedesktop notification D-Bus
interface, the macOS Cocoa API, the gnome-shell D-Bus API, and the desktop
portal for this functionality.
- `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
alternative storage for [class@Gio.Settings]. Implementations of this extension point
must derive from the [class@Gio.SettingsBackend] 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
[iface@Gio.Proxy] 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
the [iface@Gio.TlsBackend] 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
this extension point must implement the [iface@Gio.NetworkMonitor]
interface. GIO contains implementations of this extension point that use
the netlink interface of the Linux kernel, the NetworkManager D-Bus interface
and the desktop portal for this functionality.
- `G_MEMORY_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
implementations for memory usage monitoring. Implementations of this
extension point must implement the GMemoryMonitorInterface interface.
extension point must implement the [iface@Gio.MemoryMonitor] interface.
GIO contains implementations of this extension point that use the
org.freedesktop.LowMemoryMonitor D-Bus interface, the Windows API and
`org.freedesktop.LowMemoryMonitor` D-Bus interface, the Windows API and
the desktop portal for this functionality.
- `G_POWER_PROFILE_MONITOR_EXTENSION_POINT_NAME`. Allows to provide
implementations for power usage monitoring. Implementations of this
extension point must implement the GPowerProfileMonitorInterface interface.
extension point must implement the [iface@Gio.PowerProfileMonitor] interface.
GIO contains implementations of this extension point that use the
net.hadess.PowerProfiles D-Bus interface and the desktop portal for
`net.hadess.PowerProfiles` D-Bus interface and the desktop portal for
this functionality.