diff options
Diffstat (limited to 'docs/reference/glib/programming.xml')
| -rw-r--r-- | docs/reference/glib/programming.xml | 65 |
1 files changed, 61 insertions, 4 deletions
diff --git a/docs/reference/glib/programming.xml b/docs/reference/glib/programming.xml index 52df907e8..9efa19d33 100644 --- a/docs/reference/glib/programming.xml +++ b/docs/reference/glib/programming.xml @@ -20,6 +20,47 @@ General considerations when programming with GLib <title>Writing GLib Applications</title> <refsect2> +<title>Memory Allocations</title> + +<para> +Unless otherwise specified, all functions which allocate memory in GLib will +abort the process if heap allocation fails. This is because it is too hard to +recover from allocation failures in any non-trivial program and, in particular, +to test all the allocation failure code paths. +</para> +</refsect2> + +<refsect2> +<title>UTF-8 and String Encoding</title> + +<para> +All GLib, GObject and GIO functions accept and return strings in +<ulink url="https://en.wikipedia.org/wiki/UTF-8">UTF-8 encoding</ulink> +unless otherwise specified. +</para> + +<para> +Input strings to function calls are <emphasis>not</emphasis> checked to see if +they are valid UTF-8: it is the application developer’s responsibility to +validate input strings at the time of input, either at the program or library +boundary, and to only use valid UTF-8 string constants in their application. +If GLib were to UTF-8 validate all string inputs to all functions, there would +be a significant drop in performance. +</para> + +<para>Similarly, output strings from functions are guaranteed to be in UTF-8, +and this does not need to be validated by the calling function. If a function +returns invalid UTF-8 (and is not documented as doing so), that’s a bug. +</para> + +<para> +See <link linkend='g-utf8-validate'><function>g_utf8_validate()</function></link> +and <link linkend='g-utf8-make-valid'><function>g_utf8_make_valid()</function></link> +for validating UTF-8 input. +</para> +</refsect2> + +<refsect2> <title>Threads</title> <para> @@ -35,15 +76,22 @@ will always have at least 2 threads. </para> <para> +In particular, this means that programs must only use +<ulink url="man:signal-safety(7)">async-signal-safe functions</ulink> between +calling <function>fork()</function> and <function>exec()</function>, even if +they haven’t explicitly spawned another thread yet. +</para> + +<para> See the sections on <link linkend="glib-Threads">threads</link> and -<link linkend="glib-Thread-Pools">threadpools</link> for GLib APIs that +<link linkend="glib-Thread-Pools">thread pools</link> for GLib APIs that support multithreaded applications. </para> </refsect2> <refsect2> -<title>Security</title> +<title>Security and setuid use</title> <para> When writing code that runs with elevated privileges, it is important @@ -56,8 +104,17 @@ excellent book on this topic, When it comes to GLib and its associated libraries, GLib and GObject are generally fine to use in code that runs with elevated privileges; they don't load modules (executable code in shared objects) -or run other programs 'behind your back'. GIO has to be used -carefully in privileged programs, see the <ulink url="http://developer.gnome.org/gio/stable/ch02.html">GIO documentation</ulink> for details. +or run other programs ‘behind your back’. GIO, however, is not designed to be +used in privileged programs, either ones which are spawned by a privileged +process, or ones which are run with a setuid bit set. +</para> + +<para> +setuid programs should always reset their environment to contain only +known-safe values before calling into non-trivial libraries such as GIO. This +reduces the risk of an attacker-controlled environment variable being used to +get a privileged GIO process to run arbitrary code via loading a GIO module or +similar. </para> </refsect2> |