4 files changed, 97 insertions, 34 deletions

diff --git a/docs/reference/glib/building.xml b/docs/reference/glib/building.xml
index dd1a4495b..2ae52e8dd 100644
--- a/docs/reference/glib/building.xml
+++ b/docs/reference/glib/building.xml
@@ -49,7 +49,7 @@
       aliasing and cannot be guaranteed to work.
     </para>
     <para>
-      The GTK+ documentation contains
+      The GTK documentation contains
       <ulink url="https://developer.gnome.org/gtk3/stable/gtk-building.html">further details</ulink>
       about the build process and ways to influence it.
     </para>
@@ -60,7 +60,7 @@
       Before you can compile the GLib library, you need to have
       various other tools and libraries installed on your system.
       If you are building from a release archive, you will need
-      <ulink url="https://wiki.gnome.org/Projects/GLib/CompilerRequirements">a compliant C toolchain</ulink>,
+      <ulink url="https://gitlab.gnome.org/GNOME/glib/-/blob/main/docs/toolchain-requirements.md">a compliant C toolchain</ulink>,
       <application>Meson</application>, and <application>pkg-config</application>;
       the requirements are the same when building from a Git repository clone
       of GLib.
diff --git a/docs/reference/glib/glib-sections.txt.in b/docs/reference/glib/glib-sections.txt.in
index 3703198bd..60e87af5b 100644
--- a/docs/reference/glib/glib-sections.txt.in
+++ b/docs/reference/glib/glib-sections.txt.in
@@ -586,6 +586,7 @@ g_timeout_add_once
 g_timeout_add_full
 g_timeout_add_seconds
 g_timeout_add_seconds_full
+g_timeout_add_seconds_once
 
 <SUBSECTION>
 g_idle_source_new
@@ -3401,6 +3402,7 @@ g_test_trap_assertions
 g_assertion_message
 g_assertion_message_expr
 g_assertion_message_cmpstr
+g_assertion_message_cmpint
 g_assertion_message_cmpnum
 g_assertion_message_error
 g_test_assert_expected_messages_internal
@@ -3689,12 +3691,14 @@ g_ref_count_init
 g_ref_count_inc
 g_ref_count_dec
 g_ref_count_compare
+G_REF_COUNT_INIT
 <SUBSECTION>
 gatomicrefcount
 g_atomic_ref_count_init
 g_atomic_ref_count_inc
 g_atomic_ref_count_dec
 g_atomic_ref_count_compare
+G_ATOMIC_REF_COUNT_INIT
 </SECTION>
 
 <SECTION>
diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build
index 114de49da..3cfff2f0b 100644
--- a/docs/reference/glib/meson.build
+++ b/docs/reference/glib/meson.build
@@ -113,35 +113,37 @@ if get_option('man')
   endforeach
 endif
 
-# GVariant specification is currently standalone
-rst2html5 = find_program('rst2html5', 'rst2html5.py', required: false)
+if get_option('gtk_doc')
+  # GVariant specification is currently standalone
+  rst2html5 = find_program('rst2html5', 'rst2html5.py', required: false)
 
-if rst2html5.found()
-  spec_path = glib_datadir / 'doc' / 'glib-2.0'
+  if rst2html5.found()
+    spec_path = glib_datadir / 'doc' / 'glib-2.0'
 
-  figures = files(
-    'gvariant-byte-boundaries.svg',
-    'gvariant-integer-and-string-structure.svg',
-    'gvariant-integer-array.svg',
-    'gvariant-string-array.svg',
-  )
+    figures = files(
+      'gvariant-byte-boundaries.svg',
+      'gvariant-integer-and-string-structure.svg',
+      'gvariant-integer-array.svg',
+      'gvariant-string-array.svg',
+    )
 
-  custom_target('gvariant-specification-1.0',
-    input: 'gvariant-specification-1.0.rst',
-    output: 'gvariant-specification-1.0.html',
-    command: [
-      rst2html5,
-      '@INPUT@',
-    ],
-    capture: true,
-    install: true,
-    install_dir: spec_path,
-    install_tag: 'doc',
-    depend_files: figures,
-  )
+    custom_target('gvariant-specification-1.0',
+      input: 'gvariant-specification-1.0.rst',
+      output: 'gvariant-specification-1.0.html',
+      command: [
+        rst2html5,
+        '@INPUT@',
+      ],
+      capture: true,
+      install: true,
+      install_dir: spec_path,
+      install_tag: 'doc',
+      depend_files: figures,
+    )
 
-  install_data(figures,
-    install_dir : spec_path,
-    install_tag : 'doc',
-  )
-endif
\ No newline at end of file
+    install_data(figures,
+      install_dir : spec_path,
+      install_tag : 'doc',
+    )
+  endif
+endif
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>