1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-programming">
<refmeta>
<refentrytitle>Writing GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Writing GLib Applications</refname>
<refpurpose>
General considerations when programming with GLib
</refpurpose>
</refnamediv>
<refsect1>
<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>
The general policy of GLib is that all functions are invisibly threadsafe
with the exception of data structure manipulation functions, where, if
you have two threads manipulating the <emphasis>same</emphasis> data
structure, they must use a lock to synchronize their operation.
</para>
<para>
GLib creates a worker thread for its own purposes so GLib applications
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">thread pools</link> for GLib APIs that
support multithreaded applications.
</para>
</refsect2>
<refsect2>
<title>Security and setuid use</title>
<para>
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,
<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
</para>
<para>
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, 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>
</refsect1>
</refentry>
|
