docs/reference/gio/html/ch02.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Writing GIO applications: GIO Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GIO Reference Manual">
<link rel="up" href="pt01.html" title="Part I. GIO Overview">
<link rel="prev" href="ch01.html" title="Introduction">
<link rel="next" href="ch03.html" title="Compiling GIO applications">
<meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="pt01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ch01.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="ch03.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="id-1.3.3"></a>Writing GIO applications</h2></div></div></div>
<p>
      The information in the GLib <a class="ulink" href="http://developer.gnome.org/glib/stable/glib-programming.html" target="_top">documentation</a> about writing GLib
      applications is generally applicable when writing GIO applications.
    </p>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.3.3.3"></a>Threads</h2></div></div></div>
<p>
       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 <GTKDOCLINK HREF="g-main-context-push-thread-default">thread-default
       main context</GTKDOCLINK> to execute callbacks of asynchronous
       methods in the same context in which the operation was started.
    </p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="async-programming"></a>Asynchronous Programming</h2></div></div></div>
<p>
      Many GIO functions come in two versions: synchronous and asynchronous,
      denoted by an <code class="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.
    </p>
<p>
      A few self-contained groups of functions, such as code generated by
      <span class="application">gdbus-codegen</span>,
      use a different convention: functions are asynchronous default, and it is
      the <span class="emphasis"><em>synchronous</em></span> version which has a
      <code class="code">_sync</code>
      suffix. Aside from naming differences, they should be treated the same
      way as functions following the normal convention above.
    </p>
<p>
      The asynchronous (<code class="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 class="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
      <a class="link" href="GAsyncResult.html#GAsyncResult.description" title="Description"><span class="type">GAsyncResult</span></a>
      and <a class="link" href="GTask.html#GTask.description" title="Description"><span class="type">GTask</span></a>.
    </p>
<p>
      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).
    </p>
<p>
      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.
    </p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.3.3.5"></a>Security</h2></div></div></div>
<p>
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:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
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. <a class="ulink" href="http://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html" target="_top">polkit</a> is a framework that allows this.
</p></li>
<li class="listitem"><p>
Use a small helper that is executed with elevated privileges via
pkexec. <a class="ulink" href="http://www.freedesktop.org/software/polkit/docs/latest/pkexec.1.html" target="_top">pkexec</a> is a small program launcher that is part of polkit.
</p></li>
<li class="listitem"><p>
Use a small helper that is executed with elevated privileges by
being suid root.
</p></li>
</ul></div>
<p>
None of these approaches is the clear winner, they all have their
advantages and disadvantages.
</p>
<p>
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,
<a class="ulink" href="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html" target="_top">Secure Programming for Linux and Unix HOWTO</a>.
</p>
<p>
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 explictly asked to do so via an
environment variable.
</p>
<p>
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:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>
Clear the environment, e.g. using the <code class="function"><code class="function">clearenv()</code></code>
function.
David Wheeler has a good <a class="ulink" href="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/environment-variables.html" target="_top">explanation</a> for why it is
important to sanitize the environment.
See <a class="xref" href="running-gio-apps.html" title="Running GIO applications"><i>Running GIO applications</i></a>
for a list of all environment variables affecting GIO. In particular,
<code class="envar">PATH</code> (used to locate binaries), <code class="envar">GIO_EXTRA_MODULES</code> (used to locate loadable modules) and <code class="envar">DBUS_{SYSTEM,SESSION}_BUS_ADDRESS</code> (used to locate the D-Bus system and session bus) are important.
</p></li>
<li class="listitem"><p>
Don't use GVfs, by setting <code class="envar">GIO_USE_VFS=local</code> 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.
</p></li>
</ul></div>
<p>
</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25.1</div>
</body>
</html>