diff options
Diffstat (limited to 'docs/reference/glib')
| -rw-r--r-- | docs/reference/glib/building.xml | 14 | ||||
| -rw-r--r-- | docs/reference/glib/glib-docs.xml | 168 | ||||
| -rw-r--r-- | docs/reference/glib/glib-sections.txt.in | 11 | ||||
| -rw-r--r-- | docs/reference/glib/meson.build | 58 | ||||
| -rw-r--r-- | docs/reference/glib/programming.xml | 65 |
5 files changed, 193 insertions, 123 deletions
diff --git a/docs/reference/glib/building.xml b/docs/reference/glib/building.xml index dd1a4495b..edfdfbea3 100644 --- a/docs/reference/glib/building.xml +++ b/docs/reference/glib/building.xml @@ -22,15 +22,15 @@ is thus: <literallayout> - <userinput>meson _build</userinput> - <userinput>ninja -C _build</userinput> - <userinput>ninja -C _build install</userinput> + <userinput>meson setup _build</userinput> + <userinput>meson compile -C _build</userinput> + <userinput>meson install -C _build</userinput> </literallayout> On FreeBSD: <literallayout> - <userinput>env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" meson -Dxattr=false -Dinstalled_tests=true -Db_lundef=false _build</userinput> - <userinput>ninja -C _build</userinput> + <userinput>env CPPFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib -Wl,--disable-new-dtags" meson setup -Dxattr=false -Dinstalled_tests=true -Db_lundef=false _build</userinput> + <userinput>meson compile -C _build</userinput> </literallayout> </para> @@ -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-docs.xml b/docs/reference/glib/glib-docs.xml index e378fd956..5bf2e5cda 100644 --- a/docs/reference/glib/glib-docs.xml +++ b/docs/reference/glib/glib-docs.xml @@ -90,8 +90,8 @@ <xi:include href="xml/gregex.xml" /> <xi:include href="regex-syntax.xml" /> <xi:include href="xml/markup.xml" /> - <xi:include href="xml/keyfile.xml" /> - <xi:include href="xml/bookmarkfile.xml" /> + <xi:include href="xml/gkeyfile.xml" /> + <xi:include href="xml/gbookmarkfile.xml" /> <xi:include href="xml/testing.xml" /> <xi:include href="xml/gunix.xml" /> <xi:include href="xml/windows.xml" /> @@ -145,166 +145,170 @@ <xi:include href="gtester-report.xml" /> </chapter> - <index id="api-index-full"> + <chapter id="api-index-full"> <title>Index</title> <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-deprecated" role="deprecated"> + </chapter> + <chapter id="api-index-deprecated" role="deprecated"> <title>Index of deprecated symbols</title> <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-2" role="2.2"> + </chapter> + <chapter id="api-index-2-2" role="2.2"> <title>Index of new symbols in 2.2</title> <xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-4" role="2.4"> + </chapter> + <chapter id="api-index-2-4" role="2.4"> <title>Index of new symbols in 2.4</title> <xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-6" role="2.6"> + </chapter> + <chapter id="api-index-2-6" role="2.6"> <title>Index of new symbols in 2.6</title> <xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-8" role="2.8"> + </chapter> + <chapter id="api-index-2-8" role="2.8"> <title>Index of new symbols in 2.8</title> <xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-10" role="2.10"> + </chapter> + <chapter id="api-index-2-10" role="2.10"> <title>Index of new symbols in 2.10</title> <xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-12" role="2.12"> + </chapter> + <chapter id="api-index-2-12" role="2.12"> <title>Index of new symbols in 2.12</title> <xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-14" role="2.14"> + </chapter> + <chapter id="api-index-2-14" role="2.14"> <title>Index of new symbols in 2.14</title> <xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-16" role="2.16"> + </chapter> + <chapter id="api-index-2-16" role="2.16"> <title>Index of new symbols in 2.16</title> <xi:include href="xml/api-index-2.16.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-18" role="2.18"> + </chapter> + <chapter id="api-index-2-18" role="2.18"> <title>Index of new symbols in 2.18</title> <xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-20" role="2.20"> + </chapter> + <chapter id="api-index-2-20" role="2.20"> <title>Index of new symbols in 2.20</title> <xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-22" role="2.22"> + </chapter> + <chapter id="api-index-2-22" role="2.22"> <title>Index of new symbols in 2.22</title> <xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-24" role="2.24"> + </chapter> + <chapter id="api-index-2-24" role="2.24"> <title>Index of new symbols in 2.24</title> <xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-26" role="2.26"> + </chapter> + <chapter id="api-index-2-26" role="2.26"> <title>Index of new symbols in 2.26</title> <xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-28" role="2.28"> + </chapter> + <chapter id="api-index-2-28" role="2.28"> <title>Index of new symbols in 2.28</title> <xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-30" role="2.30"> + </chapter> + <chapter id="api-index-2-30" role="2.30"> <title>Index of new symbols in 2.30</title> <xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-32" role="2.32"> + </chapter> + <chapter id="api-index-2-32" role="2.32"> <title>Index of new symbols in 2.32</title> <xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-34" role="2.34"> + </chapter> + <chapter id="api-index-2-34" role="2.34"> <title>Index of new symbols in 2.34</title> <xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-36" role="2.36"> + </chapter> + <chapter id="api-index-2-36" role="2.36"> <title>Index of new symbols in 2.36</title> <xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-38" role="2.38"> + </chapter> + <chapter id="api-index-2-38" role="2.38"> <title>Index of new symbols in 2.38</title> <xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-40" role="2.40"> + </chapter> + <chapter id="api-index-2-40" role="2.40"> <title>Index of new symbols in 2.40</title> <xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-42" role="2.42"> + </chapter> + <chapter id="api-index-2-42" role="2.42"> <title>Index of new symbols in 2.42</title> <xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-44" role="2.44"> + </chapter> + <chapter id="api-index-2-44" role="2.44"> <title>Index of new symbols in 2.44</title> <xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-46" role="2.46"> + </chapter> + <chapter id="api-index-2-46" role="2.46"> <title>Index of new symbols in 2.46</title> <xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-48" role="2.48"> + </chapter> + <chapter id="api-index-2-48" role="2.48"> <title>Index of new symbols in 2.48</title> <xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-50" role="2.50"> + </chapter> + <chapter id="api-index-2-50" role="2.50"> <title>Index of new symbols in 2.50</title> <xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-52" role="2.52"> + </chapter> + <chapter id="api-index-2-52" role="2.52"> <title>Index of new symbols in 2.52</title> <xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-54" role="2.54"> + </chapter> + <chapter id="api-index-2-54" role="2.54"> <title>Index of new symbols in 2.54</title> <xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-56" role="2.56"> + </chapter> + <chapter id="api-index-2-56" role="2.56"> <title>Index of new symbols in 2.56</title> <xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-58" role="2.58"> + </chapter> + <chapter id="api-index-2-58" role="2.58"> <title>Index of new symbols in 2.58</title> <xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-60" role="2.60"> + </chapter> + <chapter id="api-index-2-60" role="2.60"> <title>Index of new symbols in 2.60</title> <xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-62" role="2.62"> + </chapter> + <chapter id="api-index-2-62" role="2.62"> <title>Index of new symbols in 2.62</title> <xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-64" role="2.64"> + </chapter> + <chapter id="api-index-2-64" role="2.64"> <title>Index of new symbols in 2.64</title> <xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-66" role="2.66"> + </chapter> + <chapter id="api-index-2-66" role="2.66"> <title>Index of new symbols in 2.66</title> <xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-68" role="2.68"> + </chapter> + <chapter id="api-index-2-68" role="2.68"> <title>Index of new symbols in 2.68</title> <xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-70" role="2.70"> + </chapter> + <chapter id="api-index-2-70" role="2.70"> <title>Index of new symbols in 2.70</title> <xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-72" role="2.72"> + </chapter> + <chapter id="api-index-2-72" role="2.72"> <title>Index of new symbols in 2.72</title> <xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-74" role="2.74"> + </chapter> + <chapter id="api-index-2-74" role="2.74"> <title>Index of new symbols in 2.74</title> <xi:include href="xml/api-index-2.74.xml"><xi:fallback /></xi:include> - </index> - <index id="api-index-2-76" role="2.76"> + </chapter> + <chapter id="api-index-2-76" role="2.76"> <title>Index of new symbols in 2.76</title> <xi:include href="xml/api-index-2.76.xml"><xi:fallback /></xi:include> - </index> + </chapter> + <chapter id="api-index-2-78" role="2.78"> + <title>Index of new symbols in 2.78</title> + <xi:include href="xml/api-index-2.78.xml"><xi:fallback /></xi:include> + </chapter> <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include> diff --git a/docs/reference/glib/glib-sections.txt.in b/docs/reference/glib/glib-sections.txt.in index 3703198bd..5258544a3 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 @@ -2063,7 +2064,7 @@ GErrorType <SECTION> <TITLE>Key-value file parser</TITLE> -<FILE>keyfile</FILE> +<FILE>gkeyfile</FILE> GKeyFile G_KEY_FILE_ERROR GKeyFileError @@ -2158,7 +2159,7 @@ g_key_file_get_type <SECTION> <TITLE>Bookmark file parser</TITLE> -<FILE>bookmarkfile</FILE> +<FILE>gbookmarkfile</FILE> GBookmarkFile G_BOOKMARK_FILE_ERROR GBookmarkFileError @@ -2624,6 +2625,7 @@ g_str_hash <FILE>strings</FILE> GString g_string_new +g_string_new_take g_string_new_len g_string_sized_new g_string_assign @@ -3129,6 +3131,7 @@ g_utf8_strchr g_utf8_strrchr g_utf8_strreverse g_utf8_substring +g_utf8_truncate_middle g_utf8_validate g_utf8_validate_len g_utf8_make_valid @@ -3356,6 +3359,7 @@ g_test_trap_assert_stdout_unmatched g_test_trap_assert_stderr g_test_trap_assert_stderr_unmatched g_test_trap_fork +g_test_disable_crash_reporting g_test_rand_bit g_test_rand_int @@ -3401,6 +3405,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 +3694,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> |