evin/pkg-glib2.0
3
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Import Upstream version 2.72.4

Browse source
This commit is contained in:
evinadmin 2023-07-04 11:23:22 +02:00
commit 4ef3ff9793
2003 changed files with 1332420 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

134
docs/reference/glib/Sorted_binary_tree_breadth-first_traversal.svg Normal file
View file

@ -0,0 +1,134 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 16.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
width="266px" height="212px" viewBox="0 0 266 212" enable-background="new 0 0 266 212" xml:space="preserve">
<g>
<g>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="27.23" y1="23.192" x2="29.23" y2="23.192"/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9562,3.9562" x1="33.187" y1="23.192" x2="236.932" y2="23.192"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,23.192 240.91,23.192
238.97,23.677 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="24.646" x2="27.971" y2="76.427"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,76.912 24.095,77.396
26.095,77.396 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="77.396" x2="236.902" y2="77.396"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,77.396 240.91,77.396
238.97,77.881 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="78.85" x2="27.971" y2="130.631"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,131.114 24.095,131.6
26.095,131.6 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0154,4.0154" x1="30.11" y1="131.6" x2="236.902" y2="131.6"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="238.91,131.6 240.91,131.6
238.97,132.085 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="3.9907,3.9907" x1="235.099" y1="133.053" x2="27.971" y2="184.835"/>
<polyline fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" points="26.035,185.318 24.095,185.804
26.095,185.804 "/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" stroke-dasharray="4.0086,4.0086" x1="30.104" y1="185.804" x2="228.53" y2="185.804"/>
<line fill="none" stroke="#000000" stroke-width="2" stroke-miterlimit="10" x1="230.534" y1="185.804" x2="232.534" y2="185.804"/>
<g>
<rect x="24.095" y="19.892" width="6.602" height="6.602"/>
</g>
<g>
<path d="M238.569,185.804c-2.84,1.054-6.363,2.852-8.548,4.756l1.721-4.756l-1.721-4.755
C232.206,182.953,235.729,184.751,238.569,185.804z"/>
</g>
</g>
</g>
<g id="graph0">
<title>sorted_binary_tree</title>
<g id="node1">
<title>C</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="185.804" rx="18.067" ry="18.067"/>
<text transform="matrix(1 0 0 1 55.5435 190.8223)" font-family="'Times-Roman'" font-size="14.0528">C</text>
</g>
<g id="node2">
<title>E</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="185.804" rx="18.067" ry="18.067"/>
<text transform="matrix(1 0 0 1 128.21 190.8223)" font-family="'Times-Roman'" font-size="14.0528">E</text>
</g>
<g id="node3">
<title>H</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="185.804" rx="17.064" ry="18.067"/>
<text transform="matrix(1 0 0 1 199.6992 190.8223)" font-family="'Times-Roman'" font-size="14.0528">H</text>
</g>
<g id="node4">
<title>A</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="24.094" cy="131.6" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 19.02 136.6191)" font-family="'Times-Roman'" font-size="14.0528">A</text>
</g>
<g id="node5">
<title>D</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="96.366" cy="131.6" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 91.292 136.6191)" font-family="'Times-Roman'" font-size="14.0528">D</text>
</g>
<g id="edge6">
<title>D-&gt;C</title>
<path fill="none" stroke="#000000" d="M86.328,147.66c-3.011,4.016-7.026,9.034-10.038,14.053"/>
<polygon stroke="#000000" points="78.298,164.725 70.268,170.747 73.279,160.709 "/>
</g>
<g id="edge8">
<title>D-&gt;E</title>
<path fill="none" stroke="#000000" d="M106.404,147.66c3.011,4.016,7.026,9.034,10.038,14.053"/>
<polygon stroke="#000000" points="119.453,160.709 122.464,170.747 114.434,164.725 "/>
</g>
<g id="node6">
<title>I</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="240.909" cy="131.6" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 238.5693 136.6191)" font-family="'Times-Roman'" font-size="14.0528">I</text>
</g>
<g id="edge12">
<title>I-&gt;H</title>
<path fill="none" stroke="#000000" d="M230.871,146.656c-3.011,5.02-6.021,10.038-10.037,15.057"/>
<polygon stroke="#000000" points="223.846,163.721 214.812,169.743 217.822,159.705 "/>
</g>
<g id="node7">
<title>B</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="60.23" cy="77.396" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 55.5435 82.415)" font-family="'Times-Roman'" font-size="14.0528">B</text>
</g>
<g id="edge3">
<title>B-&gt;A</title>
<path fill="none" stroke="#000000" d="M50.192,92.453c-3.011,5.019-6.022,10.038-10.038,15.057"/>
<polygon stroke="#000000" points="43.166,109.518 34.132,115.539 37.144,105.502 "/>
</g>
<g id="edge5">
<title>B-&gt;D</title>
<path fill="none" stroke="#000000" d="M70.268,92.453c3.011,5.019,6.022,10.038,10.038,15.057"/>
<polygon stroke="#000000" points="83.317,105.502 86.328,115.539 77.294,109.518 "/>
</g>
<g id="node8">
<title>G</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="204.773" cy="77.396" rx="17.064" ry="18.068"/>
<text transform="matrix(1 0 0 1 199.6992 82.415)" font-family="'Times-Roman'" font-size="14.0528">G</text>
</g>
<g id="edge11">
<title>G-&gt;I</title>
<path fill="none" stroke="#000000" d="M214.812,93.457c3.011,4.015,7.026,9.034,10.038,14.053"/>
<polygon stroke="#000000" points="227.86,106.506 230.871,116.543 222.842,110.521 "/>
</g>
<g id="node9">
<title>F</title>
<ellipse fill="#FFFFFF" stroke="#000000" cx="132.502" cy="23.192" rx="18.068" ry="18.068"/>
<text transform="matrix(1 0 0 1 128.5942 28.2109)" font-family="'Times-Roman'" font-size="14.0528">F</text>
</g>
<g id="edge2">
<title>F-&gt;B</title>
<path fill="none" stroke="#000000" d="M117.445,34.234c-11.042,8.03-23.087,17.064-34.128,26.098"/>
<polygon stroke="#000000" points="85.325,63.343 75.287,66.354 81.31,57.321 "/>
</g>
<g id="edge10">
<title>F-&gt;G</title>
<path fill="none" stroke="#000000" d="M147.559,34.234c11.041,8.03,23.087,17.064,34.129,26.098"/>
<polygon stroke="#000000" points="183.694,57.321 189.717,66.354 179.68,63.343 "/>
</g>
</g>
</svg>
Side by side

After

Width:  |  Height:  |  Size: 7.1 KiB

753
docs/reference/glib/Sorted_binary_tree_inorder.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

750
docs/reference/glib/Sorted_binary_tree_postorder.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

750
docs/reference/glib/Sorted_binary_tree_preorder.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 36 KiB

365
docs/reference/glib/building.xml Normal file
View file

@ -0,0 +1,365 @@
<?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-building">
<refmeta>
<refentrytitle>Compiling the GLib package</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling the GLib Package</refname>
<refpurpose>How to compile GLib itself</refpurpose>
</refnamediv>
<refsect1 id="building">
<title>Building the Library on UNIX</title>
<para>
On UNIX, GLib uses the standard <application>Meson</application> build
system. The normal sequence for compiling and installing the GLib library
is thus:
<literallayout>
<userinput>meson _build</userinput>
<userinput>ninja -C _build</userinput>
<userinput>ninja -C _build install</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 -Diconv=external -Db_lundef=false _build</userinput>
<userinput>ninja -C _build</userinput>
</literallayout>
</para>
<para>
The standard options provided by <application>Meson</application> may be
passed to the <command>meson</command> command. Please see the
<application>Meson</application> documentation or run
<command>meson configure --help</command> for information about
the standard options.
</para>
<para>
GLib is compiled with
<ulink url="https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html#index-fstrict-aliasing">strict aliasing</ulink>
disabled. It is strongly recommended that this is not re-enabled by
overriding the compiler flags, as GLib has not been tested with strict
aliasing and cannot be guaranteed to work.
</para>
<para>
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>
</refsect1>
<refsect1 id="dependencies">
<title>Dependencies</title>
<para>
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>,
<application>Meson</application>, and <application>pkg-config</application>;
the requirements are the same when building from a Git repository clone
of GLib.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
is a tool for tracking the compilation flags needed for
libraries that are used by the GLib library. (For each
library, a small <literal>.pc</literal> text file is
installed in a standard location that contains the compilation
flags needed for that library along with version number
information).
</para>
</listitem>
</itemizedlist>
<para>
A UNIX build of GLib requires that the system implements at
least the original 1990 version of POSIX. Beyond this, it
depends on a number of other libraries.
</para>
<itemizedlist>
<listitem>
<para>
The <ulink url="http://www.gnu.org/software/libiconv/">GNU
libiconv library</ulink> is needed to build GLib if your
system doesn't have the <function>iconv()</function>
function for doing conversion between character
encodings. Most modern systems should have
<function>iconv()</function>, however many older systems lack
an <function>iconv()</function> implementation. On such systems,
you must install the libiconv library. This can be found at:
<ulink url="http://www.gnu.org/software/libiconv">http://www.gnu.org/software/libiconv</ulink>.
</para>
<para>
If your system has an <function>iconv()</function> implementation but
you want to use libiconv instead, you can pass the
<option>-Diconv=gnu</option> option to <command>meson</command>. This
forces libiconv to be used.
</para>
<para>
Note that if you have libiconv installed in your default include
search path (for instance, in <filename>/usr/local/</filename>), but
don't enable it, you will get an error while compiling GLib because
the <filename>iconv.h</filename> that libiconv installs hides the
system iconv.
</para>
<para>
If you are using the native iconv implementation on Solaris
instead of libiconv, you'll need to make sure that you have
the converters between locale encodings and UTF-8 installed.
At a minimum you'll need the SUNWuiu8 package. You probably
should also install the SUNWciu8, SUNWhiu8, SUNWjiu8, and
SUNWkiu8 packages.
</para>
<para>
The native iconv on Compaq Tru64 doesn't contain support for
UTF-8, so you'll need to use GNU libiconv instead. (When
using GNU libiconv for GLib, you'll need to use GNU libiconv
for GNU gettext as well.) This probably applies to related
operating systems as well.
</para>
</listitem>
<listitem>
<para>
Python 3.5 or newer is required. Your system Python must
conform to <ulink
url="https://www.python.org/dev/peps/pep-0394/">PEP 394
</ulink>
For FreeBSD, this means that the
<literal>lang/python3</literal> port must be installed.
</para>
</listitem>
<listitem>
<para>
The libintl library from the <ulink
url="http://www.gnu.org/software/gettext">GNU gettext
package</ulink> is needed if your system doesn't have the
<function>gettext()</function> functionality for handling
message translation databases.
</para>
</listitem>
<listitem>
<para>
A thread implementation is needed. The thread support in GLib
can be based upon POSIX threads or win32 threads.
</para>
</listitem>
<listitem>
<para>
GRegex uses the <ulink url="http://www.pcre.org/">PCRE library</ulink>
for regular expression matching. The system version of PCRE is used,
unless not available (which is the case on Android), in which case a
fallback subproject is used.
</para>
</listitem>
<listitem>
<para>
The optional extended attribute support in GIO requires the
<function>getxattr()</function> family of functions that may be
provided by the C library or by the standalone libattr library. To
build GLib without extended attribute support, use the
<option>-Dxattr=false</option> option.
</para>
</listitem>
<listitem>
<para>
The optional SELinux support in GIO requires libselinux.
To build GLib without SELinux support, use the
<option>-Dselinux=disabled</option> option.
</para>
</listitem>
<listitem>
<para>
The optional support for DTrace requires the
<filename>sys/sdt.h</filename> header, which is provided
by SystemTap on Linux. To build GLib without DTrace, use
the <option>-Ddtrace=false</option> option.
</para>
</listitem>
<listitem>
<para>
The optional support for
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink>
can be disabled with the <option>-Dsystemtap=false</option>
option. Additionally, you can control the location
where GLib installs the SystemTap probes, using the
<option>-Dtapset_install_dir=DIR</option> option.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1 id="extra-configuration-options">
<title>Extra Configuration Options</title>
<para>
In addition to the normal options, these additional ones are supported
when configuring the GLib library:
</para>
<formalpara>
<title><option>--buildtype</option></title>
<para>
This is a standard <application>Meson</application> option which
specifies how much debugging and optimization to enable. If the build
type starts with <literal>debug</literal>,
<literal>G_ENABLE_DEBUG</literal> will be defined and GLib will be built
with additional debug code enabled.
</para>
<para>
If the build type is <literal>plain</literal>, GLib will not enable any
optimization or debug options by default, and will leave it entirely to
the user to choose their options. To build with the options recommended
by GLib developers, choose <literal>release</literal>.
</para>
</formalpara>
<formalpara>
<title><option>-Dforce_posix_threads=true</option></title>
<para>
Normally, <application>Meson</application> should be able to work out
the correct thread implementation to use. This option forces POSIX
threads to be used even if the platform provides another threading API
(for example, on Windows).
</para>
</formalpara>
<formalpara>
<title><option>-Dbsymbolic_functions=false</option> and
<option>-Dbsymbolic_functions=true</option></title>
<para>
By default, GLib uses the <option>-Bsymbolic-functions</option>
linker flag to avoid intra-library PLT jumps. A side-effect
of this is that it is no longer possible to override
internal uses of GLib functions with
<envar>LD_PRELOAD</envar>. Therefore, it may make
sense to turn this feature off in some situations.
The <option>-Dbsymbolic_functions=false</option> option allows
to do that.
</para>
</formalpara>
<formalpara>
<title><option>-Dgtk_doc=false</option> and
<option>-Dgtk_doc=true</option></title>
<para>
By default, GLib will detect whether the
<application>gtk-doc</application> package is installed.
If it is, then it will use it to extract and build the
documentation for the GLib library. These options
can be used to explicitly control whether
<application>gtk-doc</application> should be
used or not. If it is not used, the distributed,
pre-generated HTML files will be installed instead of
building them on your machine.
</para>
</formalpara>
<formalpara>
<title><option>-Dman=false</option> and
<option>-Dman=true</option></title>
<para>
By default, GLib will detect whether <application>xsltproc</application>
and the necessary DocBook stylesheets are installed.
If they are, then it will use them to rebuild the included
man pages from the XML sources. These options can be used
to explicitly control whether man pages should be rebuilt
used or not. The distribution includes pre-generated man
pages.
</para>
</formalpara>
<formalpara>
<title><option>-Dxattr=false</option> and
<option>-Dxattr=true</option></title>
<para>
By default, GLib will detect whether the
<function>getxattr()</function>
family of functions is available. If it is, then extended
attribute support will be included in GIO. These options can
be used to explicitly control whether extended attribute
support should be included or not. <function>getxattr()</function>
and friends can be provided by glibc or by the standalone
libattr library.
</para>
</formalpara>
<formalpara>
<title><option>-Dselinux=auto</option>,
<option>-Dselinux=enabled</option> or
<option>-Dselinux=disabled</option></title>
<para>
By default, GLib will detect if libselinux is available and
include SELinux support in GIO if it is. These options can be
used to explicitly control whether SELinux support should
be included.
</para>
</formalpara>
<formalpara>
<title><option>-Ddtrace=false</option> and
<option>-Ddtrace=true</option></title>
<para>
By default, GLib will detect if DTrace support is available, and use it.
These options can be used to explicitly control whether DTrace support
is compiled into GLib.
</para>
</formalpara>
<formalpara>
<title><option>-Dsystemtap=false</option> and
<option>-Dsystemtap=true</option></title>
<para>
This option requires DTrace support. If it is available, then
GLib will also check for the presence of SystemTap.
</para>
</formalpara>
<formalpara>
<title><option>-Db_coverage=true</option> and
<option>-Db_coverage=false</option></title>
<para>
Enable the generation of coverage reports for the GLib tests.
This requires the lcov frontend to gcov from the
<ulink url="http://ltp.sourceforge.net">Linux Test Project</ulink>.
To generate a coverage report, use
<command>ninja coverage-html</command>. The report is placed in the
<filename>meson-logs</filename> directory.
</para>
</formalpara>
<formalpara>
<title><option>-Druntime_libdir=RELPATH</option></title>
<para>
Allows specifying a relative path to where to install the runtime
libraries (meaning library files used for running, not developing,
GLib applications). This can be used in operating system setups where
programs using GLib needs to run before e.g. <filename>/usr</filename>
is mounted.
For example, if <varname>LIBDIR</varname> is <filename>/usr/lib</filename> and
<filename>../../lib</filename> is passed to
<option>-Druntime_libdir</option> then the
runtime libraries are installed into <filename>/lib</filename> rather
than <filename>/usr/lib</filename>.
</para>
</formalpara>
</refsect1>
</refentry>

174
docs/reference/glib/changes.xml Normal file
View file

@ -0,0 +1,174 @@
<?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-changes" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Changes to GLib</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Changes to GLib</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Changes to GLib</refname>
<refpurpose>
Incompatible changes made between successive versions of GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Incompatible changes from 2.0 to 2.2</title>
<itemizedlist>
<listitem>
<para>
GLib changed the seeding algorithm for the pseudo-random number
generator Mersenne Twister, as used by <structname>GRand</structname>
and <structname>GRandom</structname>. This was necessary, because some
seeds would yield very bad pseudo-random streams. Also the
pseudo-random integers generated by
<function>g_rand*_int_range()</function> will have a
slightly better equal distribution with the new version of GLib.
</para>
<para>
Further information can be found at the website of the Mersenne
Twister random number generator at <ulink
url="http://www.math.keio.ac.jp/~matumoto/emt.html">http://www.math.keio.ac.jp/~matumoto/emt.html</ulink>.
</para>
<para>
The original seeding and generation algorithms, as found in GLib
2.0.x, can be used instead of the new ones by setting the environment
variable <envar>G_RANDOM_VERSION</envar> to the value of '2.0'. Use
the GLib-2.0 algorithms only if you have sequences of numbers generated
with Glib-2.0 that you need to reproduce exactly.
</para>
</listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Incompatible changes from 1.2 to 2.0</title>
<itemizedlist>
<listitem>
<para>
The event loop functionality <structname>GMain</structname> has extensively
been revised to support multiple separate main loops in separate threads.
All sources (timeouts, idle functions, etc.) are associated with a
<structname>GMainContext</structname>.
</para>
<para>
Compatibility functions exist so that most application code dealing with
the main loop will continue to work. However, code that creates new custom
types of sources will require modification.
</para>
<para>
The main changes here are:
<itemizedlist>
<listitem>
<para>
Sources are now exposed as <type>GSource *</type>, rather than simply as
numeric ids.
</para>
</listitem>
<listitem>
<para>
New types of sources are created by structure "derivation" from
<structname>GSource</structname>, so the <literal>source_data</literal>
parameter to the <structname>GSource</structname> virtual functions has been
replaced with a <type>GSource *</type>.
</para>
</listitem>
<listitem>
<para>
Sources are first created, then later added to a specific
<structname>GMainContext</structname>.
</para>
</listitem>
<listitem>
<para>
Dispatching has been modified so both the callback and data are passed
in to the <function>dispatch()</function> virtual function.
</para>
</listitem>
</itemizedlist>
To go along with this change, the vtable for
<structname>GIOChannel</structname> has changed and
<function>add_watch()</function> has been replaced by
<function>create_watch()</function>.
</para>
</listitem>
<listitem>
<para>
<function>g_list_foreach()</function> and
<function>g_slist_foreach()</function> have been changed so they
are now safe against removal of the current item, not the next item.
</para>
<para>
It's not recommended to mutate the list in the callback to these
functions in any case.
</para>
</listitem>
<listitem>
<para>
<structname>GDate</structname> now works in UTF-8, not in the current locale.
If you want to use it with the encoding of the locale, you need to convert
strings using <function>g_locale_to_utf8()</function> first.
</para>
</listitem>
<listitem>
<para>
<function>g_strsplit()</function> has been fixed to:
<itemizedlist>
<listitem>
<para>
include trailing empty tokens, rather than stripping them
</para>
</listitem>
<listitem>
<para>
split into a maximum of <literal>max_tokens</literal> tokens, rather
than <literal>max_tokens + 1</literal>
</para>
</listitem>
</itemizedlist>
Code depending on either of these bugs will need to be fixed.
</para>
</listitem>
<listitem>
<para>
Deprecated functions that got removed:
<function>g_set_error_handler()</function>,
<function>g_set_warning_handler()</function>,
<function>g_set_message_handler()</function>, use
<function>g_log_set_handler()</function> instead.
</para>
</listitem>
</itemizedlist>
</refsect1>
</refentry>

125
docs/reference/glib/compiling.xml Normal file
View file

@ -0,0 +1,125 @@
<?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-compiling" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Compiling GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Compiling GLib Applications</refname>
<refpurpose>
How to compile your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Compiling GLib Applications on UNIX</title>
<para>
To compile a GLib application, you need to tell the compiler where to
find the GLib header files and libraries. This is done with the
<application>pkg-config</application> utility.
</para>
<para>
The following interactive shell session demonstrates how
<application>pkg-config</application> is used (the actual output on
your system may be different):
<programlisting>
$ pkg-config --cflags glib-2.0
-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
$ pkg-config --libs glib-2.0
-L/usr/lib -lm -lglib-2.0
</programlisting>
</para>
<para>
See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
for more information about <application>pkg-config</application>.
</para>
<para>
If your application uses or <structname>GObject</structname>
features, it must be compiled and linked with the options returned
by the following <application>pkg-config</application> invocation:
<programlisting>
$ pkg-config --cflags --libs gobject-2.0
</programlisting>
</para>
<para>
If your application uses modules, it must be compiled and linked
with the options returned by one of the following
<application>pkg-config</application> invocations:
<programlisting>
$ pkg-config --cflags --libs gmodule-no-export-2.0
$ pkg-config --cflags --libs gmodule-2.0
</programlisting>
The difference between the two is that gmodule-2.0 adds
<option>--export-dynamic</option> to the linker flags,
which is often not needed.
</para>
<para>
The simplest way to compile a program is to use command substitution
feature of a shell. A command written in the format
<literal>$(command)</literal> gets substituted into the command line
before execution. So to compile a GLib Hello, World, you would type
the following:
<programlisting>
$ cc hello.c $(pkg-config --cflags --libs glib-2.0) -o hello
</programlisting>
</para>
<note><para>
Note that the name of the file must come before the other options
(such as <emphasis>pkg-config</emphasis>), or else you may get an
error from the linker.
</para></note>
<para>
Deprecated GLib functions are annotated to make the compiler
emit warnings when they are used (e.g. with gcc, you need to use
the -Wdeprecated-declarations option). If these warnings are
problematic, they can be turned off by defining the preprocessor
symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline
option <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
</para>
<para>
GLib deprecation annotations are versioned; by defining the
macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED,
you can specify the range of GLib versions whose API you want
to use. APIs that were deprecated before or introduced after
this range will trigger compiler warnings.
</para>
<para>
Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
entirely from the compiler by using the preprocessor symbol
<literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
are now handled using the above mechanism.
</para>
<para>
The recommended way of using GLib has always been to only include the
toplevel headers <filename>glib.h</filename>,
<filename>glib-object.h</filename>, <filename>gio.h</filename>.
Starting with 2.32, GLib enforces this by generating an error
when individual headers are directly included.
</para>
<para>
Still, there are some exceptions; these headers have to be included
separately:
<filename>gmodule.h</filename>,
<filename>glib-unix.h</filename>,
<filename>glib/gi18n-lib.h</filename> or
<filename>glib/gi18n.h</filename> (see
the <link linkend="glib-I18N">Internationalization section</link>),
<filename>glib/gprintf.h</filename> and
<filename>glib/gstdio.h</filename>
(we don't want to pull in all of stdio).
</para>
</refsect1>
</refentry>

147
docs/reference/glib/cross.xml Normal file
View file

@ -0,0 +1,147 @@
<?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-cross-compiling" revision="7 Aug 2018">
<refmeta>
<refentrytitle>Cross-compiling the GLib package</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Cross-compiling the GLib Package</refname>
<refpurpose>
How to cross-compile GLib
</refpurpose>
</refnamediv>
<refsect1 id="cross">
<title>Building the Library for a different architecture</title>
<para>
Cross-compilation is the process of compiling a program or
library on a different architecture or operating system then
it will be run upon. GLib is slightly more difficult to
cross-compile than many packages because much of GLib is
about hiding differences between different systems.
</para>
<para>
These notes cover things specific to cross-compiling GLib;
for general information about cross-compilation, see the
<ulink url="http://mesonbuild.com/Cross-compilation.html">meson</ulink>
info pages.
</para>
<para>
GLib tries to detect as much information as possible about
the target system by compiling and linking programs without
actually running anything; however, some information GLib
needs is not available this way. This information needs
to be provided to meson via a ‘cross file’.
</para>
<para>
As an example of using a cross file, to cross compile for
the ‘MingW32’ Win64 runtime environment on a Linux system,
create a file <filename>cross_file.txt</filename> with the following
contents:
</para>
<programlisting>
[host_machine]
system = 'windows'
cpu_family = 'x86_64'
cpu = 'x86_64'
endian = 'little'
[properties]
c_args = []
c_link_args = []
[binaries]
c = 'x86_64-w64-mingw32-gcc'
cpp = 'x86_64-w64-mingw32-g++'
ar = 'x86_64-w64-mingw32-ar'
ld = 'x86_64-w64-mingw32-ld'
objcopy = 'x86_64-w64-mingw32-objcopy'
strip = 'x86_64-w64-mingw32-strip'
pkgconfig = 'x86_64-w64-mingw32-pkg-config'
windres = 'x86_64-w64-mingw32-windres'
</programlisting>
<para>
Then execute the following commands:
</para>
<programlisting>
meson --cross-file cross_file.txt builddir
</programlisting>
<para>
The complete list of cross properties follows. Most
of these won't need to be set in most cases.
</para>
</refsect1>
<refsect1 id="cross-properties">
<title>Cross properties</title>
<formalpara>
<title>have_[function]</title>
<para>
When meson checks if a function is supported, the test can be
overridden by setting the
<literal>have_<replaceable>function</replaceable></literal> property
to <constant>true</constant> or <constant>false</constant>.
For example <programlisting>Checking for function "fsync" : YES</programlisting>
can be overridden by setting <programlisting>have_fsync = false</programlisting>
</para>
</formalpara>
<formalpara>
<title>growing_stack=[true/false]</title>
<para>
Whether the stack grows up or down. Most places will want
<constant>false</constant>.
A few architectures, such as PA-RISC need <constant>true</constant>.
</para>
</formalpara>
<formalpara>
<title>have_strlcpy=[true/false]</title>
<para>
Whether you have <function>strlcpy()</function> that matches
OpenBSD. Defaults to <constant>false</constant>, which is safe,
since GLib uses a built-in version in that case.
</para>
</formalpara>
<formalpara>
<title>va_val_copy=[true/false]</title>
<para>
Whether <type>va_list</type> can be copied as a pointer. If set
to <constant>false</constant>, then <function>memcopy()</function>
will be used. Only matters if you don't have
<function>va_copy()</function> or <function>__va_copy()</function>.
(So, doesn't matter for GCC.)
Defaults to <constant>true</constant> which is slightly more common
than <constant>false</constant>.
</para>
</formalpara>
<formalpara>
<title>have_c99_vsnprintf=[true/false]</title>
<para>
Whether you have a <function>vsnprintf()</function> with C99
semantics. (C99 semantics means returning the number of bytes
that would have been written had the output buffer had enough
space.) Defaults to <constant>false</constant>.
</para>
</formalpara>
<formalpara>
<title>have_c99_snprintf=[true/false]</title>
<para>
Whether you have a <function>snprintf()</function> with C99
semantics. (C99 semantics means returning the number of bytes
that would have been written had the output buffer had enough
space.) Defaults to <constant>false</constant>.
</para>
</formalpara>
</refsect1>
</refentry>

BIN
docs/reference/glib/file-name-encodings.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/reference/glib/file-name-encodings.sxd Normal file
View file

Binary file not shown.

302
docs/reference/glib/glib-docs.xml Normal file
View file

@ -0,0 +1,302 @@
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>GLib Reference Manual</title>
<releaseinfo>
for GLib &version;
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.gnome.org/glib/unstable/">https://developer.gnome.org/glib/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<chapter id="glib">
<title>GLib Overview</title>
<para>
GLib is a general-purpose utility library, which provides many useful
data types, macros, type conversions, string utilities, file utilities,
a mainloop abstraction, and so on. It works on many UNIX-like platforms,
as well as Windows and OS X. GLib is released under the GNU Lesser
General Public License (GNU LGPL).
</para>
<xi:include href="building.xml" />
<xi:include href="cross.xml" />
<xi:include href="programming.xml" />
<xi:include href="xml/compiling.xml" />
<xi:include href="running.xml" />
<xi:include href="changes.xml" />
<xi:include href="resources.xml" />
</chapter>
<chapter id="glib-fundamentals">
<title>GLib Fundamentals</title>
<xi:include href="xml/version.xml" />
<xi:include href="xml/types.xml" />
<xi:include href="xml/macros.xml" />
<xi:include href="xml/type_conversion.xml" />
<xi:include href="xml/byte_order.xml" />
<xi:include href="xml/checkedmath.xml" />
<xi:include href="xml/numerical.xml" />
<xi:include href="xml/macros_misc.xml" />
<xi:include href="xml/atomic_operations.xml" />
</chapter>
<chapter id="glib-core">
<title>GLib Core Application Support</title>
<xi:include href="xml/main.xml" />
<xi:include href="xml/threads.xml" />
<xi:include href="xml/thread_pools.xml" />
<xi:include href="xml/async_queues.xml" />
<xi:include href="xml/modules.xml" />
<xi:include href="xml/memory.xml" />
<xi:include href="xml/memory_slices.xml" />
<xi:include href="xml/iochannels.xml" />
<xi:include href="xml/error_reporting.xml" />
<xi:include href="xml/warnings.xml" />
<xi:include href="xml/messages.xml" />
</chapter>
<chapter id="glib-utilities">
<title>GLib Utilities</title>
<xi:include href="xml/string_utils.xml" />
<xi:include href="xml/conversions.xml" />
<xi:include href="xml/unicode.xml" />
<xi:include href="xml/base64.xml" />
<xi:include href="xml/checksum.xml" />
<xi:include href="xml/hmac.xml" />
<xi:include href="xml/i18n.xml" />
<xi:include href="xml/date.xml" />
<xi:include href="xml/timezone.xml" />
<xi:include href="xml/date-time.xml" />
<xi:include href="xml/random_numbers.xml" />
<xi:include href="xml/hooks.xml" />
<xi:include href="xml/misc_utils.xml" />
<xi:include href="xml/scanner.xml" />
<xi:include href="xml/timers.xml" />
<xi:include href="xml/spawn.xml" />
<xi:include href="xml/fileutils.xml" />
<xi:include href="xml/guri.xml" />
<xi:include href="xml/ghostutils.xml" />
<xi:include href="xml/shell.xml" />
<xi:include href="xml/option.xml" />
<xi:include href="xml/patterns.xml" />
<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/testing.xml" />
<xi:include href="xml/gunix.xml" />
<xi:include href="xml/windows.xml" />
<xi:include href="xml/uuid.xml" />
</chapter>
<chapter id="glib-data-types">
<title>GLib Data Types</title>
<xi:include href="xml/linked_lists_double.xml" />
<xi:include href="xml/linked_lists_single.xml" />
<xi:include href="xml/queue.xml" />
<xi:include href="xml/sequence.xml" />
<xi:include href="xml/trash_stack.xml" />
<xi:include href="xml/hash_tables.xml" />
<xi:include href="xml/strings.xml" />
<xi:include href="xml/string_chunks.xml" />
<xi:include href="xml/arrays.xml" />
<xi:include href="xml/arrays_pointer.xml" />
<xi:include href="xml/arrays_byte.xml" />
<xi:include href="xml/trees-binary.xml" />
<xi:include href="xml/trees-nary.xml" />
<xi:include href="xml/quarks.xml" />
<xi:include href="xml/datalist.xml" />
<xi:include href="xml/datasets.xml" />
<xi:include href="xml/gvarianttype.xml"/>
<xi:include href="xml/gvariant.xml"/>
<xi:include href="gvariant-varargs.xml"/>
<xi:include href="gvariant-text.xml"/>
<xi:include href="xml/refcount.xml"/>
<xi:include href="xml/rcbox.xml"/>
<xi:include href="xml/arcbox.xml"/>
<xi:include href="xml/refstring.xml"/>
</chapter>
<chapter id="deprecated">
<title>Deprecated APIs</title>
<xi:include href="xml/threads-deprecated.xml"/>
<xi:include href="xml/caches.xml" />
<xi:include href="xml/relations.xml" />
<xi:include href="xml/completion.xml" />
</chapter>
<chapter id="tools">
<title>GLib Tools</title>
<xi:include href="glib-gettextize.xml" />
</chapter>
<chapter id="deprecated-tools">
<title>Deprecated Tools</title>
<xi:include href="gtester.xml" />
<xi:include href="gtester-report.xml" />
</chapter>
<index 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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<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">
<title>Index of new symbols in 2.72</title>
<xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

88
docs/reference/glib/glib-gettextize.xml Normal file
View file

@ -0,0 +1,88 @@
<refentry id="glib-gettextize" lang="en">
<refentryinfo>
<title>glib-gettextize</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Owen</firstname>
<surname>Taylor</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>glib-gettextize</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>glib-gettextize</refname>
<refpurpose>gettext internationalization utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>glib-gettextize</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg choice="opt">DIRECTORY</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>glib-gettextize</command> helps to prepare a source package for being
internationalized through <application>gettext</application>.
It is a variant of the <command>gettextize</command> that ships with
<application>gettext</application>.
</para>
<para><command>glib-gettextize</command> differs
from <command>gettextize</command> in that it doesn't create an
<filename>intl/</filename> subdirectory and doesn't modify
<filename>po/ChangeLog</filename> (note that newer versions of
<command>gettextize</command> behave like this when called with the
<option>--no-changelog</option> option).
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>, <option>--copy</option></term>
<listitem><para>
copy files instead of making symlinks
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-f</option>, <option>--force</option></term>
<listitem><para>
force writing of new files even if old ones exist
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry><refentrytitle>gettextize</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>

294
docs/reference/glib/glib-overrides.txt Normal file
View file

@ -0,0 +1,294 @@
# This file makes most of the thread related macros look like
# functions, which they really were, if possible easy.
<MACRO>
<NAME>GLIB_DISABLE_DEPRECATION_WARNINGS</NAME>
#ifdef GLIB_DISABLE_DEPRECATION_WARNINGS
</MACRO>
<MACRO>
<NAME>G_ATOMIC_LOCK_FREE</NAME>
#define G_ATOMIC_LOCK_FREE
</MACRO>
# default thread implementation
<MACRO>
<NAME>G_THREADS_IMPL_POSIX</NAME>
#define G_THREADS_IMPL_POSIX
</MACRO>
<MACRO>
<NAME>G_THREADS_IMPL_WIN32</NAME>
#define G_THREADS_IMPL_NONE
</MACRO>
# threads supported?
<FUNCTION>
<NAME>g_thread_supported</NAME>
<RETURNS>gboolean</RETURNS>
</FUNCTION>
# GMutex
<FUNCTION>
<NAME>g_mutex_new</NAME>
<RETURNS>GMutex *</RETURNS>
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_lock</NAME>
<RETURNS>void</RETURNS>
GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_trylock</NAME>
<RETURNS>gboolean</RETURNS>
GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_unlock</NAME>
<RETURNS>void</RETURNS>
GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_mutex_free</NAME>
<RETURNS>void</RETURNS>
GMutex *mutex
</FUNCTION>
# GStaticMutex
<STRUCT>
<NAME>GStaticMutex</NAME>
</STRUCT>
<MACRO>
<NAME>G_STATIC_MUTEX_INIT</NAME>
#define G_STATIC_MUTEX_INIT
</MACRO>
<FUNCTION>
<NAME>g_static_mutex_lock</NAME>
<RETURNS>void</RETURNS>
GStaticMutex* mutex
</FUNCTION>
<FUNCTION>
<NAME>g_static_mutex_trylock</NAME>
<RETURNS>gboolean</RETURNS>
GStaticMutex* mutex
</FUNCTION>
<FUNCTION>
<NAME>g_static_mutex_unlock</NAME>
<RETURNS>void</RETURNS>
GStaticMutex* mutex
</FUNCTION>
<FUNCTION>
<NAME>g_static_mutex_get_mutex</NAME>
<RETURNS>GMutex *</RETURNS>
GStaticMutex* mutex
</FUNCTION>
# GThread
<FUNCTION>
<NAME>g_thread_yield</NAME>
<RETURNS>void</RETURNS>
</FUNCTION>
<FUNCTION>
<NAME>g_thread_create</NAME>
<RETURNS>GThread *</RETURNS>
GThreadFunc func
gpointer data,
gboolean joinable,
GError **error
</FUNCTION>
# G_LOCK_* macros
<MACRO>
<NAME>G_LOCK_DEFINE</NAME>
#define G_LOCK_DEFINE(name)
</MACRO>
<MACRO>
<NAME>G_LOCK_DEFINE_STATIC</NAME>
#define G_LOCK_DEFINE_STATIC(name)
</MACRO>
<MACRO>
<NAME>G_LOCK_EXTERN</NAME>
#define G_LOCK_EXTERN(name)
</MACRO>
<MACRO>
<NAME>G_LOCK</NAME>
#define G_LOCK(name)
</MACRO>
<MACRO>
<NAME>G_UNLOCK</NAME>
#define G_UNLOCK(name)
</MACRO>
<MACRO>
<NAME>G_TRYLOCK</NAME>
#define G_TRYLOCK(name)
</MACRO>
# GCond
<FUNCTION>
<NAME>g_cond_new</NAME>
<RETURNS>GCond*</RETURNS>
</FUNCTION>
<FUNCTION>
<NAME>g_cond_signal</NAME>
<RETURNS>void</RETURNS>
GCond *cond
</FUNCTION>
<FUNCTION>
<NAME>g_cond_broadcast</NAME>
<RETURNS>void</RETURNS>
GCond *cond
</FUNCTION>
<FUNCTION>
<NAME>g_cond_wait</NAME>
<RETURNS>void</RETURNS>
GCond *cond, GMutex *mutex
</FUNCTION>
<FUNCTION>
<NAME>g_cond_timed_wait</NAME>
<RETURNS>gboolean</RETURNS>
GCond *cond, GMutex *mutex, GTimeVal *abs_time
</FUNCTION>
<FUNCTION>
<NAME>g_cond_free</NAME>
<RETURNS>void</RETURNS>
GCond *cond
</FUNCTION>
# GPrivate
<MACRO>
<NAME>G_PRIVATE_INIT</NAME>
#define G_PRIVATE_INIT(notify)
</MACRO>
# GStaticPrivate
<MACRO>
<NAME>G_STATIC_PRIVATE_INIT</NAME>
#define G_STATIC_PRIVATE_INIT
</MACRO>
# Definitions for different operating systems
<MACRO>
<NAME>G_OS_UNIX</NAME>
#define G_OS_UNIX
</MACRO>
<MACRO>
<NAME>G_OS_WIN32</NAME>
#define G_OS_WIN32
</MACRO>
# g_ascii_isxxx
<FUNCTION>
<NAME>g_ascii_isalnum</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isalpha</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_iscntrl</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isdigit</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isgraph</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_islower</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isprint</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_ispunct</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isspace</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isupper</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
<FUNCTION>
<NAME>g_ascii_isxdigit</NAME>
<RETURNS>gboolean</RETURNS>
gchar c
</FUNCTION>
# g_atomic
<FUNCTION>
<NAME>g_atomic_int_inc</NAME>
<RETURNS>void</RETURNS>
gint *atomic
</FUNCTION>
<FUNCTION>
<NAME>g_atomic_int_dec_and_test</NAME>
<RETURNS>gboolean</RETURNS>
gint *atomic
</FUNCTION>
<MACRO>
<NAME>G_VA_COPY</NAME>
#define G_VA_COPY(ap1,ap2)
</MACRO>

4013
docs/reference/glib/glib-sections.txt Normal file
View file

File diff suppressed because it is too large Load diff

78
docs/reference/glib/gtester-report.xml Normal file
View file

@ -0,0 +1,78 @@
<refentry id="gtester-report">
<refentryinfo>
<title>gtester-report</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtester-report</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtester-report</refname>
<refpurpose>test report formatting utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtester-report</command>
<arg choice="opt" rep="repeat">option</arg>
<arg>gtester-log</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gtester-report</command> is a script which converts
the XML output generated by gtester into HTML.
</para>
<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
TAP for reporting test results instead, and feed it to the test harness provided
by your build system.</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s</option>, <option>--subunit</option></term>
<listitem><para>
Output subunit. Needs python-subunit.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>gtester</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

192
docs/reference/glib/gtester.xml Normal file
View file

@ -0,0 +1,192 @@
<refentry id="gtester">
<refentryinfo>
<title>gtester</title>
<productname>GLib</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Tim</firstname>
<surname>Janik</surname>
</author>
<author>
<contrib>Developer</contrib>
<firstname>Sven</firstname>
<surname>Herzberg</surname>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>gtester</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">User Commands</refmiscinfo>
</refmeta>
<refnamediv>
<refname>gtester</refname>
<refpurpose>test running utility</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>gtester</command>
<arg choice="opt" rep="repeat">OPTION</arg>
<arg>testprogram</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1><title>Description</title>
<para><command>gtester</command> is a utility to run unit tests that have
been written using the GLib test framework.
</para>
<para>Since GLib 2.62, <command>gtester-report</command> is deprecated. Use
TAP for reporting test results instead, and feed it to the test harness provided
by your build system.</para>
<para>
When called with the <option>-o</option> option, <command>gtester</command>
writes an XML report of the test results, which can be converted
into HTML using the <command>gtester-report</command> utility.
</para>
</refsect1>
<refsect1><title>Options</title>
<variablelist>
<varlistentry>
<term><option>-h</option>, <option>--help</option></term>
<listitem><para>
print help and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-v</option>, <option>--version</option></term>
<listitem><para>
print version information and exit
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--g-fatal-warnings</option></term>
<listitem><para>
make warnings fatal
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-k</option>, <option>--keep-going</option></term>
<listitem><para>
continue running after tests failed
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-l</option></term>
<listitem><para>
list paths of available test cases
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-m=<replaceable>MODE</replaceable></option></term>
<listitem><para>
run test cases in <replaceable>MODE</replaceable>, which can be one of:
<variablelist>
<varlistentry>
<term><option>perf</option></term>
<listitem><para>
run performance tests
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>slow</option>, <option>thorough</option></term>
<listitem><para>
run slow tests, or repeat non-deterministic tests more often
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>quick</option></term>
<listitem><para>
do not run slow or performance tests, or do extra repeats
of non-deterministic tests (default)
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>undefined</option></term>
<listitem><para>
run test cases that deliberately provoke checks or assertion
failures, if implemented (default)
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>no-undefined</option></term>
<listitem><para>
do not run test cases that deliberately provoke checks or
assertion failures
</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-p=<replaceable>TESTPATH</replaceable></option></term>
<listitem><para>
only run test cases matching <replaceable>TESTPATH</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-s=<replaceable>TESTPATH</replaceable></option></term>
<listitem><para>
skip test cases matching <replaceable>TESTPATH</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--seed=<replaceable>SEEDSTRING</replaceable></option></term>
<listitem><para>
run all test cases with random number seed <replaceable>SEEDSTRING</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-o=<replaceable>LOGFILE</replaceable></option></term>
<listitem><para>
write the test log to <replaceable>LOGFILE</replaceable>
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-q</option>, <option>--quiet</option></term>
<listitem><para>
suppress per test binary output
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>--verbose</option></term>
<listitem><para>
report success per testcase
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1><title>See also</title>
<para>
<citerefentry>
<refentrytitle>gtester-report</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
</para>
</refsect1>
</refentry>

622
docs/reference/glib/gvariant-text.xml Normal file
View file

@ -0,0 +1,622 @@
<?xml version='1.0' encoding='utf-8'?>
<refentry id='gvariant-text'>
<refmeta>
<refentrytitle>GVariant Text Format</refentrytitle>
</refmeta>
<refnamediv>
<refname>GVariant Text Format</refname>
<refpurpose>textual representation of GVariants</refpurpose>
</refnamediv>
<refsect1>
<title>GVariant Text Format</title>
<para>
This page attempts to document the GVariant text format as produced by
<link linkend='g-variant-print'><function>g_variant_print()</function></link> and parsed by the
<link linkend='g-variant-parse'><function>g_variant_parse()</function></link> family of functions. In most
cases the style closely resembles the formatting of literals in Python but there are some additions and
exceptions.
</para>
<para>
The functions that deal with GVariant text format absolutely always deal in utf-8. Conceptually, GVariant
text format is a string of Unicode characters -- not bytes. Non-ASCII but otherwise printable Unicode
characters are not treated any differently from normal ASCII characters.
</para>
<para>
The parser makes two passes. The purpose of the first pass is to determine the type of the value being
parsed. The second pass does the actual parsing. Based on the fact that all elements in an array have to
have the same type, GVariant is able to make some deductions that would not otherwise be possible. As an
example:
<informalexample><programlisting>[[1, 2, 3], [4, 5, 6]]</programlisting></informalexample>
is parsed as an array of arrays of integers (type '<literal>aai</literal>'), but
<informalexample><programlisting>[[1, 2, 3], [4, 5, 6.0]]</programlisting></informalexample>
is parsed as an array of arrays of doubles (type '<literal>aad</literal>').
</para>
<para>
As another example, GVariant is able to determine that
<informalexample><programlisting>["hello", nothing]</programlisting></informalexample>
is an array of maybe strings (type '<literal>ams</literal>').
</para>
<para>
What the parser accepts as valid input is dependent on context. The API permits for out-of-band type
information to be supplied to the parser (which will change its behaviour). This can be seen in the
GSettings and GDBus command line utilities where the type information is available from the schema or the
remote introspection information. The additional information can cause parses to succeed when they would not
otherwise have been able to (by resolving ambiguous type information) or can cause them to fail (due to
conflicting type information). Unless stated otherwise, the examples given in this section assume that no
out-of-band type data has been given to the parser.
</para>
</refsect1>
<refsect1>
<title>Syntax Summary</title>
<para>
The following table describes the rough meaning of symbols that may appear inside GVariant text format.
Each symbol is described in detail in its own section, including usage examples.
</para>
<informaltable>
<tgroup cols='2'>
<colspec colname='col_0'/>
<colspec colname='col_1'/>
<tbody>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'>Symbol</emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'>Meaning</emphasis>
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>true</literal></emphasis>,
<emphasis role='strong'><literal>false</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-booleans'>Booleans</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>""</literal></emphasis>,
<emphasis role='strong'><literal>''</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
String literal. See <link linkend='gvariant-text-strings'>Strings</link> below.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
numbers
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
See <link linkend='gvariant-text-numbers'>Numbers</link> below.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>()</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-tuples'>Tuples</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>[]</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-arrays'>Arrays</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>{}</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-dictionaries'>Dictionaries and Dictionary Entries</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>&lt;&gt;</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-variants'>Variants</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>just</literal></emphasis>,
<emphasis role='strong'><literal>nothing</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-maybe-types'>Maybe Types</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>@</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
type keywords
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<literal>boolean</literal>,
<literal>byte</literal>,
<literal>int16</literal>,
<literal>uint16</literal>,
<literal>int32</literal>,
<literal>uint32</literal>,
<literal>handle</literal>,
<literal>int64</literal>,
<literal>uint64</literal>,
<literal>double</literal>,
<literal>string</literal>,
<literal>objectpath</literal>,
<literal>signature</literal>
</para>
<para>
See <link linkend='gvariant-text-type-annotations'>Type Annotations</link> below.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>b""</literal></emphasis>,
<emphasis role='strong'><literal>b''</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-bytestrings'>Bytestrings</link>.
</para>
</entry>
</row>
<row rowsep='1'>
<entry colsep='1' rowsep='1'>
<para>
<emphasis role='strong'><literal>%</literal></emphasis>
</para>
</entry>
<entry colsep='1' rowsep='1'>
<para>
<link linkend='gvariant-text-positional'>Positional Parameters</link>.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<refsect2 id='gvariant-text-booleans'>
<title>Booleans</title>
<para>
The strings <literal>true</literal> and <literal>false</literal> are parsed as booleans. This is the only
way to specify a boolean value.
</para>
</refsect2>
<refsect2 id='gvariant-text-strings'>
<title>Strings</title>
<para>
Strings literals must be quoted using <literal>""</literal> or <literal>''</literal>. The two are
completely equivalent (except for the fact that each one is unable to contain itself unescaped).
</para>
<para>
Strings are Unicode strings with no particular encoding. For example, to specify the character
<literal>é</literal>, you just write <literal>'é'</literal>. You could also give the Unicode codepoint of
that character (U+E9) as the escape sequence <literal>'\u00e9'</literal>. Since the strings are pure
Unicode, you should not attempt to encode the utf-8 byte sequence corresponding to the string using escapes;
it won't work and you'll end up with the individual characters corresponding to each byte.
</para>
<para>
Unicode escapes of the form <literal>\uxxxx</literal> and <literal>\Uxxxxxxxx</literal> are supported, in
hexadecimal. The usual control sequence escapes <literal>\a</literal>, <literal>\b</literal>,
<literal>\f</literal>, <literal>\n</literal>, <literal>\r</literal>, <literal>\t</literal> and
<literal>\v</literal> are supported. Additionally, a <literal>\</literal> before a newline character causes
the newline to be ignored. Finally, any other character following <literal>\</literal> is copied literally
(for example, <literal>\"</literal> or <literal>\\</literal>) but for forwards compatibility with future
additions you should only use this feature when necessary for escaping backslashes or quotes.
</para>
<para>
The usual octal and hexadecimal escapes <literal>\0nnn</literal> and <literal>\xnn</literal> are not
supported here. Those escapes are used to encode byte values and GVariant strings are Unicode.
</para>
<para>
Single-character strings are not interpreted as bytes. Bytes must be specified by their numerical value.
</para>
</refsect2>
<refsect2 id='gvariant-text-numbers'>
<title>Numbers</title>
<para>
Numbers are given by default as decimal values. Octal and hex values can be given in the usual way (by
prefixing with <literal>0</literal> or <literal>0x</literal>). Note that GVariant considers bytes to be
unsigned integers and will print them as a two digit hexadecimal number by default.
</para>
<para>
Floating point numbers can also be given in the usual ways, including scientific and hexadecimal notations.
</para>
<para>
For lack of additional information, integers will be parsed as int32 values by default. If the number has a
point or an 'e' in it, then it will be parsed as a double precision floating point number by default. If
type information is available (either explicitly or inferred) then that type will be used instead.
</para>
<para>
Some examples:
</para>
<para>
<literal>5</literal> parses as the int32 value five.
</para>
<para>
<literal>37.5</literal> parses as a floating point value.
</para>
<para>
<literal>3.75e1</literal> parses the same as the value above.
</para>
<para>
<literal>uint64 7</literal> parses seven as a uint64.
See <link linkend='gvariant-text-type-annotations'>Type Annotations</link>.
</para>
</refsect2>
<refsect2 id='gvariant-text-tuples'>
<title>Tuples</title>
<para>
Tuples are formed using the same syntax as Python. Here are some examples:
</para>
<para>
<literal>()</literal> parses as the empty tuple.
</para>
<para>
<literal>(5,)</literal> is a tuple containing a single value.
</para>
<para>
<literal>("hello", 42)</literal> is a pair. Note that values of different types are permitted.
</para>
</refsect2>
<refsect2 id='gvariant-text-arrays'>
<title>Arrays</title>
<para>
Arrays are formed using the same syntax as Python uses for lists (which is arguably the term that GVariant
should have used). Note that, unlike Python lists, GVariant arrays are statically typed. This has two
implications.
</para>
<para>
First, all items in the array must have the same type. Second, the type of the array must be known, even in
the case that it is empty. This means that (unless there is some other way to infer it) type information
will need to be given explicitly for empty arrays.
</para>
<para>
The parser is able to infer some types based on the fact that all items in an array must have the same type.
See the examples below:
</para>
<para>
<literal>[1]</literal> parses (without additional type information) as a one-item array of signed integers.
</para>
<para>
<literal>[1, 2, 3]</literal> parses (similarly) as a three-item array.
</para>
<para>
<literal>[1, 2, 3.0]</literal> parses as an array of doubles. This is the most simple case of the type
inferencing in action.
</para>
<para>
<literal>[(1, 2), (3, 4.0)]</literal> causes the 2 to also be parsed as a double (but the 1 and 3 are still
integers).
</para>
<para>
<literal>["", nothing]</literal> parses as an array of maybe strings. The presence of
"<literal>nothing</literal>" clearly implies that the array elements are nullable.
</para>
<para>
<literal>[[], [""]]</literal> will parse properly because the type of the first (empty) array can be
inferred to be equal to the type of the second array (both are arrays of strings).
</para>
<para>
<literal>[b'hello', []]</literal> looks odd but will parse properly.
See <link linkend='gvariant-text-bytestrings'>Bytestrings</link>
</para>
<para>
And some examples of errors:
</para>
<para>
<literal>["hello", 42]</literal> fails to parse due to conflicting types.
</para>
<para>
<literal>[]</literal> will fail to parse without additional type information.
</para>
</refsect2>
<refsect2 id='gvariant-text-dictionaries'>
<title>Dictionaries and Dictionary Entries</title>
<para>
Dictionaries and dictionary entries are both specified using the <literal>{}</literal> characters.
</para>
<para>
The dictionary syntax is more commonly used. This is what the printer elects to use in the normal case of
dictionary entries appearing in an array (aka "a dictionary"). The separate syntax for dictionary entries
is typically only used for when the entries appear on their own, outside of an array (which is valid but
unusual). Of course, you are free to use the dictionary entry syntax within arrays but there is no good
reason to do so (and the printer itself will never do so). Note that, as with arrays, the type of empty
dictionaries must be established (either explicitly or through inference).
</para>
<para>
The dictionary syntax is the same as Python's syntax for dictionaries. Some examples:
</para>
<para>
<literal>@a{sv} {}</literal> parses as the empty dictionary of everyone's favourite type.
</para>
<para>
<literal>@a{sv} []</literal> is the same as above (owing to the fact that dictionaries are really arrays).
</para>
<para>
<literal>{1: "one", 2: "two", 3: "three"}</literal> parses as a dictionary mapping integers to strings.
</para>
<para>
The dictionary entry syntax looks just like a pair (2-tuple) that uses braces instead of parens. The
presence of a comma immediately following the key differentiates it from the dictionary syntax (which
features a colon after the first key). Some examples:
</para>
<para>
<literal>{1, "one"}</literal> is a free-standing dictionary entry that can be parsed on its own or as part
of another container value.
</para>
<para>
<literal>[{1, "one"}, {2, "two"}, {3, "three"}]</literal> is exactly equivalent to the dictionary example
given above.
</para>
</refsect2>
<refsect2 id='gvariant-text-variants'>
<title>Variants</title>
<para>
Variants are denoted using angle brackets (aka "XML brackets"), <literal>&lt;&gt;</literal>. They may not
be omitted.
</para>
<para>
Using <literal>&lt;&gt;</literal> effectively disrupts the type inferencing that occurs between array
elements. This can have positive and negative effects.
</para>
<para>
<literal>[&lt;"hello"&gt;, &lt;42&gt;]</literal> will parse whereas <literal>["hello", 42]</literal> would
not.
</para>
<para>
<literal>[&lt;['']&gt;, &lt;[]&gt;]</literal> will fail to parse even though <literal>[[''], []]</literal>
parses successfully. You would need to specify <literal>[&lt;['']&gt;, &lt;@as []&gt;]</literal>.
</para>
<para>
<literal>{"title": &lt;"frobit"&gt;, "enabled": &lt;true&gt;, "width": &lt;800&gt;}</literal> is an example of
perhaps the most pervasive use of both dictionaries and variants.
</para>
</refsect2>
<refsect2 id='gvariant-text-maybe-types'>
<title>Maybe Types</title>
<para>
The syntax for specifying maybe types is inspired by Haskell.
</para>
<para>
The null case is specified using the keyword <literal>nothing</literal> and the non-null case is explicitly
specified using the keyword <literal>just</literal>. GVariant allows <literal>just</literal> to be omitted
in every case that it is able to unambiguously determine the intention of the writer. There are two cases
where it must be specified:
</para>
<itemizedlist>
<listitem>
<para>when using nested maybes, in order to specify the <literal>just nothing</literal> case</para>
</listitem>
<listitem>
<para>
to establish the nullability of the type of a value without explicitly specifying its full type
</para>
</listitem>
</itemizedlist>
<para>
Some examples:
</para>
<para>
<literal>just 'hello'</literal> parses as a non-null nullable string.
</para>
<para>
<literal>@ms 'hello'</literal> is the same (demonstrating how <literal>just</literal> can be dropped if the type is already
known).
</para>
<para>
<literal>nothing</literal> will not parse wtihout extra type information.
</para>
<para>
<literal>@ms nothing</literal> parses as a null nullable string.
</para>
<para>
<literal>[just 3, nothing]</literal> is an array of nullable integers
</para>
<para>
<literal>[3, nothing]</literal> is the same as the above (demonstrating another place were
<literal>just</literal> can be dropped).
</para>
<para>
<literal>[3, just nothing]</literal> parses as an array of maybe maybe integers (type
<literal>'ammi'</literal>).
</para>
</refsect2>
<refsect2 id='gvariant-text-type-annotations'>
<title>Type Annotations</title>
<para>
Type annotations allow additional type information to be given to the parser. Depending on the context,
this type information can change the output of the parser, cause an error when parsing would otherwise have
succeeded or resolve an error when parsing would have otherwise failed.
</para>
<para>
Type annotations come in two forms: type codes and type keywords.
</para>
<para>
Type keywords can be seen as more verbose (and more legible) versions of a common subset of the type codes.
The type keywords <literal>boolean</literal>, <literal>byte</literal>, <literal>int16</literal>,
<literal>uint16</literal>, <literal>int32</literal>, <literal>uint32</literal>, <literal>handle</literal>,
<literal>int64</literal>, <literal>uint64</literal>, <literal>double</literal>, <literal>string</literal>,
<literal>objectpath</literal> and literal <literal>signature</literal> are each exactly equivalent to their
corresponding type code.
</para>
<para>
Type codes are an <literal>@</literal> ("at" sign) followed by a definite GVariant type string. Some
examples:
</para>
<para>
<literal>uint32 5</literal> causes the number to be parsed unsigned instead of signed (the default).
</para>
<para>
<literal>@u 5</literal> is the same
</para>
<para>
<literal>objectpath "/org/gnome/xyz"</literal> creates an object path instead of a normal string
</para>
<para>
<literal>@au []</literal> specifies the type of the empty array (which would not parse otherwise)
</para>
<para>
<literal>@ms ""</literal> indicates that a string value is meant to have a maybe type
</para>
</refsect2>
<refsect2 id='gvariant-text-bytestrings'>
<title>Bytestrings</title>
<para>
The bytestring syntax is a piece of syntactic sugar meant to complement the bytestring APIs in GVariant. It
constructs arrays of non-nul bytes (type '<literal>ay</literal>') with a nul terminator at the end. These are
normal C strings with no particular encoding enforced, so the bytes may not be valid UTF-8.
Bytestrings are a special case of byte arrays; byte arrays (also type '<literal>ay</literal>'), in the general
case, can contain nul at any position, and need not end with nul.
</para>
<para>
Bytestrings are specified with either <literal>b""</literal> or <literal>b''</literal>. As with strings,
there is no fundamental difference between the two different types of quotes.
</para>
<para>
Bytestrings support the full range of escapes that you would expect (ie: those supported by
<link linkend='g-strcompress'><function>g_strcompress()</function></link>. This includes the normal control
sequence escapes (as mentioned in the section on strings) as well as octal and hexadecimal escapes of the
forms <literal>\0nnn</literal> and <literal>\xnn</literal>.
</para>
<para>
<literal>b'abc'</literal> is equivalent to <literal>[byte 0x61, 0x62, 0x63, 0]</literal>.
</para>
<para>
When formatting arrays of bytes, the printer will choose to display the array as a bytestring if it contains
a nul character at the end and no other nul bytes within. Otherwise, it is formatted as a normal array.
</para>
</refsect2>
<refsect2 id='gvariant-text-positional'>
<title>Positional Parameters</title>
<para>
Positional parameters are not a part of the normal GVariant text format, but they are mentioned here because
they can be used with <link linkend='g-variant-new-parsed'><function>g_variant_new_parsed()</function></link>.
</para>
<para>
A positional parameter is indicated with a <literal>%</literal> followed by any valid
<link linkend='gvariant-format-strings'>GVariant Format String</link>. Variable arguments are collected as
specified by the format string and the resulting value is inserted at the current position.
</para>
<para>
This feature is best explained by example:
</para>
<informalexample><programlisting><![CDATA[char *t = "xyz";
gboolean en = false;
GVariant *value;
value = g_variant_new_parsed ("{'title': <%s>, 'enabled': <%b>}", t, en);]]></programlisting></informalexample>
<para>
This constructs a dictionary mapping strings to variants (type '<literal>a{sv}</literal>') with two items in
it. The key names are parsed from the string and the values for those keys are taken as variable arguments
parameters.
</para>
<para>
The arguments are always collected in the order that they appear in the string to be parsed. Format strings
that collect multiple arguments are permitted, so you may require more varargs parameters than the number of
<literal>%</literal> signs that appear. You can also give format strings that collect no arguments, but
there's no good reason to do so.
</para>
</refsect2>
</refsect1>
</refentry>

1178
docs/reference/glib/gvariant-varargs.xml Normal file
View file

File diff suppressed because it is too large Load diff

306
docs/reference/glib/mainloop-states.eps Normal file
View file

@ -0,0 +1,306 @@
%!PS-Adobe-2.0 EPSF-2.0
%%Title: mainloop-stages.eps
%%Creator: fig2dev Version 3.2 Patchlevel 3c
%%CreationDate: Wed Nov 29 12:23:52 2000
%%For: otaylor@fresnel.labs.redhat.com (Owen Taylor)
%%BoundingBox: 0 0 503 291
%%Magnification: 1.0000
%%EndComments
/$F2psDict 200 dict def
$F2psDict begin
$F2psDict /mtrx matrix put
/col-1 {0 setgray} bind def
/col0 {0.000 0.000 0.000 srgb} bind def
/col1 {0.000 0.000 1.000 srgb} bind def
/col2 {0.000 1.000 0.000 srgb} bind def
/col3 {0.000 1.000 1.000 srgb} bind def
/col4 {1.000 0.000 0.000 srgb} bind def
/col5 {1.000 0.000 1.000 srgb} bind def
/col6 {1.000 1.000 0.000 srgb} bind def
/col7 {1.000 1.000 1.000 srgb} bind def
/col8 {0.000 0.000 0.560 srgb} bind def
/col9 {0.000 0.000 0.690 srgb} bind def
/col10 {0.000 0.000 0.820 srgb} bind def
/col11 {0.530 0.810 1.000 srgb} bind def
/col12 {0.000 0.560 0.000 srgb} bind def
/col13 {0.000 0.690 0.000 srgb} bind def
/col14 {0.000 0.820 0.000 srgb} bind def
/col15 {0.000 0.560 0.560 srgb} bind def
/col16 {0.000 0.690 0.690 srgb} bind def
/col17 {0.000 0.820 0.820 srgb} bind def
/col18 {0.560 0.000 0.000 srgb} bind def
/col19 {0.690 0.000 0.000 srgb} bind def
/col20 {0.820 0.000 0.000 srgb} bind def
/col21 {0.560 0.000 0.560 srgb} bind def
/col22 {0.690 0.000 0.690 srgb} bind def
/col23 {0.820 0.000 0.820 srgb} bind def
/col24 {0.500 0.190 0.000 srgb} bind def
/col25 {0.630 0.250 0.000 srgb} bind def
/col26 {0.750 0.380 0.000 srgb} bind def
/col27 {1.000 0.500 0.500 srgb} bind def
/col28 {1.000 0.630 0.630 srgb} bind def
/col29 {1.000 0.750 0.750 srgb} bind def
/col30 {1.000 0.880 0.880 srgb} bind def
/col31 {1.000 0.840 0.000 srgb} bind def
end
save
newpath 0 291 moveto 0 0 lineto 503 0 lineto 503 291 lineto closepath clip newpath
-106.0 402.0 translate
1 -1 scale
/cp {closepath} bind def
/ef {eofill} bind def
/gr {grestore} bind def
/gs {gsave} bind def
/sa {save} bind def
/rs {restore} bind def
/l {lineto} bind def
/m {moveto} bind def
/rm {rmoveto} bind def
/n {newpath} bind def
/s {stroke} bind def
/sh {show} bind def
/slc {setlinecap} bind def
/slj {setlinejoin} bind def
/slw {setlinewidth} bind def
/srgb {setrgbcolor} bind def
/rot {rotate} bind def
/sc {scale} bind def
/sd {setdash} bind def
/ff {findfont} bind def
/sf {setfont} bind def
/scf {scalefont} bind def
/sw {stringwidth} bind def
/tr {translate} bind def
/tnt {dup dup currentrgbcolor
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add
4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
bind def
/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
4 -2 roll mul srgb} bind def
/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
/$F2psEnd {$F2psEnteredState restore end} def
$F2psBegin
%%Page: 1 1
10 setmiterlimit
0.06000 0.06000 sc
%
% Fig objects follow
%
/Times-Roman ff 270.00 scf sf
9300 6225 m
gs 1 -1 sc (Initial[n+1]) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
9300 6540 m
gs 1 -1 sc (\(Recursion\)) dup sw pop 2 div neg 0 rm col0 sh gr
% Polyline
15.000 slw
[60] 0 sd
n 1905 6000 m 1800 6000 1800 6420 105 arcto 4 {pop} repeat
1800 6525 3120 6525 105 arcto 4 {pop} repeat
3225 6525 3225 6105 105 arcto 4 {pop} repeat
3225 6000 1905 6000 105 arcto 4 {pop} repeat
cp gs col0 s gr [] 0 sd
% Polyline
[60] 0 sd
gs clippath
3865 5498 m 3806 5431 l 3688 5535 l 3808 5490 l 3747 5602 l cp
3184 5976 m 3243 6043 l 3361 5939 l 3242 5985 l 3302 5872 l cp
eoclip
n 3225 6000 m
3825 5475 l gs col0 s gr gr
[] 0 sd
% arrowhead
n 3302 5872 m 3242 5985 l 3361 5939 l 3302 5872 l cp gs 0.00 setgray ef gr col0 s
% arrowhead
n 3747 5602 m 3808 5490 l 3688 5535 l 3747 5602 l cp gs 0.00 setgray ef gr col0 s
% Polyline
n 4980 5775 m 4875 5775 4875 6270 105 arcto 4 {pop} repeat
4875 6375 6870 6375 105 arcto 4 {pop} repeat
6975 6375 6975 5880 105 arcto 4 {pop} repeat
6975 5775 4980 5775 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
[60] 0 sd
gs clippath
8457 5969 m 8515 5900 l 8394 5799 l 8458 5911 l 8337 5868 l cp
8042 5505 m 7984 5574 l 8105 5675 l 8042 5564 l 8162 5606 l cp
eoclip
n 8025 5550 m
8475 5925 l gs col0 s gr gr
[] 0 sd
% arrowhead
n 8162 5606 m 8042 5564 l 8105 5675 l 8162 5606 l cp gs 0.00 setgray ef gr col0 s
% arrowhead
n 8337 5868 m 8458 5911 l 8394 5799 l 8337 5868 l cp gs 0.00 setgray ef gr col0 s
% Polyline
[60] 0 sd
n 8580 5850 m 8475 5850 8475 6570 105 arcto 4 {pop} repeat
8475 6675 10020 6675 105 arcto 4 {pop} repeat
10125 6675 10125 5955 105 arcto 4 {pop} repeat
10125 5850 8580 5850 105 arcto 4 {pop} repeat
cp gs col0 s gr [] 0 sd
% Polyline
n 7155 3825 m 7050 3825 7050 4320 105 arcto 4 {pop} repeat
7050 4425 9045 4425 105 arcto 4 {pop} repeat
9150 4425 9150 3930 105 arcto 4 {pop} repeat
9150 3825 7155 3825 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
n 5055 2100 m 4950 2100 4950 2595 105 arcto 4 {pop} repeat
4950 2700 6945 2700 105 arcto 4 {pop} repeat
7050 2700 7050 2205 105 arcto 4 {pop} repeat
7050 2100 5055 2100 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
n 2730 3900 m 2625 3900 2625 4395 105 arcto 4 {pop} repeat
2625 4500 4620 4500 105 arcto 4 {pop} repeat
4725 4500 4725 4005 105 arcto 4 {pop} repeat
4725 3900 2730 3900 105 arcto 4 {pop} repeat
cp gs col0 s gr
% Polyline
[60] 0 sd
n 8580 1875 m 8475 1875 8475 2295 105 arcto 4 {pop} repeat
8475 2400 9645 2400 105 arcto 4 {pop} repeat
9750 2400 9750 1980 105 arcto 4 {pop} repeat
9750 1875 8580 1875 105 arcto 4 {pop} repeat
cp gs col0 s gr [] 0 sd
% Polyline
[60] 0 sd
gs clippath
8518 2419 m 8451 2358 l 8345 2474 l 8460 2416 l 8412 2534 l cp
8003 2848 m 8070 2909 l 8176 2793 l 8062 2852 l 8109 2733 l cp
eoclip
n 8047 2868 m
8475 2400 l gs col0 s gr gr
[] 0 sd
% arrowhead
n 8109 2733 m 8062 2852 l 8176 2793 l 8109 2733 l cp gs 0.00 setgray ef gr col0 s
% arrowhead
n 8412 2534 m 8460 2416 l 8345 2474 l 8412 2534 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
3340 4475 m 3252 4494 l 3286 4648 l 3305 4522 l 3374 4629 l cp
eoclip
n 4875 6075 m 4874 6075 l 4872 6074 l 4868 6073 l 4861 6072 l 4852 6070 l
4839 6067 l 4824 6064 l 4805 6059 l 4783 6054 l 4759 6048 l
4731 6041 l 4701 6033 l 4669 6025 l 4635 6015 l 4600 6004 l
4563 5993 l 4526 5981 l 4487 5967 l 4448 5953 l 4408 5937 l
4367 5920 l 4326 5901 l 4284 5881 l 4241 5859 l 4198 5835 l
4154 5809 l 4109 5781 l 4063 5749 l 4016 5715 l 3968 5678 l
3920 5638 l 3872 5595 l 3825 5550 l 3780 5503 l 3737 5455 l
3697 5407 l 3660 5359 l 3626 5312 l 3594 5266 l 3566 5221 l
3540 5177 l 3516 5134 l 3494 5091 l 3474 5049 l 3455 5008 l
3438 4967 l 3422 4927 l 3408 4888 l 3394 4849 l 3382 4812 l
3371 4775 l 3360 4740 l 3350 4706 l 3342 4674 l 3334 4644 l
3327 4616 l 3321 4592 l 3316 4570 l 3311 4551 l 3308 4536 l
3305 4523 l 3303 4514 l
3300 4500 l gs col0 s gr gr
% arrowhead
0 slj
n 3374 4629 m 3305 4522 l 3286 4648 l 3374 4629 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
6943 6114 m 6978 6197 l 7123 6135 l 6995 6141 l 7087 6052 l cp
eoclip
n 8475 4500 m 8475 4501 l 8475 4503 l 8475 4508 l 8475 4515 l 8474 4525 l
8474 4538 l 8473 4553 l 8472 4573 l 8470 4594 l 8468 4619 l
8465 4646 l 8462 4675 l 8457 4706 l 8452 4739 l 8445 4773 l
8437 4808 l 8427 4845 l 8416 4882 l 8403 4921 l 8388 4961 l
8370 5002 l 8350 5045 l 8326 5090 l 8299 5137 l 8268 5186 l
8232 5237 l 8192 5290 l 8148 5345 l 8100 5400 l 8057 5445 l
8013 5490 l 7968 5533 l 7923 5573 l 7878 5612 l 7833 5649 l
7789 5684 l 7745 5717 l 7701 5749 l 7658 5779 l 7615 5807 l
7573 5834 l 7531 5861 l 7489 5886 l 7447 5910 l 7407 5933 l
7366 5955 l 7327 5977 l 7288 5997 l 7250 6017 l 7214 6035 l
7180 6052 l 7147 6068 l 7117 6083 l 7090 6096 l 7065 6108 l
7043 6118 l 7025 6127 l 7010 6134 l 6998 6140 l 6989 6144 l
6975 6150 l gs col0 s gr gr
% arrowhead
0 slj
n 7087 6052 m 6995 6141 l 7123 6135 l 7087 6052 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
8433 3848 m 8521 3831 l 8493 3676 l 8471 3803 l 8404 3693 l cp
eoclip
n 7050 2400 m 7051 2400 l 7054 2401 l 7058 2401 l 7066 2403 l 7076 2404 l
7090 2407 l 7107 2410 l 7127 2414 l 7150 2418 l 7177 2424 l
7206 2430 l 7238 2437 l 7271 2445 l 7306 2454 l 7343 2463 l
7381 2474 l 7419 2486 l 7458 2499 l 7498 2513 l 7538 2528 l
7579 2545 l 7621 2564 l 7663 2585 l 7706 2608 l 7750 2634 l
7795 2662 l 7841 2694 l 7887 2728 l 7933 2766 l 7980 2807 l
8025 2850 l 8068 2895 l 8109 2942 l 8147 2988 l 8181 3034 l
8213 3080 l 8241 3125 l 8267 3169 l 8290 3212 l 8311 3254 l
8330 3296 l 8347 3337 l 8362 3377 l 8376 3417 l 8389 3456 l
8401 3494 l 8412 3532 l 8421 3569 l 8430 3604 l 8438 3637 l
8445 3669 l 8451 3698 l 8457 3725 l 8461 3748 l 8465 3768 l
8468 3785 l 8471 3799 l 8472 3809 l
8475 3825 l gs col0 s gr gr
% arrowhead
0 slj
n 8404 3693 m 8471 3803 l 8493 3676 l 8404 3693 l cp gs 0.00 setgray ef gr col0 s
% Polyline
2 slj
gs clippath
4970 2442 m 4959 2353 l 4803 2372 l 4928 2403 l 4814 2461 l cp
eoclip
n 3375 3900 m 3375 3899 l 3376 3897 l 3377 3892 l 3378 3886 l 3380 3876 l
3383 3863 l 3386 3848 l 3391 3828 l 3396 3806 l 3402 3781 l
3409 3753 l 3417 3722 l 3425 3689 l 3435 3655 l 3446 3619 l
3457 3581 l 3469 3543 l 3483 3504 l 3497 3464 l 3513 3423 l
3530 3383 l 3549 3341 l 3569 3299 l 3591 3257 l 3615 3214 l
3641 3170 l 3669 3125 l 3701 3080 l 3735 3034 l 3772 2988 l
3812 2941 l 3855 2895 l 3900 2850 l 3950 2804 l 4001 2762 l
4052 2723 l 4102 2687 l 4152 2655 l 4201 2625 l 4248 2599 l
4295 2576 l 4340 2555 l 4385 2536 l 4429 2519 l 4472 2504 l
4515 2490 l 4557 2477 l 4598 2466 l 4638 2456 l 4677 2447 l
4715 2439 l 4751 2432 l 4784 2426 l 4815 2420 l 4843 2415 l
4868 2411 l 4890 2408 l 4908 2406 l 4922 2404 l 4933 2402 l
4950 2400 l gs col0 s gr gr
% arrowhead
0 slj
n 4814 2461 m 4928 2403 l 4803 2372 l 4814 2461 l cp gs 0.00 setgray ef gr col0 s
/Times-Roman ff 360.00 scf sf
5925 6225 m
gs 1 -1 sc (Initial[n]) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 360.00 scf sf
8100 4275 m
gs 1 -1 sc (Dispatching) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 360.00 scf sf
3675 4350 m
gs 1 -1 sc (Prepared) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 360.00 scf sf
5925 2550 m
gs 1 -1 sc (Polling) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
4050 3300 m
gs 1 -1 sc (query\(\)) col0 sh gr
/Times-Roman ff 270.00 scf sf
7800 3225 m
gs 1 -1 sc (check\(\)) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
2475 6375 m
gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
3900 5400 m
gs 1 -1 sc (prepare\(\)) col0 sh gr
/Times-Roman ff 270.00 scf sf
8025 5325 m
gs 1 -1 sc (dispatch\(\)) dup sw pop neg 0 rm col0 sh gr
/Times-Roman ff 270.00 scf sf
9150 2250 m
gs 1 -1 sc (Working) dup sw pop 2 div neg 0 rm col0 sh gr
$F2psEnd
rs

65
docs/reference/glib/mainloop-states.fig Normal file
View file

@ -0,0 +1,65 @@
#FIG 3.2
Landscape
Center
Inches
Letter
100.00
Single
-2
1200 2
6 8625 6000 9975 6600
4 1 0 50 0 0 18 0.0000 4 240 1290 9300 6225 Initial[n+1]\001
4 1 0 50 0 0 18 0.0000 4 255 1335 9300 6540 (Recursion)\001
-6
2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
3225 6525 3225 6000 1800 6000 1800 6525 3225 6525
2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
1 1 2.00 90.00 120.00
1 1 2.00 90.00 120.00
3225 6000 3825 5475
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
6975 6375 6975 5775 4875 5775 4875 6375 6975 6375
2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
1 1 2.00 90.00 120.00
1 1 2.00 90.00 120.00
8025 5550 8475 5925
2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
10125 6675 10125 5850 8475 5850 8475 6675 10125 6675
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
9150 4425 9150 3825 7050 3825 7050 4425 9150 4425
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
7050 2700 7050 2100 4950 2100 4950 2700 7050 2700
2 4 0 2 0 7 50 0 -1 0.000 0 0 7 0 0 5
4725 4500 4725 3900 2625 3900 2625 4500 4725 4500
2 4 1 2 0 7 50 0 -1 4.000 0 0 7 0 0 5
9750 2400 9750 1875 8475 1875 8475 2400 9750 2400
2 1 1 2 0 7 50 0 -1 4.000 0 0 -1 1 1 2
1 1 2.00 90.00 120.00
1 1 2.00 90.00 120.00
8047 2868 8475 2400
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
4875 6075 3825 5550 3300 4500
0.000 -1.000 0.000
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
8475 4500 8100 5400 6975 6150
0.000 -1.000 0.000
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
7050 2400 8025 2850 8475 3825
0.000 -1.000 0.000
3 2 0 2 0 7 50 0 -1 0.000 0 1 0 3
1 1 2.00 90.00 120.00
3375 3900 3900 2850 4950 2400
0.000 -1.000 0.000
4 1 0 50 0 0 24 0.0000 4 315 1290 5925 6225 Initial[n]\001
4 1 0 50 0 0 24 0.0000 4 330 1770 8100 4275 Dispatching\001
4 1 0 50 0 0 24 0.0000 4 330 1320 3675 4350 Prepared\001
4 1 0 50 0 0 24 0.0000 4 330 1050 5925 2550 Polling\001
4 0 0 50 0 0 18 0.0000 4 255 825 4050 3300 query()\001
4 2 0 50 0 0 18 0.0000 4 255 855 7800 3225 check()\001
4 1 0 50 0 0 18 0.0000 4 255 990 2475 6375 Working\001
4 0 0 50 0 0 18 0.0000 4 255 1050 3900 5400 prepare()\001
4 2 0 50 0 0 18 0.0000 4 255 1140 8025 5325 dispatch()\001
4 1 0 50 0 0 18 0.0000 4 255 990 9150 2250 Working\001

BIN
docs/reference/glib/mainloop-states.gif Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
docs/reference/glib/mainloop-states.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 15 KiB

104
docs/reference/glib/meson.build Normal file
View file

@ -0,0 +1,104 @@
if get_option('gtk_doc')
subdir('xml')
ignore_headers = [
'gallocator.h',
'gdatasetprivate.h',
'glibintl.h',
'gbsearcharray.h',
'glib-private.h',
'gmoduleconf.h',
'grcboxprivate.h',
'gstdioprivate.h',
'gthreadprivate.h',
'gunibreak.h',
'gunicomp.h',
'gunidecomp.h',
'gunichartables.h',
'glib_probes.h',
'glib_trace.h',
'libcharset.h',
'gdebug.h',
'gprintfint.h',
'gmirroringtable.h',
'gscripttable.h',
'gtrace-private.h',
'glib-mirroring-tab',
'gnulib',
'gbytesprivate.h',
'gvariant-internal.h',
'gvariant-serialiser.h',
'gvariant-core.h',
'gvarianttypeinfo.h',
'gwakeup.h',
'gtranslit-data.h',
'glib-init.h',
'gconstructor.h',
'valgrind.h',
'gutilsprivate.h',
'gvalgrind.h',
'dirent.h',
]
docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
version_conf = configuration_data()
version_conf.set('GLIB_VERSION', meson.project_version())
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
)
gnome.gtkdoc('glib',
main_xml : 'glib-docs.xml',
namespace : 'g',
mode : 'none',
src_dir : [ 'glib', 'gmodule' ],
dependencies : libglib_dep,
scan_args : gtkdoc_common_scan_args + [
'--ignore-headers=' + ' '.join(ignore_headers),
],
content_files : [
'cross.xml',
'running.xml',
'building.xml',
'changes.xml',
'compiling.xml',
'programming.xml',
'resources.xml',
'regex-syntax.xml',
'glib-gettextize.xml',
'gtester.xml',
'gtester-report.xml',
'gvariant-varargs.xml',
'gvariant-text.xml',
],
expand_content_files : [
'compiling.xml',
],
html_assets : [
'file-name-encodings.png',
'mainloop-states.gif',
'Sorted_binary_tree_breadth-first_traversal.svg',
'Sorted_binary_tree_inorder.svg',
'Sorted_binary_tree_postorder.svg',
'Sorted_binary_tree_preorder.svg',
],
fixxref_args: [
'--html-dir=' + docpath,
],
install: true,
check: true)
endif
if get_option('man')
manpages = ['glib-gettextize', 'gtester', 'gtester-report']
foreach page : manpages
custom_target(page + '-man',
input: page + '.xml',
output: page + '.1',
command: xsltproc_command,
install: true,
install_dir: man1_dir)
endforeach
endif

67
docs/reference/glib/programming.xml Normal file
View file

@ -0,0 +1,67 @@
<?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>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>
See the sections on <link linkend="glib-Threads">threads</link> and
<link linkend="glib-Thread-Pools">threadpools</link> for GLib APIs that
support multithreaded applications.
</para>
</refsect2>
<refsect2>
<title>Security</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 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.
</para>
</refsect2>
</refsect1>
</refentry>

2531
docs/reference/glib/regex-syntax.xml Normal file
View file

File diff suppressed because it is too large Load diff

77
docs/reference/glib/resources.xml Normal file
View file

@ -0,0 +1,77 @@
<?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-resources" revision="17 Jan 2002">
<refmeta>
<refentrytitle>Mailing lists and bug reports</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>Mailing lists and bug reports</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Mailing lists and bug reports</refname>
<refpurpose>
Getting help with GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Filing a bug report or feature request</title>
<para>
If you encounter a bug, misfeature, or missing feature in GLib, please
file a bug report on the issue tracker at
<ulink url="https://gitlab.gnome.org/GNOME/glib/issues/new">https://gitlab.gnome.org/GNOME/glib/issues/new</ulink>.
We'd also appreciate reports of incomplete or misleading information in
the GLib documentation; file those with the ‘Documentation’ label.
</para>
<para>
Don't hesitate to file a bug report, even if you think we may know
about it already, or aren't sure of the details. Just give us as much
information as you have, and if it's already fixed or has already been
discussed, we'll add a note to that effect in the report.
</para>
<para>
The issue tracker should definitely be used for feature requests, it's
not only for bugs. We track all GLib development in GitLab, so it's
the way to be sure the GLib developers won't forget about an issue.
</para>
</refsect1>
<refsect1>
<title>Code Contributions</title>
<para>
If you develop a bugfix or enhancement for GLib, please open a merge request
for that in GitLab as well. All branches must be offered under the terms of
the GNU LGPL license, so be sure you are authorized to give us the branch
under those terms.
</para>
<para>
If you want to discuss your branch before or after developing it, open a
topic on <ulink url="https://discourse.gnome.org/tags/glib">Discourse</ulink>.
But be sure to create the GitLab merge request as well; if the branch is only
on the list and not in GitLab, it's likely to slip through the cracks.
</para>
</refsect1>
<refsect1>
<title>Discussions and user questions</title>
<para>
The <ulink url="https://gitlab.gnome.org/GNOME/glib/issues">GLib issue tracker</ulink>
is meant for discussions with actionable topics. If you want to ask a question
about using GLib, or discuss new features, you should use
<ulink url="https://discourse.gnome.org/tags/glib">the glib tag on Discourse</ulink>.
</para>
</refsect1>
</refentry>

414
docs/reference/glib/running.xml Normal file
View file

@ -0,0 +1,414 @@
<?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-running">
<refmeta>
<refentrytitle>Running GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Running GLib Applications</refname>
<refpurpose>
How to run and debug your GLib application
</refpurpose>
</refnamediv>
<refsect1>
<title>Running and debugging GLib Applications</title>
<refsect2>
<title>Environment variables</title>
<para>
The runtime behaviour of GLib applications can be influenced by a
number of environment variables.
</para>
<formalpara>
<title>Standard variables</title>
<para>
GLib reads standard environment variables like <envar>LANG</envar>,
<envar>PATH</envar>, <envar>HOME</envar>, <envar>TMPDIR</envar>,
<envar>TZ</envar> and <envar>LOGNAME</envar>.
</para>
</formalpara>
<formalpara>
<title>XDG directories</title>
<para>
GLib consults the environment variables <envar>XDG_DATA_HOME</envar>,
<envar>XDG_DATA_DIRS</envar>, <envar>XDG_CONFIG_HOME</envar>,
<envar>XDG_CONFIG_DIRS</envar>, <envar>XDG_CACHE_HOME</envar> and
<envar>XDG_RUNTIME_DIR</envar> for the various XDG directories.
For more information, see the <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG basedir spec</ulink>.
</para>
</formalpara>
<formalpara id="G_FILENAME_ENCODING">
<title><envar>G_FILENAME_ENCODING</envar></title>
<para>
This environment variable can be set to a comma-separated list of character
set names. GLib assumes that filenames are encoded in the first character
set from that list rather than in UTF-8. The special token "@locale" can be
used to specify the character set for the current locale.
</para>
</formalpara>
<formalpara id="G_BROKEN_FILENAMES">
<title><envar>G_BROKEN_FILENAMES</envar></title>
<para>
If this environment variable is set, GLib assumes that filenames are in
the locale encoding rather than in UTF-8. G_FILENAME_ENCODING takes
priority over G_BROKEN_FILENAMES.
</para>
</formalpara>
<formalpara id="G_MESSAGES_PREFIXED">
<title><envar>G_MESSAGES_PREFIXED</envar></title>
<para>
A list of log levels for which messages should be prefixed by the
program name and PID of the application. The default is to prefix
everything except <literal>G_LOG_LEVEL_MESSAGE</literal> and
<literal>G_LOG_LEVEL_INFO</literal>.
The possible values are
<literal>error</literal>,
<literal>warning</literal>,
<literal>critical</literal>,
<literal>message</literal>,
<literal>info</literal> and
<literal>debug</literal>.
You can also use the special values
<literal>all</literal> and
<literal>help</literal>.
</para>
<para>
This environment variable only affects the default log handler,
g_log_default_handler().
</para>
</formalpara>
<formalpara id="G_MESSAGES_DEBUG">
<title><envar>G_MESSAGES_DEBUG</envar></title>
<para>
A space-separated list of log domains for which informational
and debug messages should be printed. By default, these
messages are not printed.
</para>
<para>
You can also use the special value <literal>all</literal>.
</para>
<para>
This environment variable only affects the default log handler,
g_log_default_handler().
</para>
</formalpara>
<formalpara id="G-DEBUG:CAPS">
<title><envar>G_DEBUG</envar></title>
<para>
This environment variable can be set to a list of debug options,
which cause GLib to print out different types of debugging information.
<variablelist>
<varlistentry>
<term>fatal-warnings</term>
<listitem><para>Causes GLib to abort the program at the first call
to g_warning() or g_critical(). Use of this flag is not
recommended except when debugging.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fatal-criticals</term>
<listitem><para>Causes GLib to abort the program at the first call
to g_critical(). This flag can be useful during debugging and
testing.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>gc-friendly</term>
<listitem><para>Newly allocated memory that isn't directly initialized,
as well as memory being freed will be reset to 0. The point here is
to allow memory checkers and similar programs that use Boehm GC alike
algorithms to produce more accurate results.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>resident-modules</term>
<listitem><para>All modules loaded by GModule will be made resident.
This can be useful for tracking memory leaks in modules which are
later unloaded; but it can also hide bugs where code is accessed
after the module would have normally been unloaded.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>bind-now-modules</term>
<listitem><para>All modules loaded by GModule will bind their symbols
at load time, even when the code uses %G_MODULE_BIND_LAZY.</para>
</listitem>
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn on all debug options.
The special value <literal>help</literal> can be used to print all available options.
</para>
</formalpara>
<formalpara id="G_SLICE">
<title><envar>G_SLICE</envar></title>
<para>
This environment variable allows reconfiguration of the GSlice
memory allocator.
<variablelist>
<varlistentry>
<term>always-malloc</term>
<listitem><para>This will cause all slices allocated through
g_slice_alloc() and released by g_slice_free1() to be actually
allocated via direct calls to g_malloc() and g_free().
This is most useful for memory checkers and similar programs that
use Boehm GC alike algorithms to produce more accurate results.
It can also be in conjunction with debugging features of the system's
malloc() implementation such as glibc's MALLOC_CHECK_=2 to debug
erroneous slice allocation code, although
<literal>debug-blocks</literal> is usually a better suited debugging
tool.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>debug-blocks</term>
<listitem><para>Using this option (present since GLib 2.13) engages
extra code which performs sanity checks on the released memory
slices. Invalid slice addresses or slice sizes will be reported and
lead to a program halt. This option is for debugging scenarios.
In particular, client packages sporting their own test suite should
<emphasis>always enable this option when running tests</emphasis>.
Global slice validation is ensured by storing size and address
information for each allocated chunk, and maintaining a global
hash table of that data. That way, multi-thread scalability is
given up, and memory consumption is increased. However, the
resulting code usually performs acceptably well, possibly better
than with comparable memory checking carried out using external
tools.</para>
<para>An example of a memory corruption scenario that cannot be
reproduced with <literal>G_SLICE=always-malloc</literal>, but will
be caught by <literal>G_SLICE=debug-blocks</literal> is as follows:
<programlisting>
/* void* gives up type-safety */
void *slist = g_slist_alloc ();
/* corruption: sizeof (GSList) != sizeof (GList) */
g_list_free (slist);
</programlisting></para>
</listitem>
</varlistentry>
</variablelist>
The special value <literal>all</literal> can be used to turn on all options.
The special value <literal>help</literal> can be used to print all available options.
</para>
</formalpara>
<formalpara id="G_RANDOM_VERSION">
<title><envar>G_RANDOM_VERSION</envar></title>
<para>
If this environment variable is set to '2.0', the outdated
pseudo-random number seeding and generation algorithms from
GLib 2.0 are used instead of the newer, better ones. You should
only set this variable if you have sequences of numbers that were
generated with Glib 2.0 that you need to reproduce exactly.
</para>
</formalpara>
<formalpara id="LIBCHARSET_ALIAS_DIR">
<title><envar>LIBCHARSET_ALIAS_DIR</envar></title>
<para>
Allows to specify a nonstandard location for the
<filename>charset.aliases</filename> file that is used by the
character set conversion routines. The default location is the
<replaceable>libdir</replaceable> specified at compilation time.
</para>
</formalpara>
<formalpara id="TZDIR">
<title><envar>TZDIR</envar></title>
<para>
Allows to specify a nonstandard location for the timezone data files
that are used by the #GDateTime API. The default location is under
<filename>/usr/share/zoneinfo</filename>. For more information,
also look at the <command>tzset</command> manual page.
</para>
</formalpara>
<formalpara id="G_ENABLE_DIAGNOSTIC">
<title><envar>G_ENABLE_DIAGNOSTIC</envar></title>
<para>
If set to a non-zero value, this environment variable enables
diagnostic messages, like deprecation messages for GObject properties
and signals.
</para>
</formalpara>
<formalpara id="G_DEBUGGER">
<title><envar>G_DEBUGGER</envar></title>
<para>
When running on Windows, if set to a non-empty string, GLib will
try to interpret the contents of this environment variable as
a command line to a debugger, and run it if the process crashes.
The debugger command line should contain <literal>%p</literal> and <literal>%e</literal> substitution
tokens, which GLib will replace with the process ID of the crashing
process and a handle to an event that the debugger should signal
to let GLib know that the debugger successfully attached to the
process. If <literal>%e</literal> is absent, or if the debugger is not able to
signal events, GLib will resume execution after 60 seconds.
If <literal>%p</literal> is absent, the debugger won't know which process to attach to,
and GLib will also resume execution after 60 seconds.
</para>
<para>
Additionally, even if <envar>G_DEBUGGER</envar> is not set, GLib would still
try to print basic exception information (code and address) into
stderr.
</para>
<para>
By default the debugger gets a new console allocated for it.
Set the <envar>G_DEBUGGER_OLD_CONSOLE</envar> environment variable to any
non-empty string to make the debugger inherit the console of
the crashing process. Normally this is only used by the GLib
testsuite.
</para>
<para>
The exception handler is written with the aim of making it as
simple as possible, to minimize the risk of it invoking
buggy functions or running buggy code, which would result
in exceptions being raised recursively. Because of that
it lacks most of the amenities that one would expect of GLib.
Namely, it does not support Unicode, so it is highly advisable
to only use ASCII characters in <envar>G_DEBUGGER</envar>.
</para>
<para>
See also <link linkend="G_VEH_CATCH"><envar>G_VEH_CATCH</envar></link>.
</para>
</formalpara>
<formalpara id="G_VEH_CATCH">
<title><envar>G_VEH_CATCH</envar></title>
<para>
Catching some exceptions can break the program, since Windows
will sometimes use exceptions for execution flow control and
other purposes other than signalling a crash.
</para>
<para>
The <envar>G_VEH_CATCH</envar> environment variable augments
<ulink url="https://docs.microsoft.com/en-us/windows/desktop/debug/vectored-exception-handling">Vectored Exception Handling</ulink>
on Windows (see <link linkend="G_DEBUGGER"><envar>G_DEBUGGER</envar></link>), allowing GLib to catch more
exceptions. Set this variable to a comma-separated list of
hexadecimal exception codes that should additionally be caught.
</para>
<para>
By default GLib will only catch Access Violation, Stack Overflow and
Illegal Instruction <ulink url="https://docs.microsoft.com/en-us/windows/desktop/api/winnt/ns-winnt-_exception_record">exceptions</ulink>.
</para>
</formalpara>
</refsect2>
<refsect2 id="setlocale">
<title>Locale</title>
<para>
A number of interfaces in GLib depend on the current locale in which
an application is running. Therefore, most GLib-using applications should
call <function>setlocale (LC_ALL, "")</function> to set up the current
locale.
</para>
<para>
On Windows, in a C program there are several locale concepts
that not necessarily are synchronized. On one hand, there is the
system default ANSI code-page, which determines what encoding is used
for file names handled by the C library's functions and the Win32
API. (We are talking about the "narrow" functions here that take
character pointers, not the "wide" ones.)
</para>
<para>
On the other hand, there is the C library's current locale. The
character set (code-page) used by that is not necessarily the same as
the system default ANSI code-page. Strings in this character set are
returned by functions like <function>strftime()</function>.
</para>
</refsect2>
<para>
GLib ships with a set of Python macros for the GDB debugger. These includes pretty
printers for lists, hashtables and GObject types. It also has a backtrace filter
that makes backtraces with signal emissions easier to read.
</para>
<para>
To use this you need a version of GDB that supports Python scripting; anything
from 7.0 should be fine. You then need to install GLib in the same prefix as
GDB so that the Python GDB autoloaded files get installed in the right place
for GDB to pick up.
</para>
<para>
General pretty printing should just happen without having to do anything special.
To get the signal emission filtered backtrace you must use the "new-backtrace" command
instead of the standard one.
</para>
<para>
There is also a new command called gforeach that can be used to apply a command
on each item in a list. E.g. you can do
<programlisting>
gforeach i in some_list_variable: print *(GtkWidget *)l
</programlisting>
Which would print the contents of each widget in a list of widgets.
</para>
<refsect2>
<title>SystemTap</title>
<para>
<ulink url="http://sourceware.org/systemtap/">SystemTap</ulink> is a dynamic whole-system
analysis toolkit. GLib ships with a file <filename>libglib-2.0.so.*.stp</filename> which defines a
set of probe points, which you can hook into with custom SystemTap scripts.
See the files <filename>libglib-2.0.so.*.stp</filename>, <filename>libgobject-2.0.so.*.stp</filename>
and <filename>libgio-2.0.so.*.stp</filename> which
are in your shared SystemTap scripts directory.
</para>
</refsect2>
<refsect2>
<title>Memory statistics</title>
<para>
g_mem_profile() will output a summary g_malloc() memory usage, if memory
profiling has been enabled by calling
<literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup.
</para>
<para>
If GLib has been configured with <option>--enable-debug=yes</option>,
then g_slice_debug_tree_statistics() can be called in a debugger to
output details about the memory usage of the slice allocator.
</para>
</refsect2>
</refsect1>
</refentry>

1
docs/reference/glib/version.xml.in Normal file
View file

@ -0,0 +1 @@
@GLIB_VERSION@

8
docs/reference/glib/xml/gtkdocentities.ent.in Normal file
View file

@ -0,0 +1,8 @@
<!ENTITY package "@PACKAGE@">
<!ENTITY package_bugreport "@PACKAGE_BUGREPORT@">
<!ENTITY package_name "@PACKAGE_NAME@">
<!ENTITY package_string "@PACKAGE_STRING@">
<!ENTITY package_tarname "@PACKAGE_TARNAME@">
<!ENTITY package_url "@PACKAGE_URL@">
<!ENTITY package_version "@PACKAGE_VERSION@">
<!ENTITY package_api_version "@PACKAGE_API_VERSION@">

14
docs/reference/glib/xml/meson.build Normal file
View file

@ -0,0 +1,14 @@
ent_conf = configuration_data()
ent_conf.set('PACKAGE', 'glib')
ent_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.gnome.org/GNOME/glib/issues/new')
ent_conf.set('PACKAGE_NAME', 'glib')
ent_conf.set('PACKAGE_STRING', 'glib')
ent_conf.set('PACKAGE_TARNAME', 'glib')
ent_conf.set('PACKAGE_URL', 'FIXME')
ent_conf.set('PACKAGE_VERSION', glib_version)
ent_conf.set('PACKAGE_API_VERSION', glib_api_version)
configure_file(
input: 'gtkdocentities.ent.in',
output: 'gtkdocentities.ent',
configuration: ent_conf
)