luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-03-27 18:10:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Convert the programming page to Markdown

Browse Source 
Signed-off-by: Philip Withnall <pwithnall@gnome.org>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-11-23 18:17:14 +00:00
parent 59a4a239a1
commit ed5c17018f
4 changed files with 73 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/glib.toml.in
View File

@ -44,6 +44,7 @@ content_files = [
"compiling.md",
"cross-compiling.md",
"running.md",
"programming.md",
"gvariant-format-strings.md",
"gvariant-text-format.md",

1
docs/reference/glib/meson.build
View File

@ -174,6 +174,7 @@ expand_content_files = [
'goption.md',
'host-utils.md',
'data-structures.md',
'programming.md',
'shell.md',
'spawn.md',
'string-utils.md',

71
docs/reference/glib/programming.md Normal file
View File

@ -0,0 +1,71 @@
Title: Writing GLib Applications
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Red Hat, Inc.
SPDX-FileCopyrightText: 2023 Endless OS Foundation, LLC
# Writing GLib Applications
## Memory Allocations
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.
## UTF-8 and String Encoding
All GLib, GObject and GIO functions accept and return strings in
[UTF-8 encoding](https://en.wikipedia.org/wiki/UTF-8) unless otherwise
specified.
Input strings to function calls are *not* 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.
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.
See [func@GLib.utf8_validate] and [func@GLib.utf8_make_valid] for validating
UTF-8 input.
## Threads
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 *same* data structure, they must use a
lock to synchronize their operation.
GLib creates a worker thread for its own purposes so GLib applications
will always have at least 2 threads.
In particular, this means that programs must only use
[async-signal-safe functions](man:signal-safety(7)) between
calling [`fork()`](man:fork(2)) and [`exec()`](man:exec(3)), even if
they haven’t explicitly spawned another thread yet.
See the sections on [threads](threads.html) and [struct@GLib.ThreadPool] for
GLib APIs that support multithreaded applications.
## Security and setuid Use
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,
[Secure Programming for Linux and Unix HOWTO](http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html).
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.
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.

124
docs/reference/glib/programming.xml
View File

@ -1,124 +0,0 @@
<?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>