|
Packit |
ae235b |
|
|
Packit |
ae235b |
<html>
|
|
Packit |
ae235b |
<head>
|
|
Packit |
ae235b |
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
|
Packit |
ae235b |
<title>Writing GIO applications: GIO Reference Manual</title>
|
|
Packit |
ae235b |
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
|
|
Packit |
ae235b |
<link rel="home" href="index.html" title="GIO Reference Manual">
|
|
Packit |
ae235b |
<link rel="up" href="pt01.html" title="Part I. GIO Overview">
|
|
Packit |
ae235b |
<link rel="prev" href="ch01.html" title="Introduction">
|
|
Packit |
ae235b |
<link rel="next" href="ch03.html" title="Compiling GIO applications">
|
|
Packit |
ae235b |
<meta name="generator" content="GTK-Doc V1.27 (XML mode)">
|
|
Packit |
ae235b |
<link rel="stylesheet" href="style.css" type="text/css">
|
|
Packit |
ae235b |
</head>
|
|
Packit |
ae235b |
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Writing GIO applications
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The information in the GLib documentation about writing GLib
|
|
Packit |
ae235b |
applications is generally applicable when writing GIO applications.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Threads
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
GDBus has its own private worker thread, so applications using
|
|
Packit |
ae235b |
GDBus have at least 3 threads. GIO makes heavy use of the concept
|
|
Packit |
ae235b |
of a <GTKDOCLINK HREF="g-main-context-push-thread-default">thread-default
|
|
Packit |
ae235b |
main context</GTKDOCLINK> to execute callbacks of asynchronous
|
|
Packit |
ae235b |
methods in the same context in which the operation was started.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Asynchronous Programming
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Many GIO functions come in two versions: synchronous and asynchronous,
|
|
Packit |
ae235b |
denoted by an _async suffix. It is important to use these
|
|
Packit |
ae235b |
appropriately: synchronous calls should not be used from
|
|
Packit |
ae235b |
within a main loop which is shared with other code, such as one in the
|
|
Packit |
ae235b |
application’s main thread. Synchronous calls block until they complete,
|
|
Packit |
ae235b |
and I/O operations can take noticeable amounts of time (even on ‘fast’
|
|
Packit |
ae235b |
SSDs). Blocking a main loop iteration while waiting for I/O means that
|
|
Packit |
ae235b |
other sources in the main loop will not be dispatched, such as input and
|
|
Packit |
ae235b |
redraw handlers for the application’s UI. This can cause the application
|
|
Packit |
ae235b |
to ‘freeze’ until I/O completes.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
A few self-contained groups of functions, such as code generated by
|
|
Packit |
ae235b |
gdbus-codegen,
|
|
Packit |
ae235b |
use a different convention: functions are asynchronous default, and it is
|
|
Packit |
ae235b |
the synchronous version which has a
|
|
Packit |
ae235b |
_sync
|
|
Packit |
ae235b |
suffix. Aside from naming differences, they should be treated the same
|
|
Packit |
ae235b |
way as functions following the normal convention above.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The asynchronous (_async) versions of functions return
|
|
Packit |
ae235b |
control to the caller immediately, after scheduling the I/O in the kernel
|
|
Packit |
ae235b |
and adding a callback for it to the main loop. This callback will be
|
|
Packit |
ae235b |
invoked when the operation has completed. From the callback, the paired
|
|
Packit |
ae235b |
_finish function should be called to retrieve the return
|
|
Packit |
ae235b |
value of the I/O operation, and any errors which occurred. For more
|
|
Packit |
ae235b |
information on using and implementing asynchronous functions, see
|
|
Packit |
ae235b |
GAsyncResult
|
|
Packit |
ae235b |
and GTask.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
By starting multiple asynchronous operations in succession, they will be
|
|
Packit |
ae235b |
executed in parallel (up to an arbitrary limit imposed by GIO’s internal
|
|
Packit |
ae235b |
worker thread pool).
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
The synchronous versions of functions can be used early in application
|
|
Packit |
ae235b |
startup when there is no main loop to block, for example to load initial
|
|
Packit |
ae235b |
configuration files. They can also be used for I/O on files which are
|
|
Packit |
ae235b |
guaranteed to be small and on the local disk. Note that the user’s home
|
|
Packit |
ae235b |
directory is not guaranteed to be on the local disk.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Security
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
When your program needs to carry out some privileged operation (say,
|
|
Packit |
ae235b |
create a new user account), there are various ways in which you can go
|
|
Packit |
ae235b |
about this:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Implement a daemon that offers the privileged operation. A convenient
|
|
Packit |
ae235b |
way to do this is as a D-Bus system-bus service. The daemon will probably
|
|
Packit |
ae235b |
need ways to check the identity and authorization of the caller before
|
|
Packit |
ae235b |
executing the operation. polkit is a framework that allows this.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Use a small helper that is executed with elevated privileges via
|
|
Packit |
ae235b |
pkexec. pkexec is a small program launcher that is part of polkit.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Use a small helper that is executed with elevated privileges by
|
|
Packit |
ae235b |
being suid root.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
None of these approaches is the clear winner, they all have their
|
|
Packit |
ae235b |
advantages and disadvantages.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
When writing code that runs with elevated privileges, it is important
|
|
Packit |
ae235b |
to follow some basic rules of secure programming. David Wheeler has an
|
|
Packit |
ae235b |
excellent book on this topic,
|
|
Packit |
ae235b |
Secure Programming for Linux and Unix HOWTO.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
When using GIO in code that runs with elevated privileges, you have to
|
|
Packit |
ae235b |
be careful. GIO has extension points whose implementations get loaded
|
|
Packit |
ae235b |
from modules (executable code in shared objects), which could allow
|
|
Packit |
ae235b |
an attacker to sneak his own code into your application by tricking it
|
|
Packit |
ae235b |
into loading the code as a module. However, GIO will never load modules
|
|
Packit |
ae235b |
from your home directory except when explictly asked to do so via an
|
|
Packit |
ae235b |
environment variable.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
In most cases, your helper program should be so small that you don't
|
|
Packit |
ae235b |
need GIO, whose APIs are largely designed to support full-blown desktop
|
|
Packit |
ae235b |
applications. If you can't resist the convenience of these APIs, here
|
|
Packit |
ae235b |
are some steps you should take:
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Clear the environment, e.g. using the clearenv()
|
|
Packit |
ae235b |
function.
|
|
Packit |
ae235b |
David Wheeler has a good explanation for why it is
|
|
Packit |
ae235b |
important to sanitize the environment.
|
|
Packit |
ae235b |
See Running GIO applications
|
|
Packit |
ae235b |
for a list of all environment variables affecting GIO. In particular,
|
|
Packit |
ae235b |
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.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Don't use GVfs, by setting GIO_USE_VFS=local in the environment.
|
|
Packit |
ae235b |
The reason to avoid GVfs in security-sensitive programs is that it uses
|
|
Packit |
ae235b |
many libraries which have not necessarily been audited for security problems.
|
|
Packit |
ae235b |
Gvfs is also heavily distributed and relies on a session bus to be present.
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
|
|
Packit |
ae235b |
Generated by GTK-Doc V1.27
|
|
Packit |
ae235b |
</body>
|
|
Packit |
ae235b |
</html>
|