| <!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> |