luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-24 14:36:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'migrate-to-gi-docgen14' into 'main'

Browse Source 
Switch to using gi-docgen for docs (batch 14)

Closes #3037

See merge request GNOME/glib!3724
This commit is contained in:
Philip Withnall 2023-11-28 14:06:23 +00:00
commit ded4976337
91 changed files with 2557 additions and 16687 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/reference/gio/concat-files-helper.py
View File

@ -1,36 +0,0 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# Copyright (C) 2018 Collabora Inc.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General
# Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
#
# Author: Xavier Claessens <xavier.claessens@collabora.com>
import os
import sys
if len(sys.argv) < 3:
print(
"Usage: {} <output file> <input file 1> ...".format(
os.path.basename(sys.argv[0])
)
)
sys.exit(1)
with open(sys.argv[1], "w") as outfile:
for fname in sys.argv[2:]:
with open(fname) as infile:
for line in infile:
outfile.write(line)

1
docs/reference/gio/gdbus-object-manager-example/.gitignore vendored
View File

@ -1 +0,0 @@
gdbus-object-manager-example-overrides.txt

19
docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-docs.xml
View File

@ -1,19 +0,0 @@
<?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'">
]>
<book lang="en" xmlns:xi="http://www.w3.org/2003/XInclude">
<part>
<title>GDBus ObjctManager Example</title>
<chapter>
<title>Interfaces</title>
<xi:include href="xml/ExampleAnimal.xml"/>
<xi:include href="xml/ExampleCat.xml"/>
<xi:include href="xml/ExampleObject.xml"/>
<xi:include href="xml/ExampleObjectManagerClient.xml"/>
</chapter>
</part>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

161
docs/reference/gio/gdbus-object-manager-example/gdbus-object-manager-example-sections.txt
View File

@ -1,161 +0,0 @@
<SECTION>
<FILE>ExampleAnimal</FILE>
<TITLE>ExampleAnimal</TITLE>
ExampleAnimal
ExampleAnimalIface
example_animal_interface_info
example_animal_override_properties
example_animal_call_poke
example_animal_call_poke_finish
example_animal_call_poke_sync
example_animal_complete_poke
example_animal_emit_jumped
example_animal_get_mood
example_animal_get_foo
example_animal_get_bar
example_animal_dup_mood
example_animal_dup_foo
example_animal_dup_bar
example_animal_set_mood
example_animal_set_foo
example_animal_set_bar
ExampleAnimalProxy
ExampleAnimalProxyClass
example_animal_proxy_new
example_animal_proxy_new_finish
example_animal_proxy_new_sync
example_animal_proxy_new_for_bus
example_animal_proxy_new_for_bus_finish
example_animal_proxy_new_for_bus_sync
ExampleAnimalSkeleton
ExampleAnimalSkeletonClass
example_animal_skeleton_new
<SUBSECTION Standard>
example_animal_get_type
example_animal_proxy_get_type
example_animal_skeleton_get_type
ExampleAnimalSkeletonPrivate
ExampleAnimalProxyPrivate
EXAMPLE_TYPE_ANIMAL
EXAMPLE_TYPE_ANIMAL_PROXY
EXAMPLE_TYPE_ANIMAL_SKELETON
EXAMPLE_ANIMAL
EXAMPLE_ANIMAL_GET_IFACE
EXAMPLE_ANIMAL_PROXY
EXAMPLE_ANIMAL_PROXY_CLASS
EXAMPLE_ANIMAL_PROXY_GET_CLASS
EXAMPLE_ANIMAL_SKELETON
EXAMPLE_ANIMAL_SKELETON_CLASS
EXAMPLE_ANIMAL_SKELETON_GET_CLASS
EXAMPLE_IS_ANIMAL
EXAMPLE_IS_ANIMAL_PROXY
EXAMPLE_IS_ANIMAL_PROXY_CLASS
EXAMPLE_IS_ANIMAL_SKELETON
EXAMPLE_IS_ANIMAL_SKELETON_CLASS
</SECTION>
<SECTION>
<FILE>ExampleCat</FILE>
<TITLE>ExampleCat</TITLE>
ExampleCat
ExampleCatIface
example_cat_interface_info
example_cat_override_properties
ExampleCatProxy
ExampleCatProxyClass
example_cat_proxy_new
example_cat_proxy_new_finish
example_cat_proxy_new_sync
example_cat_proxy_new_for_bus
example_cat_proxy_new_for_bus_finish
example_cat_proxy_new_for_bus_sync
ExampleCatSkeleton
ExampleCatSkeletonClass
example_cat_skeleton_new
<SUBSECTION Standard>
example_cat_get_type
example_cat_proxy_get_type
example_cat_skeleton_get_type
ExampleCatProxyPrivate
ExampleCatSkeletonPrivate
EXAMPLE_TYPE_CAT
EXAMPLE_TYPE_CAT_PROXY
EXAMPLE_TYPE_CAT_SKELETON
EXAMPLE_CAT
EXAMPLE_CAT_GET_IFACE
EXAMPLE_CAT_PROXY
EXAMPLE_CAT_PROXY_CLASS
EXAMPLE_CAT_PROXY_GET_CLASS
EXAMPLE_CAT_SKELETON
EXAMPLE_CAT_SKELETON_CLASS
EXAMPLE_CAT_SKELETON_GET_CLASS
EXAMPLE_IS_CAT
EXAMPLE_IS_CAT_PROXY
EXAMPLE_IS_CAT_PROXY_CLASS
EXAMPLE_IS_CAT_SKELETON
EXAMPLE_IS_CAT_SKELETON_CLASS
</SECTION>
<SECTION>
<FILE>ExampleObject</FILE>
<TITLE>ExampleObject</TITLE>
ExampleObject
ExampleObjectIface
example_object_get_animal
example_object_get_cat
example_object_peek_animal
example_object_peek_cat
ExampleObjectProxy
ExampleObjectProxyClass
example_object_proxy_new
ExampleObjectSkeleton
ExampleObjectSkeletonClass
example_object_skeleton_new
example_object_skeleton_set_animal
example_object_skeleton_set_cat
<SUBSECTION Standard>
example_object_get_type
example_object_proxy_get_type
example_object_skeleton_get_type
ExampleObjectProxyPrivate
ExampleObjectSkeletonPrivate
EXAMPLE_IS_OBJECT
EXAMPLE_IS_OBJECT_PROXY
EXAMPLE_IS_OBJECT_PROXY_CLASS
EXAMPLE_IS_OBJECT_SKELETON
EXAMPLE_IS_OBJECT_SKELETON_CLASS
EXAMPLE_OBJECT
EXAMPLE_OBJECT_GET_IFACE
EXAMPLE_OBJECT_PROXY
EXAMPLE_OBJECT_PROXY_CLASS
EXAMPLE_OBJECT_PROXY_GET_CLASS
EXAMPLE_OBJECT_SKELETON
EXAMPLE_OBJECT_SKELETON_CLASS
EXAMPLE_OBJECT_SKELETON_GET_CLASS
EXAMPLE_TYPE_OBJECT
EXAMPLE_TYPE_OBJECT_PROXY
EXAMPLE_TYPE_OBJECT_SKELETON
</SECTION>
<SECTION>
<FILE>ExampleObjectManagerClient</FILE>
<TITLE>ExampleObjectManagerClient</TITLE>
ExampleObjectManagerClient
ExampleObjectManagerClientClass
example_object_manager_client_get_proxy_type
example_object_manager_client_new
example_object_manager_client_new_finish
example_object_manager_client_new_sync
example_object_manager_client_new_for_bus
example_object_manager_client_new_for_bus_finish
example_object_manager_client_new_for_bus_sync
<SUBSECTION Standard>
example_object_manager_client_get_type
EXAMPLE_IS_OBJECT_MANAGER_CLIENT
EXAMPLE_IS_OBJECT_MANAGER_CLIENT_CLASS
EXAMPLE_OBJECT_MANAGER_CLIENT
EXAMPLE_OBJECT_MANAGER_CLIENT_CLASS
EXAMPLE_OBJECT_MANAGER_CLIENT_GET_CLASS
EXAMPLE_TYPE_OBJECT_MANAGER_CLIENT
ExampleObjectManagerClientPrivate
</SECTION>

11
docs/reference/gio/gdbus-object-manager-example/meson.build
View File

@ -1,11 +0,0 @@
gdbus_object_manager_example_doc = gnome.gtkdoc('gdbus-object-manager-example',
main_xml : 'gdbus-object-manager-example-docs.xml',
namespace : 'example',
dependencies : [libgdbus_example_objectmanager_dep],
src_dir : 'gio/tests/gdbus-object-manager-example',
scan_args : [
'--rebuild-types',
],
install : false,
)

3
docs/reference/gio/gio-docs-unix.xml
View File

@ -1,3 +0,0 @@
<chapter id='unix-support'>
<!--FIXME: fill this with unix APIs that cannot build on Windows -->
</chapter>

6
docs/reference/gio/gio-docs-win32.xml
View File

@ -1,6 +0,0 @@
<chapter id='win32-support'>
<title>Win32 support</title>
<xi:include href="xml/gwin32registrykey.xml"/>
<xi:include href="xml/gwin32inputstream.xml"/>
<xi:include href="xml/gwin32outputstream.xml"/>
</chapter>

417
docs/reference/gio/gio-docs.xml
View File

@ -1,417 +0,0 @@
<?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 lang="en" id="gio" xmlns:xi="http://www.w3.org/2003/XInclude">
<title>GIO Reference Manual</title>
<bookinfo>
<title>GIO Reference Manual</title>
<releaseinfo>
for GIO &version;
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.gnome.org/gio/unstable/">https://developer.gnome.org/gio/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<part>
<title>API Reference</title>
<chapter id="file_ops">
<title>File Operations</title>
<xi:include href="xml/gfile.xml"/>
<xi:include href="xml/gfileattribute.xml"/>
<xi:include href="xml/gfileinfo.xml"/>
<xi:include href="xml/gfileenumerator.xml"/>
<xi:include href="xml/gioerror.xml"/>
<xi:include href="xml/gmountoperation.xml"/>
</chapter>
<chapter id="file_mon">
<title>File System Monitoring</title>
<xi:include href="xml/gfilemonitor.xml"/>
</chapter>
<chapter id="utils">
<title>File-related Utilities</title>
<xi:include href="xml/gfilenamecompleter.xml"/>
</chapter>
<chapter id="async">
<title>Asynchronous I/O</title>
<xi:include href="xml/gcancellable.xml"/>
<xi:include href="xml/gasyncresult.xml"/>
<xi:include href="xml/gtask.xml"/>
<xi:include href="xml/gioscheduler.xml"/>
<xi:include href="xml/gsimpleasyncresult.xml"/>
</chapter>
<chapter id="conversion">
<title>Data conversion</title>
<xi:include href="xml/gconverter.xml"/>
<xi:include href="xml/gcharsetconverter.xml"/>
<xi:include href="xml/gzlibcompressor.xml"/>
<xi:include href="xml/gzlibdecompressor.xml"/>
</chapter>
<chapter id="streaming">
<title>Streaming I/O</title>
<xi:include href="xml/gseekable.xml"/>
<xi:include href="xml/ginputstream.xml"/>
<xi:include href="xml/goutputstream.xml"/>
<xi:include href="xml/giostream.xml"/>
<xi:include href="xml/gsimpleiostream.xml"/>
<xi:include href="xml/gfileinputstream.xml"/>
<xi:include href="xml/gfileoutputstream.xml"/>
<xi:include href="xml/gfileiostream.xml"/>
<xi:include href="xml/gfiledescriptorbased.xml"/>
<xi:include href="xml/gfilterinputstream.xml"/>
<xi:include href="xml/gfilteroutputstream.xml"/>
<xi:include href="xml/gmemoryinputstream.xml"/>
<xi:include href="xml/gmemoryoutputstream.xml"/>
<xi:include href="xml/gbufferedinputstream.xml"/>
<xi:include href="xml/gbufferedoutputstream.xml"/>
<xi:include href="xml/gdatainputstream.xml"/>
<xi:include href="xml/gdataoutputstream.xml"/>
<xi:include href="xml/gunixinputstream.xml"/>
<xi:include href="xml/gunixoutputstream.xml"/>
<xi:include href="xml/gconverterinputstream.xml"/>
<xi:include href="xml/gconverteroutputstream.xml"/>
<xi:include href="xml/gpollableinputstream.xml"/>
<xi:include href="xml/gpollableoutputstream.xml"/>
<xi:include href="xml/gpollableutils.xml"/>
</chapter>
<chapter id="types">
<title>File types and applications</title>
<xi:include href="xml/gcontenttype.xml"/>
<xi:include href="xml/gappinfo.xml"/>
<xi:include href="xml/gappinfomonitor.xml"/>
<xi:include href="xml/gdesktopappinfo.xml"/>
</chapter>
<chapter id="volume_mon">
<title>Volumes and Drives</title>
<xi:include href="xml/gvolumemonitor.xml"/>
<xi:include href="xml/gvolume.xml"/>
<xi:include href="xml/gmount.xml"/>
<xi:include href="xml/gdrive.xml"/>
<xi:include href="xml/gunixmounts.xml"/>
</chapter>
<chapter id="icons">
<title>Icons</title>
<xi:include href="xml/gicon.xml"/>
<xi:include href="xml/gfileicon.xml"/>
<xi:include href="xml/gbytesicon.xml"/>
<xi:include href="xml/gloadableicon.xml"/>
<xi:include href="xml/gthemedicon.xml"/>
<xi:include href="xml/gemblemedicon.xml"/>
<xi:include href="xml/gemblem.xml"/>
</chapter>
<chapter id="failable_initialization">
<title>Failable Initialization</title>
<xi:include href="xml/ginitable.xml"/>
<xi:include href="xml/gasyncinitable.xml"/>
</chapter>
<chapter id="subprocesses">
<title>Subprocesses</title>
<xi:include href="xml/gsubprocess.xml"/>
<xi:include href="xml/gsubprocesslauncher.xml"/>
</chapter>
<chapter id="networking">
<title>Low-level network support</title>
<xi:include href="xml/gsocket.xml"/>
<xi:include href="xml/gdatagrambased.xml"/>
<xi:include href="xml/ginetaddress.xml"/>
<xi:include href="xml/ginetaddressmask.xml"/>
<xi:include href="xml/gsocketaddress.xml"/>
<xi:include href="xml/ginetsocketaddress.xml"/>
<xi:include href="xml/gunixsocketaddress.xml"/>
<xi:include href="xml/gnativesocketaddress.xml"/>
<xi:include href="xml/gsocketcontrolmessage.xml"/>
<xi:include href="xml/gunixfdlist.xml"/>
<xi:include href="xml/gunixfdmessage.xml"/>
<xi:include href="xml/gcredentials.xml"/>
<xi:include href="xml/gunixcredentialsmessage.xml"/>
<xi:include href="xml/gproxy.xml"/>
<xi:include href="xml/gproxyaddress.xml"/>
<xi:include href="xml/gnetworking.xml"/>
</chapter>
<chapter id="highlevel-socket">
<title>High-level network functionality</title>
<xi:include href="xml/gsocketclient.xml"/>
<xi:include href="xml/gsocketconnection.xml"/>
<xi:include href="xml/gunixconnection.xml"/>
<xi:include href="xml/gtcpconnection.xml"/>
<xi:include href="xml/gtcpwrapperconnection.xml"/>
<xi:include href="xml/gsocketlistener.xml"/>
<xi:include href="xml/gsocketservice.xml"/>
<xi:include href="xml/gthreadedsocketservice.xml"/>
<xi:include href="xml/gnetworkmonitor.xml"/>
</chapter>
<chapter id="tls">
<title>TLS (SSL) support</title>
<xi:include href="xml/gtls.xml"/>
<xi:include href="xml/gtlscertificate.xml"/>
<xi:include href="xml/gtlsconnection.xml"/>
<xi:include href="xml/gtlsclientconnection.xml"/>
<xi:include href="xml/gtlsserverconnection.xml"/>
<xi:include href="xml/gdtlsconnection.xml"/>
<xi:include href="xml/gdtlsclientconnection.xml"/>
<xi:include href="xml/gdtlsserverconnection.xml"/>
<xi:include href="xml/gtlsbackend.xml"/>
<xi:include href="xml/gtlsdatabase.xml"/>
<xi:include href="xml/gtlsfiledatabase.xml"/>
<xi:include href="xml/gtlsinteraction.xml"/>
<xi:include href="xml/gtlspassword.xml"/>
</chapter>
<chapter id="resolver">
<title>DNS resolution</title>
<xi:include href="xml/gresolver.xml"/>
<xi:include href="xml/gproxyresolver.xml"/>
<xi:include href="xml/gsimpleproxyresolver.xml"/>
<xi:include href="xml/gsocketconnectable.xml"/>
<xi:include href="xml/gsocketaddressenumerator.xml"/>
<xi:include href="xml/gproxyaddressenumerator.xml"/>
<xi:include href="xml/gnetworkaddress.xml"/>
<xi:include href="xml/gnetworkservice.xml"/>
<xi:include href="xml/gsrvtarget.xml"/>
</chapter>
<chapter id="gdbus-lowlevel">
<title>Low-level D-Bus Support</title>
<xi:include href="xml/gdbusutils.xml"/>
<xi:include href="xml/gdbusaddress.xml"/>
<xi:include href="xml/gdbusintrospection.xml"/>
<xi:include href="xml/gdbuserror.xml"/>
<xi:include href="xml/gdbusmessage.xml"/>
<xi:include href="xml/gdbusconnection.xml"/>
<xi:include href="xml/gdbusmethodinvocation.xml"/>
<xi:include href="xml/gdbusserver.xml"/>
<xi:include href="xml/gdbusauthobserver.xml"/>
</chapter>
<chapter id="gdbus-convenience">
<title>High-level D-Bus Support</title>
<xi:include href="xml/gdbusnameowning.xml"/>
<xi:include href="xml/gdbusnamewatching.xml"/>
<xi:include href="xml/gdbusinterface.xml"/>
<xi:include href="xml/gdbusinterfaceskeleton.xml"/>
<xi:include href="xml/gdbusproxy.xml"/>
<xi:include href="xml/gdbusobject.xml"/>
<xi:include href="xml/gdbusobjectskeleton.xml"/>
<xi:include href="xml/gdbusobjectproxy.xml"/>
<xi:include href="xml/gdbusobjectmanager.xml"/>
<xi:include href="xml/gdbusobjectmanagerserver.xml"/>
<xi:include href="xml/gdbusobjectmanagerclient.xml"/>
</chapter>
<chapter id="settings">
<title>Settings</title>
<xi:include href="xml/gsettings.xml"/>
<xi:include href="xml/gsettingsbackend.xml"/>
<xi:include href="xml/gsettingsschema.xml"/>
</chapter>
<chapter id="resources">
<title>Resources</title>
<xi:include href="xml/gresource.xml"/>
</chapter>
<chapter id='permissions'>
<title>Permissions</title>
<xi:include href="xml/gpermission.xml"/>
<xi:include href="xml/gsimplepermission.xml"/>
</chapter>
<chapter id='data-models'>
<title>Data Models</title>
<xi:include href="xml/glistmodel.xml"/>
<xi:include href="xml/gliststore.xml"/>
</chapter>
<chapter id="application">
<title>Application support</title>
<xi:include href="xml/gapplication.xml"/>
<xi:include href="xml/gapplicationcommandline.xml"/>
<xi:include href="xml/gactiongroup.xml"/>
<xi:include href="xml/gactionmap.xml"/>
<xi:include href="xml/gsimpleactiongroup.xml"/>
<xi:include href="xml/gaction.xml"/>
<xi:include href="xml/gsimpleaction.xml"/>
<xi:include href="xml/gpropertyaction.xml"/>
<xi:include href="xml/gremoteactiongroup.xml"/>
<xi:include href="xml/gactiongroupexporter.xml"/>
<xi:include href="xml/gdbusactiongroup.xml"/>
<xi:include href="xml/gdebugcontroller.xml"/>
<xi:include href="xml/gdebugcontrollerdbus.xml"/>
<xi:include href="xml/gmemorymonitor.xml"/>
<xi:include href="xml/gmenumodel.xml"/>
<xi:include href="xml/gmenu.xml"/>
<xi:include href="xml/gmenuexporter.xml"/>
<xi:include href="xml/gdbusmenumodel.xml"/>
<xi:include href="xml/gnotification.xml"/>
<xi:include href="xml/gpowerprofilemonitor.xml"/>
</chapter>
<chapter id="extending">
<title>Extending GIO</title>
<xi:include href="xml/gvfs.xml"/>
<xi:include href="xml/giomodule.xml"/>
<xi:include href="xml/extensionpoints.xml"/>
</chapter>
<chapter id="tools">
<title>GIO Tools</title>
<xi:include href="gio-querymodules.xml"/>
<xi:include href="gsettings.xml"/>
<xi:include href="glib-compile-schemas.xml"/>
<xi:include href="glib-compile-resources.xml"/>
<xi:include href="gdbus.xml"/>
<xi:include href="xml/gdbus-codegen.xml"/>
<xi:include href="gresource.xml"/>
<xi:include href="gapplication.xml"/>
<xi:include href="gio.xml"/>
</chapter>
<chapter id="testing">
<title>GIO Testing</title>
<xi:include href="xml/gtestdbus.xml"/>
</chapter>
<xi:include href="gio-docs-platform.xml"/>
</part>
<part id="migrating">
<title>Migrating to GIO</title>
<xi:include href="xml/migrating-posix.xml"/>
</part>
<chapter id="gio-hierarchy">
<title>Object Hierarchy</title>
<xi:include href="xml/tree_index.sgml"/>
</chapter>
<chapter id="api-index-full">
<title id="index-all">Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-18" role="2.18">
<title>Index of new symbols in 2.18</title>
<xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-20" role="2.20">
<title>Index of new symbols in 2.20</title>
<xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-24" role="2.24">
<title>Index of new symbols in 2.24</title>
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-26" role="2.26">
<title>Index of new symbols in 2.26</title>
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-28" role="2.28">
<title>Index of new symbols in 2.28</title>
<xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-30" role="2.30">
<title>Index of new symbols in 2.30</title>
<xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-34" role="2.34">
<title>Index of new symbols in 2.34</title>
<xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-36" role="2.36">
<title>Index of new symbols in 2.36</title>
<xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-38" role="2.38">
<title>Index of new symbols in 2.38</title>
<xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-40" role="2.40">
<title>Index of new symbols in 2.40</title>
<xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-42" role="2.42">
<title>Index of new symbols in 2.42</title>
<xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-44" role="2.44">
<title>Index of new symbols in 2.44</title>
<xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-46" role="2.46">
<title>Index of new symbols in 2.46</title>
<xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-48" role="2.48">
<title>Index of new symbols in 2.48</title>
<xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-50" role="2.50">
<title>Index of new symbols in 2.50</title>
<xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-52" role="2.52">
<title>Index of new symbols in 2.52</title>
<xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-54" role="2.54">
<title>Index of new symbols in 2.54</title>
<xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-56" role="2.56">
<title>Index of new symbols in 2.56</title>
<xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-58" role="2.58">
<title>Index of new symbols in 2.58</title>
<xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-60" role="2.60">
<title>Index of new symbols in 2.60</title>
<xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-62" role="2.62">
<title>Index of new symbols in 2.62</title>
<xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-64" role="2.64">
<title>Index of new symbols in 2.64</title>
<xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-66" role="2.66">
<title>Index of new symbols in 2.66</title>
<xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-68" role="2.68">
<title>Index of new symbols in 2.68</title>
<xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-70" role="2.70">
<title>Index of new symbols in 2.70</title>
<xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-72" role="2.72">
<title>Index of new symbols in 2.72</title>
<xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-74" role="2.74">
<title>Index of new symbols in 2.74</title>
<xi:include href="xml/api-index-2.74.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-76" role="2.76">
<title>Index of new symbols in 2.76</title>
<xi:include href="xml/api-index-2.76.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-78" role="2.78">
<title>Index of new symbols in 2.78</title>
<xi:include href="xml/api-index-2.78.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-80" role="2.80">
<title>Index of new symbols in 2.80</title>
<xi:include href="xml/api-index-2.80.xml"><xi:fallback /></xi:include>
</chapter>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

4812
docs/reference/gio/gio-sections-common.txt
View File

File diff suppressed because it is too large Load Diff

122
docs/reference/gio/gio-sections-win32.txt
View File

@ -1,122 +0,0 @@
<SECTION>
<FILE>gwin32inputstream</FILE>
<TITLE>GWin32InputStream</TITLE>
GWin32InputStream
g_win32_input_stream_new
g_win32_input_stream_set_close_handle
g_win32_input_stream_get_close_handle
g_win32_input_stream_get_handle
<SUBSECTION Standard>
GWin32InputStreamClass
G_WIN32_INPUT_STREAM
G_IS_WIN32_INPUT_STREAM
G_TYPE_WIN32_INPUT_STREAM
G_WIN32_INPUT_STREAM_CLASS
G_IS_WIN32_INPUT_STREAM_CLASS
G_WIN32_INPUT_STREAM_GET_CLASS
<SUBSECTION Private>
g_win32_input_stream_get_type
GWin32InputStreamPrivate
</SECTION>
<SECTION>
<FILE>gwin32outputstream</FILE>
<TITLE>GWin32OutputStream</TITLE>
GWin32OutputStream
g_win32_output_stream_new
g_win32_output_stream_set_close_handle
g_win32_output_stream_get_close_handle
g_win32_output_stream_get_handle
<SUBSECTION Standard>
GWin32OutputStreamClass
G_WIN32_OUTPUT_STREAM
G_IS_WIN32_OUTPUT_STREAM
G_TYPE_WIN32_OUTPUT_STREAM
G_WIN32_OUTPUT_STREAM_CLASS
G_IS_WIN32_OUTPUT_STREAM_CLASS
G_WIN32_OUTPUT_STREAM_GET_CLASS
<SUBSECTION Private>
g_win32_output_stream_get_type
GWin32OutputStreamPrivate
</SECTION>
<SECTION>
<FILE>gwin32registrykey</FILE>
<SUBSECTION>
GWin32RegistrySubkeyIter
g_win32_registry_subkey_iter_copy
g_win32_registry_subkey_iter_free
g_win32_registry_subkey_iter_assign
<SUBSECTION>
GWin32RegistryValueIter
g_win32_registry_value_iter_copy
g_win32_registry_value_iter_free
g_win32_registry_value_iter_assign
<SUBSECTION>
GWin32RegistryKey
g_win32_registry_key_new
g_win32_registry_key_new_w
g_win32_registry_key_get_child
g_win32_registry_key_get_child_w
<SUBSECTION>
g_win32_registry_subkey_iter_init
g_win32_registry_subkey_iter_clear
g_win32_registry_subkey_iter_n_subkeys
g_win32_registry_subkey_iter_next
g_win32_registry_subkey_iter_get_name
g_win32_registry_subkey_iter_get_name_w
<SUBSECTION>
g_win32_registry_value_iter_init
g_win32_registry_value_iter_clear
g_win32_registry_value_iter_n_values
g_win32_registry_value_iter_next
GWin32RegistryValueType
g_win32_registry_value_iter_get_value_type
g_win32_registry_value_iter_get_name
g_win32_registry_value_iter_get_name_w
g_win32_registry_value_iter_get_data
g_win32_registry_value_iter_get_data_w
<SUBSECTION>
g_win32_registry_key_get_value
g_win32_registry_key_get_value_w
g_win32_registry_key_get_path
g_win32_registry_key_get_path_w
GWin32RegistryKeyWatchCallbackFunc
GWin32RegistryKeyWatcherFlags
g_win32_registry_key_watch
g_win32_registry_key_has_changed
g_win32_registry_key_erase_change_indicator
<SUBSECTION Standard>
GWin32RegistryKeyClass
<SUBSECTION Private>
GWin32RegistryKeyPrivate
g_win32_registry_key_get_type
g_win32_registry_subkey_iter_get_type
g_win32_registry_value_iter_get_type
G_TYPE_WIN32_REGISTRY_KEY
G_WIN32_REGISTRY_KEY
G_WIN32_REGISTRY_KEY_CLASS
G_IS_WIN32_REGISTRY_KEY
G_IS_WIN32_REGISTRY_KEY_CLASS
G_WIN32_REGISTRY_KEY_GET_CLASS
G_TYPE_WIN32_REGISTRY_SUBKEY_ITER
G_TYPE_WIN32_REGISTRY_VALUE_ITER
</SECTION>
<SECTION>
<FILE>gregistrysettingsbackend</FILE>
<TITLE>GRegistrySettingsBackend</TITLE>
GRegistrySettingsBackend
g_registry_settings_backend_new
<SUBSECTION Private>
g_registry_settings_backend_get_type
</SECTION>

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

@ -61,6 +61,7 @@ content_files = [
"migrating-gdbus.md",
"migrating-gconf.md",
"migrating-gnome-vfs.md",
"migrating-posix.md",
"io-scheduler.md",
]

213
docs/reference/gio/meson.build
View File

@ -1,214 +1,3 @@
if get_option('gtk_doc')
subdir('gdbus-object-manager-example')
subdir('xml')
ignore_headers = [
'gdbus-2.0',
'inotify',
'kqueue',
'libasyncns',
'tests',
'win32',
'xdgmime',
'gappinfoprivate.h',
'gapplicationimpl.h',
'gasynchelper.h',
'gcontenttypeprivate.h',
'gcontextspecificgroup.h',
'gcredentialsprivate.h',
'gdbus-daemon-generated.h',
'gdbusactiongroup-private.h',
'gdbusauth.h',
'gdbusauthmechanismanon.h',
'gdbusauthmechanismexternal.h',
'gdbusauthmechanism.h',
'gdbusauthmechanismsha1.h',
'gdbusdaemon.h',
'gdbusprivate.h',
'gdelayedsettingsbackend.h',
'gdocumentportal.h',
'gdummyfile.h',
'gdummyproxyresolver.h',
'gdummytlsbackend.h',
'gfileattribute-priv.h',
'gfileinfo-priv.h',
'ghttpproxy.h',
'giomodule-priv.h',
'gioprivate.h',
'giowin32-afunix.h',
'giowin32-priv.h',
'gio_probes.h',
'gio_trace.h',
'gio-tool.h',
'glocaldirectorymonitor.h',
'glocalfileenumerator.h',
'glocalfile.h',
'glocalfileinfo.h',
'glocalfileinputstream.h',
'glocalfileiostream.h',
'glocalfilemonitor.h',
'glocalfileoutputstream.h',
'glocalvfs.h',
'gmemorymonitordbus.h',
'gmemorymonitorportal.h',
'gmountprivate.h',
'gnativevolumemonitor.h',
'gnetworkingprivate.h',
'gnetworkmonitorbase.h',
'gnetworkmonitornetlink.h',
'gnetworkmonitornm.h',
'gnetworkmonitorportal.h',
'gnotificationbackend.h',
'gnotification-private.h',
'gopenuriportal.h',
'gpollfilemonitor.h',
'gportalsupport.h',
'gpowerprofilemonitordbus.h',
'gpowerprofilemonitorportal.h',
'gproxyresolverportal.h',
'gregistrysettingsbackend.h',
'gresourcefile.h',
'gsandbox.h',
'gsettingsbackendinternal.h',
'gsettings-mapping.h',
'gsettingsschema-internal.h',
'gsocketinputstream.h',
'gsocketoutputstream.h',
'gsocks4aproxy.h',
'gsocks4proxy.h',
'gsocks5proxy.h',
'gsubprocesslauncher-private.h',
'gthreadedresolver.h',
'gtrashportal.h',
'gunionvolumemonitor.h',
'gunixmount.h',
'gunixresolver.h',
'gunixvolume.h',
'gunixvolumemonitor.h',
'gwin32networkmonitor.h',
'gwin32api-application-activation-manager.h',
'gwin32api-iterator.h',
'gwin32api-misc.h',
'gwin32api-package.h',
'gwin32api-storage.h',
'gwin32appinfo.h',
'gwin32file-sync-stream.h',
'gwin32mount.h',
'gwin32packageparser.h',
'gwin32resolver.h',
'gwin32volumemonitor.h',
'thumbnail-verify.h',
'xdp-dbus.h',
'gio-visibility.h',
]
sections_files = files('gio-sections-common.txt')
if host_system == 'windows'
ignore_headers += [
'gfiledescriptorbased.h',
'gunixmounts.h',
'gunixfdmessage.h',
'gunixinputstream.h',
'gunixoutputstream.h',
'gdesktopappinfo.h',
'gosxappinfo.h',
]
sections_files += files('gio-sections-win32.txt')
platform_file = files('gio-docs-win32.xml')
else
if glib_have_cocoa
ignore_headers += ['gdesktopappinfo.h']
else
ignore_headers += ['gosxappinfo.h']
endif
ignore_headers += [
'gwin32inputstream.h',
'gwin32outputstream.h',
'gwin32registrykey.h',
]
platform_file = files('gio-docs-unix.xml')
endif
ignore_sources = [
'kqueue',
'tests',
'gdbus-daemon-generated.c',
'xdp-dbus.c',
]
docpath = join_paths(glib_datadir, 'gtk-doc', 'html')
version_conf = configuration_data()
version_conf.set('VERSION', meson.project_version())
configure_file(
input: 'version.xml.in',
output: 'version.xml',
configuration: version_conf
)
concat_files_helper = find_program('concat-files-helper.py')
configure_file(
output : 'gio-sections.txt',
input : sections_files,
command : [concat_files_helper, '@OUTPUT@', '@INPUT@'],
)
fs.copyfile(platform_file, 'gio-docs-platform.xml')
content_files = [
'migrating-posix.xml',
'gio-querymodules.xml',
'glib-compile-schemas.xml',
'glib-compile-resources.xml',
'gapplication.xml',
'gsettings.xml',
'gresource.xml',
'gdbus.xml',
'gdbus-codegen.xml',
]
content_files += [
gdbus_example_objectmanager_xml,
gdbus_example_objectmanager_sources,
gdbus_object_manager_example_doc
]
gnome.gtkdoc('gio',
main_xml : 'gio-docs.xml',
namespace : 'g',
mode : 'none',
dependencies : [libgio_dep, libgobject_dep, libglib_dep],
src_dir : 'gio',
scan_args : [
'--ignore-decorators=' + ignore_decorators.replace('GLIB', 'GIO'),
'--rebuild-types',
'--ignore-headers=' + ' '.join(ignore_headers),
],
mkdb_args : [
'--ignore-files=' + ' '.join(ignore_sources),
],
content_files : content_files,
expand_content_files : [
'migrating-posix.xml',
'gdbus-codegen.xml',
],
html_assets : [
'gvfs-overview.png',
'menu-example.png',
'menu-model.png',
],
fixxref_args: [
'--html-dir=' + docpath,
'--extra-dir=' + join_paths('gio', '..', 'glib', 'html'),
'--extra-dir=' + join_paths('gio', '..', 'gobject', 'html'),
],
install: true,
check: false,
)
endif
if get_option('man')
manpages = ['gapplication', 'gio-querymodules', 'glib-compile-schemas',
'glib-compile-resources', 'gsettings', 'gresource', 'gdbus',
@ -223,7 +12,6 @@ if get_option('man')
endforeach
endif
# gi-docgen version
expand_content_files = [
'dbus-error.md',
'dbus-introspection.md',
@ -237,6 +25,7 @@ expand_content_files = [
'migrating-gconf.md',
'migrating-gdbus.md',
'migrating-gnome-vfs.md',
'migrating-posix.md',
'networking.md',
'overview.md',
'pollable-utils.md',

17
docs/reference/gio/migrating-posix.md Normal file
View File

@ -0,0 +1,17 @@
Title: Migrating from POSIX to GIO
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2007 Matthias Clasen
# Migrating from POSIX to GIO
## Comparison of POSIX and GIO concepts
| POSIX | GIO |
|-----------------------|-----------------------------------------------------|
| `char *path` | [iface@Gio.File] |
| `struct stat *buf` | [class@Gio.FileInfo] |
| `struct statvfs *buf` | [class@Gio.FileInfo] |
| `int fd` | [class@Gio.InputStream] or [class@Gio.OutputStream] |
| `DIR *` | [class@Gio.FileEnumerator] |
| `fstab entry` | [struct@Gio.UnixMountPoint] |
| `mtab entry` | [struct@Gio.UnixMountEntry] |

27
docs/reference/gio/migrating-posix.xml
View File

@ -1,27 +0,0 @@
<part id="migrating">
<title>Migrating to GIO</title>
<chapter>
<title>Migrating from POSIX to GIO</title>
<table id="posix-vs-gio">
<title>Comparison of POSIX and GIO concepts</title>
<tgroup cols="2">
<thead>
<row><entry>POSIX</entry><entry>GIO</entry></row>
</thead>
<tbody>
<row><entry>char *path</entry><entry>GFile *file</entry></row>
<row><entry>struct stat *buf</entry><entry>GFileInfo *info</entry></row>
<row><entry>struct statvfs *buf</entry><entry>GFileInfo *info</entry></row>
<row><entry morerows="1">int fd</entry><entry>GInputStream *in</entry></row>
<row><entry>GOutputStream *out</entry></row>
<row><entry>DIR *</entry><entry>GFileEnumerator *enum</entry></row>
<row><entry>fstab entry</entry><entry>GUnixMountPoint *mount_point</entry></row>
<row><entry>mtab entry</entry><entry>GUnixMountEntry *mount_entry</entry></row>
</tbody>
</tgroup>
</table>
</chapter>
</part>

1
docs/reference/gio/version.xml.in
View File

@ -1 +0,0 @@
@VERSION@

8
docs/reference/gio/xml/gtkdocentities.ent.in
View File

@ -1,8 +0,0 @@
<!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/gio/xml/meson.build
View File

@ -1,14 +0,0 @@
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
)

75
docs/reference/glib/atomic.md Normal file
View File

@ -0,0 +1,75 @@
Title: Atomic Operations
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Dan Winship
# Atomic Operations
The following is a collection of compiler macros to provide atomic
access to integer and pointer-sized values.
The macros that have ‘int’ in the name will operate on pointers to `gint` and
`guint`. The macros with ‘pointer’ in the name will operate on pointers to any
pointer-sized value, including `guintptr`.
There is no support for 64-bit operations on platforms with 32-bit pointers
because it is not generally possible to perform these operations atomically.
The get, set and exchange operations for integers and pointers
nominally operate on `gint` and `gpointer`, respectively. Of the
arithmetic operations, the ‘add’ operation operates on (and returns)
signed integer values (`gint` and `gssize`) and the ‘and’, ‘or’, and
‘xor’ operations operate on (and return) unsigned integer values
(`guint` and `gsize`).
All of the operations act as a full compiler and (where appropriate)
hardware memory barrier. Acquire and release or producer and
consumer barrier semantics are not available through this API.
It is very important that all accesses to a particular integer or
pointer be performed using only this API and that different sizes of
operation are not mixed or used on overlapping memory regions. Never
read or assign directly from or to a value — always use this API.
For simple reference counting purposes you should use `gatomicrefcount`
(see [func@GLib.atomic_ref_count_init]) rather than [func@GLib.atomic_int_inc]
and [func@GLib.atomic_int_dec_and_test].
Uses of [func@GLib.atomic_int_inc] and [func@GLib.atomic_int_dec_and_test]
that fall outside of simple counting patterns are prone to
subtle bugs and occasionally undefined behaviour. It is also worth
noting that since all of these operations require global
synchronisation of the entire machine, they can be quite slow. In
the case of performing multiple atomic operations it can often be
faster to simply acquire a mutex lock around the critical area,
perform the operations normally and then release the lock.
## Atomic Integer Operations
* [func@GLib.atomic_int_get]
* [func@GLib.atomic_int_set]
* [func@GLib.atomic_int_inc]
* [func@GLib.atomic_int_dec_and_test]
* [func@GLib.atomic_int_compare_and_exchange]
* [func@GLib.atomic_int_compare_and_exchange_full]
* [func@GLib.atomic_int_exchange]
* [func@GLib.atomic_int_add]
* [func@GLib.atomic_int_and]
* [func@GLib.atomic_int_or]
* [func@GLib.atomic_int_xor]
## Atomic Pointer Operations
* [func@GLib.atomic_pointer_get]
* [func@GLib.atomic_pointer_set]
* [func@GLib.atomic_pointer_compare_and_exchange]
* [func@GLib.atomic_pointer_compare_and_exchange_full]
* [func@GLib.atomic_pointer_exchange]
* [func@GLib.atomic_pointer_add]
* [func@GLib.atomic_pointer_and]
* [func@GLib.atomic_pointer_or]
* [func@GLib.atomic_pointer_xor]
## Deprecated API
* [func@GLib.atomic_int_exchange_and_add]

20
docs/reference/glib/base64.md Normal file
View File

@ -0,0 +1,20 @@
Title: Base64 Encoding
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2006, 2009 Matthias Clasen
# Base64 Encoding
Base64 is an encoding that allows a sequence of arbitrary bytes to be
encoded as a sequence of printable ASCII characters. For the definition
of Base64, see [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) or
[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
Base64 is most commonly used as a MIME transfer encoding for email.
GLib supports incremental encoding using [func@GLib.base64_encode_step] and
[func@GLib.base64_encode_close]. Incremental decoding can be done with
[func@GLib.base64_decode_step]. To encode or decode data in one go, use
[func@GLib.base64_encode] or [func@GLib.base64_decode]. To avoid memory
allocation when decoding, you can use [func@GLib.base64_decode_inplace].
Support for Base64 encoding was added in GLib 2.12.

174
docs/reference/glib/changes.xml
View File

@ -1,174 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-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>

30
docs/reference/glib/checked-math.md Normal file
View File

@ -0,0 +1,30 @@
Title: Bounds-checking Integer Arithmetic
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2015 Allison Lortie
# Bounds-checking Integer Arithmetic
GLib offers a set of macros for doing additions and multiplications
of unsigned integers, with checks for overflows.
The helpers all have three arguments. A pointer to the destination
is always the first argument and the operands to the operation are
the other two.
Following standard GLib convention, the helpers return true in case
of success (ie: no overflow).
The helpers may be macros, normal functions or inlines. They may be
implemented with inline assembly or compiler intrinsics where
available.
Since: 2.48
The APIs are:
* [func@GLib.uint_checked_add]
* [func@GLib.uint_checked_mul]
* [func@GLib.uint64_checked_add]
* [func@GLib.uint64_checked_mul]
* [func@GLib.size_checked_add]
* [func@GLib.size_checked_mul]

78
docs/reference/glib/datalist-and-dataset.md Normal file
View File

@ -0,0 +1,78 @@
Title: Keyed Data Lists and Datasets
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 1999 Owen Taylor
SPDX-FileCopyrightText: 2000 Red Hat, Inc.
SPDX-FileCopyrightText: 2005 Tim Janik
## Keyed Data Lists
Keyed data lists provide lists of arbitrary data elements which can
be accessed either with a string or with a [type@GLib.Quark] corresponding to
the string.
The [type@GLib.Quark] methods are quicker, since the strings have to be
converted to [type@GLib.Quark]s anyway.
Data lists are used for associating arbitrary data with
[class@GObject.Object]s, using [method@GObject.Object.set_data] and related
functions. The data is stored inside opaque [type@GLib.Data] elements.
To create a datalist, use [func@GLib.datalist_init].
To add data elements to a datalist use [func@GLib.datalist_id_set_data],
[func@GLib.datalist_id_set_data_full], [func@GLib.datalist_set_data],
[func@GLib.datalist_set_data_full] and [func@GLib.datalist_id_replace_data].
To get data elements from a datalist use [func@GLib.datalist_id_get_data],
[func@GLib.datalist_get_data] and [func@GLib.datalist_id_dup_data].
To iterate over all data elements in a datalist use
[func@GLib.datalist_foreach] (not thread-safe).
To remove data elements from a datalist use
[func@GLib.datalist_id_remove_data], [func@GLib.datalist_remove_data] and
[func@GLib.datalist_id_remove_multiple]. To remove elements without destroying
them, use [func@GLib.datalist_id_remove_no_notify] and
[func@GLib.datalist_remove_no_notify].
To remove all data elements from a datalist, use [func@GLib.datalist_clear].
A small number of boolean flags can be stored alongside a datalist, using
[func@GLib.datalist_set_flags], [func@GLib.datalist_unset_flags] and
[func@GLib.datalist_get_flags].
## Datasets
Datasets associate groups of data elements with particular memory
locations. These are useful if you need to associate data with a
structure returned from an external library. Since you cannot modify
the structure, you use its location in memory as the key into a
dataset, where you can associate any number of data elements with it.
There are two forms of most of the dataset functions. The first form
uses strings to identify the data elements associated with a
location. The second form uses [type@GLib.Quark] identifiers, which are
created with a call to [func@GLib.quark_from_string] or
[func@GLib.quark_from_static_string]. The second form is quicker, since it
does not require looking up the string in the hash table of [type@GLib.Quark]
identifiers.
There is no function to create a dataset. It is automatically
created as soon as you add elements to it.
To add data elements to a dataset use [func@GLib.dataset_id_set_data],
[func@GLib.dataset_id_set_data_full], [func@GLib.dataset_set_data] and
[func@GLib.dataset_set_data_full].
To get data elements from a dataset use [func@GLib.dataset_id_get_data] and
[func@GLib.dataset_get_data].
To iterate over all data elements in a dataset use
[func@GLib.dataset_foreach] (not thread-safe).
To remove data elements from a dataset use
[func@GLib.dataset_id_remove_data] and [func@GLib.dataset_remove_data]. To
remove data without destroying it, use [func@GLib.dataset_id_remove_no_notify]
and [func@GLib.dataset_remove_no_notify].
To destroy a dataset, use [func@GLib.dataset_destroy].

110
docs/reference/glib/file-utils.md Normal file
View File

@ -0,0 +1,110 @@
Title: File Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Dan Winship
# File Utilities
Do not use these APIs unless you are porting a POSIX application to Windows.
A more high-level file access API is provided as GIO — see the documentation
for [iface@Gio.File].
## POSIX File Wrappers
There is a group of functions which wrap the common POSIX functions
dealing with filenames:
* [func@GLib.access]
* [func@GLib.chdir]
* [func@GLib.chmod]
* [func@GLib.close]
* [func@GLib.creat]
* [func@GLib.fopen],
* [func@GLib.freopen]
* [func@GLib.fsync]
* [func@GLib.lstat]
* [func@GLib.mkdir]
* [func@GLib.open]
* [func@GLib.remove]
* [func@GLib.rename]
* [func@GLib.rmdir]
* [func@GLib.stat]
* [func@GLib.unlink]
* [func@GLib.utime]
The point of these wrappers is to make it possible to handle file names with any
Unicode characters in them on Windows without having to use `#ifdef`s and the
wide character API in the application code.
On some Unix systems, these APIs may be defined as identical to their POSIX
counterparts. For this reason, you must check for and include the necessary
header files (such as `fcntl.h`) before using functions like [func@GLib.creat].
You must also define the relevant feature test macros.
The pathname argument should be in the GLib file name encoding.
On POSIX this is the actual on-disk encoding which might correspond
to the locale settings of the process (or the `G_FILENAME_ENCODING`
environment variable), or not.
On Windows the GLib file name encoding is UTF-8. Note that the
Microsoft C library does not use UTF-8, but has separate APIs for
current system code page and wide characters (UTF-16). The GLib
wrappers call the wide character API if present (on modern Windows
systems), otherwise convert to/from the system code page.
## POSIX Directory Wrappers
Another group of functions allows to open and read directories
in the GLib file name encoding:
* [ctor@GLib.Dir.open]
* [method@GLib.Dir.read_name]
* [method@GLib.Dir.rewind]
* [method@GLib.Dir.close]
## Error Handling
* [func@GLib.file_error_from_errno]
## Setting/Getting File Contents
* [func@GLib.file_get_contents]
* [func@GLib.file_set_contents]
* [func@GLib.file_set_contents_full]
## File Tests
* [func@GLib.file_test]
* [func@GLib.file_read_link]
## Temporary File Handling
* [func@GLib.mkdtemp]
* [func@GLib.mkdtemp_full]
* [func@GLib.mkstemp]
* [func@GLib.mkstemp_full]
* [func@GLib.file_open_tmp]
* [id@g_dir_make_tmp]
## Building and Manipulating Paths
* [func@GLib.build_path]
* [func@GLib.build_pathv]
* [func@GLib.build_filename]
* [func@GLib.build_filenamev]
* [func@GLib.build_filename_valist]
* [func@GLib.IS_DIR_SEPARATOR]
* [func@GLib.path_is_absolute]
* [func@GLib.path_skip_root]
* [func@GLib.get_current_dir]
* [func@GLib.path_get_basename]
* [func@GLib.path_get_dirname]
* [func@GLib.canonicalize_filename]
## Creating Directories
* [func@GLib.mkdir_with_parents]
## Deprecated API
* [func@GLib.basename]

313
docs/reference/glib/glib-docs.xml
View File

@ -1,313 +0,0 @@
<?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="programming.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/gpathbuf.xml" />
<xi:include href="xml/guri.xml" />
<xi:include href="xml/ghostutils.xml" />
<xi:include href="xml/shell.xml" />
<xi:include href="xml/goptioncontext.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/gkeyfile.xml" />
<xi:include href="xml/gbookmarkfile.xml" />
<xi:include href="xml/testing.xml" />
<xi:include href="xml/gunix.xml" />
<xi:include href="xml/windows.xml" />
<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="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>
<chapter id="api-index-full">
<title>Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-2" role="2.2">
<title>Index of new symbols in 2.2</title>
<xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-4" role="2.4">
<title>Index of new symbols in 2.4</title>
<xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-6" role="2.6">
<title>Index of new symbols in 2.6</title>
<xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-8" role="2.8">
<title>Index of new symbols in 2.8</title>
<xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-10" role="2.10">
<title>Index of new symbols in 2.10</title>
<xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-12" role="2.12">
<title>Index of new symbols in 2.12</title>
<xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-14" role="2.14">
<title>Index of new symbols in 2.14</title>
<xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-16" role="2.16">
<title>Index of new symbols in 2.16</title>
<xi:include href="xml/api-index-2.16.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-18" role="2.18">
<title>Index of new symbols in 2.18</title>
<xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-20" role="2.20">
<title>Index of new symbols in 2.20</title>
<xi:include href="xml/api-index-2.20.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-24" role="2.24">
<title>Index of new symbols in 2.24</title>
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-26" role="2.26">
<title>Index of new symbols in 2.26</title>
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-28" role="2.28">
<title>Index of new symbols in 2.28</title>
<xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-30" role="2.30">
<title>Index of new symbols in 2.30</title>
<xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-34" role="2.34">
<title>Index of new symbols in 2.34</title>
<xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-36" role="2.36">
<title>Index of new symbols in 2.36</title>
<xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-38" role="2.38">
<title>Index of new symbols in 2.38</title>
<xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-40" role="2.40">
<title>Index of new symbols in 2.40</title>
<xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-42" role="2.42">
<title>Index of new symbols in 2.42</title>
<xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-44" role="2.44">
<title>Index of new symbols in 2.44</title>
<xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-46" role="2.46">
<title>Index of new symbols in 2.46</title>
<xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-48" role="2.48">
<title>Index of new symbols in 2.48</title>
<xi:include href="xml/api-index-2.48.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-50" role="2.50">
<title>Index of new symbols in 2.50</title>
<xi:include href="xml/api-index-2.50.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-52" role="2.52">
<title>Index of new symbols in 2.52</title>
<xi:include href="xml/api-index-2.52.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-54" role="2.54">
<title>Index of new symbols in 2.54</title>
<xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-56" role="2.56">
<title>Index of new symbols in 2.56</title>
<xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-58" role="2.58">
<title>Index of new symbols in 2.58</title>
<xi:include href="xml/api-index-2.58.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-60" role="2.60">
<title>Index of new symbols in 2.60</title>
<xi:include href="xml/api-index-2.60.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-62" role="2.62">
<title>Index of new symbols in 2.62</title>
<xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-64" role="2.64">
<title>Index of new symbols in 2.64</title>
<xi:include href="xml/api-index-2.64.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-66" role="2.66">
<title>Index of new symbols in 2.66</title>
<xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-68" role="2.68">
<title>Index of new symbols in 2.68</title>
<xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-70" role="2.70">
<title>Index of new symbols in 2.70</title>
<xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-72" role="2.72">
<title>Index of new symbols in 2.72</title>
<xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-74" role="2.74">
<title>Index of new symbols in 2.74</title>
<xi:include href="xml/api-index-2.74.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-76" role="2.76">
<title>Index of new symbols in 2.76</title>
<xi:include href="xml/api-index-2.76.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-78" role="2.78">
<title>Index of new symbols in 2.78</title>
<xi:include href="xml/api-index-2.78.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-80" role="2.80">
<title>Index of new symbols in 2.80</title>
<xi:include href="xml/api-index-2.80.xml"><xi:fallback /></xi:include>
</chapter>"
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

294
docs/reference/glib/glib-overrides.txt
View File

@ -1,294 +0,0 @@
# 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>

3777
docs/reference/glib/glib-sections.txt.in
View File

File diff suppressed because it is too large Load Diff

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

@ -44,6 +44,8 @@ content_files = [
"compiling.md",
"cross-compiling.md",
"running.md",
"programming.md",
"resources.md",
"gvariant-format-strings.md",
"gvariant-text-format.md",
@ -51,21 +53,43 @@ content_files = [
"character-set.md",
"i18n.md",
"string-utils.md",
"types.md",
"macros.md",
"conversion-macros.md",
"auto-cleanup.md",
"memory.md",
"memory-slices.md",
"error-reporting.md",
"logging.md",
"warnings.md",
"file-utils.md",
"host-utils.md",
"misc-utils.md",
"main-loop.md",
"reference-counting.md",
"testing.md",
"atomic.md",
"checked-math.md",
"threads.md",
"spawn.md",
"unix.md",
"windows.md",
"random.md",
"numerical.md",
"markup.md",
"base64.md",
"goption.md",
"data-structures.md",
"datalist-and-dataset.md",
"shell.md",
"uuid.md",
"unicode.md",
"version.md",
"threads-deprecated.md",
]
content_images = [
"file-name-encodings.png",

30
docs/reference/glib/host-utils.md Normal file
View File

@ -0,0 +1,30 @@
Title: Hostname Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2008 Dan Winship
# Hostname Utilities
Functions for manipulating internet hostnames; in particular, for
converting between Unicode and ASCII-encoded forms of
Internationalized Domain Names (IDNs).
The
[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
standards allow for the use
of Unicode domain names in applications, while providing
backward-compatibility with the old ASCII-only DNS, by defining an
ASCII-Compatible Encoding of any given Unicode name, which can be
used with non-IDN-aware applications and protocols. (For example,
“Παν語.org” maps to “xn--4wa8awb4637h.org”.)
## Hostname Conversions
* [func@GLib.hostname_to_ascii]
* [func@GLib.hostname_to_unicode]
## Hostname Checks
* [func@GLib.hostname_is_non_ascii]
* [func@GLib.hostname_is_ascii_encoded]
* [func@GLib.hostname_is_ip_address]

99
docs/reference/glib/memory.md Normal file
View File

@ -0,0 +1,99 @@
Title: Memory Allocation
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2000, 2019 Red Hat, Inc.
SPDX-FileCopyrightText: 2007 Emmanuele Bassi
SPDX-FileCopyrightText: 2018 Pavlo Solntsev
SPDX-FileCopyrightText: 2020 Endless Mobile, Inc.
# Memory Allocation
These functions provide support for allocating and freeing memory.
If any call to allocate memory using functions [func@GLib.new],
[func@GLib.new0], [func@GLib.renew], [func@GLib.malloc], [func@GLib.malloc0],
[func@GLib.malloc0_n], [func@GLib.realloc] and [func@GLib.realloc_n]
fails, the application is terminated. This also means that there is no
need to check if the call succeeded.
On the other hand, the `g_try_…()` family of functions returns `NULL` on failure
that can be used as a check for unsuccessful memory allocation. The application
is not terminated in this case.
As all GLib functions and data structures use [func@GLib.malloc] internally,
unless otherwise specified, any allocation failure will result in the
application being terminated.
It’s important to match [func@GLib.malloc] (and wrappers such as
[func@GLib.new]) with [func@GLib.free], [func@GLib.slice_alloc] (and wrappers
such as [func@GLib.slice_new]) with [func@GLib.slice_free], plain
[`malloc()`](man:malloc(3)) with [`free()`](man:free(3)), and (if you’re using
C++) `new` with `delete` and `new[]` with `delete[]`. Otherwise bad things can
happen, since these allocators may use different memory pools (and
`new`/`delete` call constructors and destructors).
Since GLib 2.46, [func@GLib.malloc] is hardcoded to always use the system malloc
implementation.
## Struct Allocations
* [func@GLib.new]
* [func@GLib.new0]
* [func@GLib.renew]
* [func@GLib.try_new]
* [func@GLib.try_new0]
* [func@GLib.try_renew]
## Block Allocations
* [func@GLib.malloc]
* [func@GLib.malloc0]
* [func@GLib.realloc]
* [func@GLib.try_malloc]
* [func@GLib.try_malloc0]
* [func@GLib.try_realloc]
* [func@GLib.malloc_n]
* [func@GLib.malloc0_n]
* [func@GLib.realloc_n]
* [func@GLib.try_malloc_n]
* [func@GLib.try_malloc0_n]
* [func@GLib.try_realloc_n]
## Free Functions
* [func@GLib.free]
* [func@GLib.free_sized]
* [func@GLib.clear_pointer]
* [func@GLib.steal_pointer]
In addition, the `g_mem_gc_friendly` exported variable will be true if GLib has
been [run with `G_DEBUG=gc-friendly`](running.html#environment-variables). If
so, memory to be freed will be cleared to zero before being freed.
## Stack Allocations
* [func@GLib.alloca]
* [func@GLib.alloca0]
* [func@GLib.newa]
* [func@GLib.newa0]
## Aligned Allocations
* [func@GLib.aligned_alloc]
* [func@GLib.aligned_alloc0]
* [func@GLib.aligned_free]
* [func@GLib.aligned_free_sized]
## Copies and Moves
* [func@GLib.memmove]
* [func@GLib.memdup2]
## Deprecated API
* [func@GLib.memdup]
* [struct@GLib.MemVTable]
* [func@GLib.mem_set_vtable]
* [func@GLib.mem_is_system_malloc]
* `glib_mem_profiler_table` exported variable
* [func@GLib.mem_profile]

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

@ -1,100 +1,3 @@
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',
'gconstructorprivate.h',
'testutils.h',
'valgrind.h',
'gutilsprivate.h',
'gvalgrind.h',
'dirent.h',
'glib-unixprivate.h',
'glib-visibility.h',
'gmodule-visibility.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
)
configure_file(
input: 'glib-sections.txt.in',
output: 'glib-sections.txt',
command: [gen_visibility_macros, meson.project_version(), 'doc-sections', '@INPUT@', '@OUTPUT@'],
)
gnome.gtkdoc('glib',
main_xml : 'glib-docs.xml',
namespace : 'g',
mode : 'none',
src_dir : [ 'glib', 'gmodule' ],
dependencies : libglib_dep,
scan_args : [
'--ignore-decorators=' + ignore_decorators + '|' + ignore_decorators.replace('GLIB', 'GMODULE'),
'--ignore-headers=' + ' '.join(ignore_headers),
],
content_files : [
'changes.xml',
'programming.xml',
'resources.xml',
'regex-syntax.xml',
'glib-gettextize.xml',
'gtester.xml',
'gtester-report.xml',
],
expand_content_files : [
],
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: false)
endif
if get_option('man')
manpages = ['glib-gettextize', 'gtester', 'gtester-report']
@ -143,27 +46,48 @@ if get_option('gtk_doc')
endif
endif
# gi-docgen version
expand_content_files = [
'atomic.md',
'base64.md',
'building.md',
'character-set.md',
'checked-math.md',
'compiling.md',
'cross-compiling.md',
'datalist-and-dataset.md',
'error-reporting.md',
'file-utils.md',
'gvariant-format-strings.md',
'gvariant-text-format.md',
'i18n.md',
'logging.md',
'main-loop.md',
'memory.md',
'memory-slices.md',
'numerical.md',
'random.md',
'reference-counting.md',
'running.md',
'testing.md',
'threads.md',
'threads-deprecated.md',
'markup.md',
'misc-utils.md',
'goption.md',
'host-utils.md',
'data-structures.md',
'programming.md',
'resources.md',
'shell.md',
'spawn.md',
'string-utils.md',
'types.md',
'unicode.md',
'unix.md',
'uuid.md',
'version.md',
'warnings.md',
'windows.md',
]
glib_toml = configure_file(input: 'glib.toml.in', output: 'glib.toml', configuration: toml_conf)

113
docs/reference/glib/misc-utils.md Normal file
View File

@ -0,0 +1,113 @@
Title: Miscellaneous Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2000 Red Hat, Inc.
# Miscellaneous Utilities
These are portable utility functions.
## Application Name and Environment
* [func@GLib.get_application_name]
* [func@GLib.set_application_name]
* [func@GLib.get_prgname]
* [func@GLib.set_prgname]
* [func@GLib.get_environ]
* [func@GLib.environ_getenv]
* [func@GLib.environ_setenv]
* [func@GLib.environ_unsetenv]
* [func@GLib.getenv]
* [func@GLib.setenv]
* [func@GLib.unsetenv]
* [func@GLib.listenv]
* [func@GLib.get_user_name]
* [func@GLib.get_real_name]
## System Directories
* [func@GLib.get_user_cache_dir]
* [func@GLib.get_user_data_dir]
* [func@GLib.get_user_config_dir]
* [func@GLib.get_user_state_dir]
* [func@GLib.get_user_runtime_dir]
* [func@GLib.get_user_special_dir]
* [func@GLib.get_system_data_dirs]
* [func@GLib.get_system_config_dirs]
* [func@GLib.reload_user_special_dirs_cache]
## OS Info
Information about the current OS can be retrieved by calling
[func@GLib.get_os_info] and passing it one of the following keys (this list may
grow in future):
* `G_OS_INFO_KEY_NAME`
* `G_OS_INFO_KEY_PRETTY_NAME`
* `G_OS_INFO_KEY_VERSION`
* `G_OS_INFO_KEY_VERSION_CODENAME`
* `G_OS_INFO_KEY_VERSION_ID`
* `G_OS_INFO_KEY_ID`
* `G_OS_INFO_KEY_HOME_URL`
* `G_OS_INFO_KEY_DOCUMENTATION_URL`
* `G_OS_INFO_KEY_SUPPORT_URL`
* `G_OS_INFO_KEY_BUG_REPORT_URL`
* `G_OS_INFO_KEY_PRIVACY_POLICY_URL`
## Paths
* [func@GLib.get_host_name]
* [func@GLib.get_home_dir]
* [func@GLib.get_tmp_dir]
* [func@GLib.get_current_dir]
* [func@GLib.canonicalize_filename]
* [func@GLib.path_is_absolute]
* [func@GLib.path_skip_root]
* [func@GLib.path_get_basename]
* [func@GLib.path_get_dirname]
* [func@GLib.build_filename]
* [func@GLib.build_filenamev]
* [func@GLib.build_filename_valist]
* [func@GLib.build_path]
* [func@GLib.build_pathv]
## Size Formatting
* [func@GLib.format_size]
* [func@GLib.format_size_full]
* [func@GLib.format_size_for_display]
## Executables
* [func@GLib.find_program_in_path]
## Bit Manipulation
* [func@GLib.bit_nth_lsf]
* [func@GLib.bit_nth_msf]
* [func@GLib.bit_storage]
## Primes
* [func@GLib.spaced_primes_closest]
## Process Lifetime
* [func@GLib.abort]
## Debug
* [func@GLib.parse_debug_string]
## Sorting
* [func@GLib.qsort_with_data]
## Pointers
* [func@GLib.nullify_pointer]
## Deprecated API
* [type@GLib.VoidFunc]
* [type@GLib.FreeFunc]
* [func@GLib.atexit]

35
docs/reference/glib/numerical.md Normal file
View File

@ -0,0 +1,35 @@
Title: Numerical Definitions
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2001 Havoc Pennington
SPDX-FileCopyrightText: 2010 Red Hat, Inc.
# Numerical Definitions
GLib offers mathematical constants such as [const@GLib.PI] for the value of pi;
many platforms have these in the C library, but some don’t. The GLib
versions always exist.
The [type@GLib.FloatIEEE754] and [type@GLib.DoubleIEEE754] unions are used to
access the sign, mantissa and exponent of IEEE floats and doubles. These unions
are defined as appropriate for a given platform. IEEE floats and doubles are
supported (used for storage) by at least Intel, PPC and Sparc. See
[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
for more information about IEEE number formats.
## Floating Point
* [const@GLib.IEEE754_FLOAT_BIAS]
* [const@GLib.IEEE754_DOUBLE_BIAS]
* [type@GLib.FloatIEEE754]
* [type@GLib.DoubleIEEE754]
## Numerical Constants
* [const@GLib.E]
* [const@GLib.LN2]
* [const@GLib.LN10]
* [const@GLib.PI]
* [const@GLib.PI_2]
* [const@GLib.PI_4]
* [const@GLib.SQRT2]
* [const@GLib.LOG_2_BASE_10]

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

@ -0,0 +1,71 @@
Title: Writing GLib Applications
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2012 Red Hat, Inc.
SPDX-FileCopyrightText: 2023 Endless OS Foundation, LLC
# Writing GLib Applications
## Memory Allocations
Unless otherwise specified, all functions which allocate memory in GLib will
abort the process if heap allocation fails. This is because it is too hard to
recover from allocation failures in any non-trivial program and, in particular,
to test all the allocation failure code paths.
## UTF-8 and String Encoding
All GLib, GObject and GIO functions accept and return strings in
[UTF-8 encoding](https://en.wikipedia.org/wiki/UTF-8) unless otherwise
specified.
Input strings to function calls are *not* checked to see if
they are valid UTF-8: it is the application developer’s responsibility to
validate input strings at the time of input, either at the program or library
boundary, and to only use valid UTF-8 string constants in their application.
If GLib were to UTF-8 validate all string inputs to all functions, there would
be a significant drop in performance.
Similarly, output strings from functions are guaranteed to be in UTF-8,
and this does not need to be validated by the calling function. If a function
returns invalid UTF-8 (and is not documented as doing so), that’s a bug.
See [func@GLib.utf8_validate] and [func@GLib.utf8_make_valid] for validating
UTF-8 input.
## Threads
The general policy of GLib is that all functions are invisibly threadsafe
with the exception of data structure manipulation functions, where, if
you have two threads manipulating the *same* data structure, they must use a
lock to synchronize their operation.
GLib creates a worker thread for its own purposes so GLib applications
will always have at least 2 threads.
In particular, this means that programs must only use
[async-signal-safe functions](man:signal-safety(7)) between
calling [`fork()`](man:fork(2)) and [`exec()`](man:exec(3)), even if
they haven’t explicitly spawned another thread yet.
See the sections on [threads](threads.html) and [struct@GLib.ThreadPool] for
GLib APIs that support multithreaded applications.
## Security and setuid Use
When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
[Secure Programming for Linux and Unix HOWTO](http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html).
When it comes to GLib and its associated libraries, GLib and
GObject are generally fine to use in code that runs with elevated
privileges; they don’t load modules (executable code in shared objects)
or run other programs ‘behind your back’. GIO, however, is not designed to be
used in privileged programs, either ones which are spawned by a privileged
process, or ones which are run with a setuid bit set.
setuid programs should always reset their environment to contain only
known-safe values before calling into non-trivial libraries such as GIO. This
reduces the risk of an attacker-controlled environment variable being used to
get a privileged GIO process to run arbitrary code via loading a GIO module or
similar.

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

@ -1,124 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-programming">
<refmeta>
<refentrytitle>Writing GLib Applications</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLib Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Writing GLib Applications</refname>
<refpurpose>
General considerations when programming with GLib
</refpurpose>
</refnamediv>
<refsect1>
<title>Writing GLib Applications</title>
<refsect2>
<title>Memory Allocations</title>
<para>
Unless otherwise specified, all functions which allocate memory in GLib will
abort the process if heap allocation fails. This is because it is too hard to
recover from allocation failures in any non-trivial program and, in particular,
to test all the allocation failure code paths.
</para>
</refsect2>
<refsect2>
<title>UTF-8 and String Encoding</title>
<para>
All GLib, GObject and GIO functions accept and return strings in
<ulink url="https://en.wikipedia.org/wiki/UTF-8">UTF-8 encoding</ulink>
unless otherwise specified.
</para>
<para>
Input strings to function calls are <emphasis>not</emphasis> checked to see if
they are valid UTF-8: it is the application developer’s responsibility to
validate input strings at the time of input, either at the program or library
boundary, and to only use valid UTF-8 string constants in their application.
If GLib were to UTF-8 validate all string inputs to all functions, there would
be a significant drop in performance.
</para>
<para>Similarly, output strings from functions are guaranteed to be in UTF-8,
and this does not need to be validated by the calling function. If a function
returns invalid UTF-8 (and is not documented as doing so), that’s a bug.
</para>
<para>
See <link linkend='g-utf8-validate'><function>g_utf8_validate()</function></link>
and <link linkend='g-utf8-make-valid'><function>g_utf8_make_valid()</function></link>
for validating UTF-8 input.
</para>
</refsect2>
<refsect2>
<title>Threads</title>
<para>
The general policy of GLib is that all functions are invisibly threadsafe
with the exception of data structure manipulation functions, where, if
you have two threads manipulating the <emphasis>same</emphasis> data
structure, they must use a lock to synchronize their operation.
</para>
<para>
GLib creates a worker thread for its own purposes so GLib applications
will always have at least 2 threads.
</para>
<para>
In particular, this means that programs must only use
<ulink url="man:signal-safety(7)">async-signal-safe functions</ulink> between
calling <function>fork()</function> and <function>exec()</function>, even if
they haven’t explicitly spawned another thread yet.
</para>
<para>
See the sections on <link linkend="glib-Threads">threads</link> and
<link linkend="glib-Thread-Pools">thread pools</link> for GLib APIs that
support multithreaded applications.
</para>
</refsect2>
<refsect2>
<title>Security and setuid use</title>
<para>
When writing code that runs with elevated privileges, it is important
to follow some basic rules of secure programming. David Wheeler has an
excellent book on this topic,
<ulink url="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html">Secure Programming for Linux and Unix HOWTO</ulink>.
</para>
<para>
When it comes to GLib and its associated libraries, GLib and
GObject are generally fine to use in code that runs with elevated
privileges; they don't load modules (executable code in shared objects)
or run other programs ‘behind your back’. GIO, however, is not designed to be
used in privileged programs, either ones which are spawned by a privileged
process, or ones which are run with a setuid bit set.
</para>
<para>
setuid programs should always reset their environment to contain only
known-safe values before calling into non-trivial libraries such as GIO. This
reduces the risk of an attacker-controlled environment variable being used to
get a privileged GIO process to run arbitrary code via loading a GIO module or
similar.
</para>
</refsect2>
</refsect1>
</refentry>

61
docs/reference/glib/random.md Normal file
View File

@ -0,0 +1,61 @@
Title: Random Numbers
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2000, 2002 Sebastian Wilhelmi
SPDX-FileCopyrightText: 2013 Colin Walters
# Random Numbers
The following functions allow you to use a portable, fast and good
pseudo-random number generator (PRNG).
Do not use this API for cryptographic purposes such as key
generation, nonces, salts or one-time pads.
This PRNG is suitable for non-cryptographic use such as in games
(shuffling a card deck, generating levels), generating data for
a test suite, etc. If you need random data for cryptographic
purposes, it is recommended to use platform-specific APIs such
as `/dev/random` on UNIX, or
[`CryptGenRandom()`](https://learn.microsoft.com/en-us/windows/win32/api/wincrypt/nf-wincrypt-cryptgenrandom)
on Windows.
[type@GLib.Rand] uses the Mersenne Twister PRNG, which was originally
developed by Makoto Matsumoto and Takuji Nishimura. Further
information can be found at
[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
If you just need a random number, you simply call the `g_random_*()`
functions, which will create a globally used [type@GLib.Rand] and use the
according `g_rand_*()` functions internally:
* [func@GLib.random_int]
* [func@GLib.random_int_range]
* [func@GLib.random_double]
* [func@GLib.random_double_range]
* [func@GLib.random_set_seed]
Whenever you need a stream of reproducible random numbers, you better create a
[type@GLib.Rand] yourself and use the `g_rand_*()` functions directly, which
will also be slightly faster. Initializing a [type@GLib.Rand] with a
certain seed will produce exactly the same series of random
numbers on all platforms. This can thus be used as a seed for
e.g. games.
The `g_rand*_range()` functions will return high quality equally
distributed random numbers, whereas for example the
`(g_random_int () % max)` approach often
doesn’t yield equally distributed numbers.
GLib changed the seeding algorithm for the pseudo-random number
generator Mersenne Twister, as used by [type@GLib.Rand]. This was necessary,
because some seeds would yield very bad pseudo-random streams.
Also the pseudo-random integers generated by `g_rand*_int_range()`
will have a slightly better equal distribution with the new
version of GLib.
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 `G_RANDOM_VERSION` 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.

2485
docs/reference/glib/regex-syntax.xml
View File

File diff suppressed because it is too large Load Diff

43
docs/reference/glib/resources.md Normal file
View File

@ -0,0 +1,43 @@
Title: Support and Bug Reports
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2002 Matthias Clasen
SPDX-FileCopyrightText: 2018 Collabora, Ltd.
SPDX-FileCopyrightText: 2019 Emmanuele Bassi
# Support and Bug Reports
## Filing a Bug Report or Feature Request
If you encounter a bug, misfeature, or missing feature in GLib, please
file a bug report on the issue tracker at
[https://gitlab.gnome.org/GNOME/glib/issues/new](https://gitlab.gnome.org/GNOME/glib/issues/new).
We’d also appreciate reports of incomplete or misleading information in
the GLib documentation; file those with the ‘Documentation’ label.
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.
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.
## Code Contributions
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.
If you want to discuss your branch before or after developing it, open a
topic on [Discourse](https://discourse.gnome.org/tags/glib).
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.
## Discussions and User Questions
The [GLib issue tracker](https://gitlab.gnome.org/GNOME/glib/issues)
is meant for discussions with actionable topics. If you want to ask a question
about using GLib, or discuss new features, you should use
[the `glib` tag on Discourse](https://discourse.gnome.org/tags/glib).

77
docs/reference/glib/resources.xml
View File

@ -1,77 +0,0 @@
<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="glib-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>

15
docs/reference/glib/shell.md Normal file
View File

@ -0,0 +1,15 @@
Title: Shell Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2014 Matthias Clasen
# Shell Utilities
GLib provides the functions [func@GLib.shell_quote] and
[func@GLib.shell_unquote] to handle shell-like quoting in strings. The function
[func@GLib.shell_parse_argv] parses a string similar to the way a POSIX shell
(`/bin/sh`) would.
Note that string handling in shells has many obscure and historical
corner-cases which these functions do not necessarily reproduce. They
are good enough in practice, though.

76
docs/reference/glib/spawn.md Normal file
View File

@ -0,0 +1,76 @@
Title: Spawning Processes
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2014 Red Hat, Inc.
SPDX-FileCopyrightText: 2017 Philip Withnall
# Spawning Processes
GLib supports spawning of processes with an API that is more
convenient than the bare UNIX [`fork()`](man:fork(2)) and
[`exec()`](man:exec(3)).
The `g_spawn_…()` family of functions has synchronous ([func@GLib.spawn_sync])
and asynchronous variants ([func@GLib.spawn_async],
[func@GLib.spawn_async_with_pipes]), as well as convenience variants that take a
complete shell-like command line ([func@GLib.spawn_command_line_sync],
[func@GLib.spawn_command_line_async]).
See [class@Gio.Subprocess] in GIO for a higher-level API that provides
stream interfaces for communication with child processes.
An example of using [func@GLib.spawn_async_with_pipes]:
```c
const gchar * const argv[] = { "my-favourite-program", "--args", NULL };
gint child_stdout, child_stderr;
GPid child_pid;
g_autoptr(GError) error = NULL;
// Spawn child process.
g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL,
NULL, &child_pid, NULL, &child_stdout,
&child_stderr, &error);
if (error != NULL)
{
g_error ("Spawning child failed: %s", error->message);
return;
}
// Add a child watch function which will be called when the child process
// exits.
g_child_watch_add (child_pid, child_watch_cb, NULL);
// You could watch for output on @child_stdout and @child_stderr using
// #GUnixInputStream or #GIOChannel here.
static void
child_watch_cb (GPid pid,
gint status,
gpointer user_data)
{
g_message ("Child %" G_PID_FORMAT " exited %s", pid,
g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally");
// Free any resources associated with the child here, such as I/O channels
// on its stdout and stderr FDs. If you have no code to put in the
// child_watch_cb() callback, you can remove it and the g_child_watch_add()
// call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag,
// otherwise the child process will stay around as a zombie until this
// process exits.
g_spawn_close_pid (pid);
}
```
## Spawn Functions
* [func@GLib.spawn_async_with_fds]
* [func@GLib.spawn_async_with_pipes]
* [func@GLib.spawn_async_with_pipes_and_fds]
* [func@GLib.spawn_async]
* [func@GLib.spawn_sync]
* [func@GLib.spawn_check_wait_status]
* [func@GLib.spawn_check_exit_status]
* [func@GLib.spawn_command_line_async]
* [func@GLib.spawn_command_line_sync]
* [func@GLib.spawn_close_pid]

187
docs/reference/glib/string-utils.md Normal file
View File

@ -0,0 +1,187 @@
Title: String Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 1999 Owen Taylor
SPDX-FileCopyrightText: 2000 Red Hat, Inc.
SPDX-FileCopyrightText: 2002, 2003, 2014 Matthias Clasen
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
# String Utilities
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
Note that the functions [func@GLib.printf], [func@GLib.fprintf],
[func@GLib.sprintf], [func@GLib.vprintf], [func@GLib.vfprintf],
[func@GLib.vsprintf] and [func@GLib.vasprintf] are declared in the header
`gprintf.h` which is not included in `glib.h`
(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
explicitly include `<glib/gprintf.h>` in order to use the GLib
`printf()` functions.
## String precision pitfalls # {#string-precision}
While you may use the `printf()` functions to format UTF-8 strings,
notice that the precision of a `%Ns` parameter is interpreted
as the number of bytes, not characters to print. On top of that,
the GNU libc implementation of the `printf()` functions has the
‘feature’ that it checks that the string given for the `%Ns`
parameter consists of a whole number of characters in the current
encoding. So, unless you are sure you are always going to be in an
UTF-8 locale or your know your text is restricted to ASCII, avoid
using `%Ns`. If your intention is to format strings for a
certain number of columns, then `%Ns` is not a correct solution
anyway, since it fails to take wide characters (see [func@GLib.unichar_iswide])
into account.
Note also that there are various `printf()` parameters which are platform
dependent. GLib provides platform independent macros for these parameters
which should be used instead. A common example is [const@GLib.GUINT64_FORMAT],
which should be used instead of `%llu` or similar parameters for formatting
64-bit integers. These macros are all named `G_*_FORMAT`; see
[Basic Types](types.html).
## General String Manipulation
* [func@GLib.strdup]
* [func@GLib.strndup]
* [func@GLib.strdupv]
* [func@GLib.strnfill]
* [func@GLib.stpcpy]
* [func@GLib.strstr_len]
* [func@GLib.strrstr]
* [func@GLib.strrstr_len]
* [func@GLib.str_has_prefix]
* [func@GLib.str_has_suffix]
* [func@GLib.strcmp0]
* [func@GLib.str_to_ascii]
* [func@GLib.str_tokenize_and_fold]
* [func@GLib.str_match_string]
For users of GLib in C, the `g_set_str()` inline function also exists to set a
string and handle copying the new value and freeing the old one.
## String Copying
* [func@GLib.strlcpy]
* [func@GLib.strlcat]
## Printing
* [func@GLib.strdup_printf]
* [func@GLib.strdup_vprintf]
* [func@GLib.printf]
* [func@GLib.vprintf]
* [func@GLib.fprintf]
* [func@GLib.vfprintf]
* [func@GLib.sprintf]
* [func@GLib.vsprintf]
* [func@GLib.snprintf]
* [func@GLib.vsnprintf]
* [func@GLib.vasprintf]
* [func@GLib.printf_string_upper_bound]
## ASCII
* [func@GLib.str_is_ascii]
* [func@GLib.ascii_isalnum]
* [func@GLib.ascii_isalpha]
* [func@GLib.ascii_iscntrl]
* [func@GLib.ascii_isdigit]
* [func@GLib.ascii_isgraph]
* [func@GLib.ascii_islower]
* [func@GLib.ascii_isprint]
* [func@GLib.ascii_ispunct]
* [func@GLib.ascii_isspace]
* [func@GLib.ascii_isupper]
* [func@GLib.ascii_isxdigit]
## ASCII Parsing
* [func@GLib.ascii_digit_value]
* [func@GLib.ascii_xdigit_value]
## ASCII Comparisons
* [func@GLib.ascii_strcasecmp]
* [func@GLib.ascii_strncasecmp]
## ASCII Case Manipulation
* [func@GLib.ascii_strup]
* [func@GLib.ascii_strdown]
* [func@GLib.ascii_tolower]
* [func@GLib.ascii_toupper
## ASCII String Manipulation
* [func@GLib.strreverse]
## ASCII Number Manipulation
* [func@GLib.ascii_strtoll]
* [func@GLib.ascii_strtoull]
* [const@GLib.ASCII_DTOSTR_BUF_SIZE]
* [func@GLib.ascii_strtod]
* [func@GLib.ascii_dtostr]
* [func@GLib.ascii_formatd]
* [func@GLib.strtod]
## ASCII Number Parsing
* [type@GLib.NumberParserError]
* [func@GLib.ascii_string_to_signed]
* [func@GLib.ascii_string_to_unsigned]
## Whitespace Removal
* [func@GLib.strchug]
* [func@GLib.strchomp]
* [func@GLib.strstrip]
## Find and Replace
* [func@GLib.strdelimit]
* [const@GLib.STR_DELIMITERS]
* [func@GLib.strescape]
* [func@GLib.strcompress]
* [func@GLib.strcanon]
## Splitting and Joining
* [func@GLib.strsplit]
* [func@GLib.strsplit_set]
* [func@GLib.strconcat]
* [func@GLib.strjoin]
* [func@GLib.strjoinv]
## String Arrays
* [type@GLib.Strv]
* [func@GLib.strfreev]
* [func@GLib.strv_length]
* [func@GLib.strv_contains]
* [func@GLib.strv_equal]
## String Array Builder
* [type@GLib.StrvBuilder]
* [ctor@GLib.StrvBuilder.new]
* [method@GLib.StrvBuilder.ref]
* [method@GLib.StrvBuilder.unref]
* [method@GLib.StrvBuilder.add]
* [method@GLib.StrvBuilder.addv]
* [method@GLib.StrvBuilder.add_many]
* [method@GLib.StrvBuilder.take]
* [method@GLib.StrvBuilder.end]
## POSIX Errors
* [func@GLib.strerror]
* [func@GLib.strsignal]
## Deprecated API
* [func@GLib.strup]
* [func@GLib.strdown]
* [func@GLib.strcasecmp]
* [func@GLib.strncasecmp]

37
docs/reference/glib/threads-deprecated.md Normal file
View File

@ -0,0 +1,37 @@
Title: Deprecated Thread API
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2011 Allison Lortie
# Deprecated Thread API
These APIs are deprecated. You should not use them in new code.
This section remains only to assist with understanding code that was
written to use these APIs at some point in the past.
Deprecated thread creation/configuration functions:
* [type@GLib.ThreadPriority]
* [type@GLib.ThreadFunctions]
* [func@GLib.Thread.init]
* [func@GLib.Thread.get_initialized]
* [method@GLib.Thread.set_priority]
* [func@GLib.Thread.foreach]
* [func@GLib.Thread.create]
* [func@GLib.Thread.create_full]
Deprecated static variants of locking primitives:
* [type@GLib.StaticMutex]
* [type@GLib.StaticRecMutex]
* [type@GLib.StaticRWLock]
* [type@GLib.StaticPrivate]
Deprecated dynamic allocation of locking primitives:
* [func@GLib.Private.new]
* [func@GLib.Mutex.new]
* [method@GLib.Mutex.free]
* [func@GLib.Cond.new]
* [method@GLib.Cond.free]
* [method@GLib.Cond.timed_wait]

882
docs/reference/glib/types.md Normal file
View File

@ -0,0 +1,882 @@
Title: Basic Types
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 1999 Owen Taylor
SPDX-FileCopyrightText: 2000 Red Hat, Inc.
SPDX-FileCopyrightText: 2000 Sebastian Wilhelmi
SPDX-FileCopyrightText: 2008 Matthias Clasen
SPDX-FileCopyrightText: 2008, 2010 Behdad Esfahbod
SPDX-FileCopyrightText: 2009 Christian Persch
SPDX-FileCopyrightText: 2014, 2022 Collabora, Ltd.
SPDX-FileCopyrightText: 2017, 2018 Endless Mobile, Inc.
SPDX-FileCopyrightText: 2018 Christoph Reiter
SPDX-FileCopyrightText: 2019 Alistair Thomas
# Basic Types
GLib defines a number of commonly used types, which can be divided
into several groups:
- New types which are not part of standard C (but are defined in
various C standard library header files) — [`gboolean`](#gboolean),
[`gssize`](#gssize).
- Integer types which are guaranteed to be the same size across
all platforms — [`gint8`](#gint8), [`guint8`](#guint8), [`gint16`](#gint16),
[`guint16`](#guint16), [`gint32`](#gint32), [`guint32`](#guint32),
[`gint64`](#gint64), [`guint64`](#guint64).
- Types which are easier to use than their standard C counterparts —
[`gpointer`](#gpointer), [`gconstpointer`](#gconstpointer),
[`guchar`](#guchar), [`guint`](#guint), [`gushort`](#gushort),
[`gulong`](#gulong).
- Types which correspond exactly to standard C types, but are
included for completeness — [`gchar`](#gchar), [`gint`](#gint),
[`gshort`](#gshort), [`glong`](#glong), [`gfloat`](#gfloat),
[`gdouble`](#gdouble).
- Types which correspond exactly to standard C99 types, but are available
to use even if your compiler does not support C99 — [`gsize`](#gsize),
[`goffset`](#goffset), [`gintptr`](#gintptr), [`guintptr`](#guintptr).
GLib also defines macros for the limits of some of the standard
integer and floating point types, as well as macros for suitable
[`printf()`](man:printf(3)) formats for these types.
Note that depending on the platform and build configuration, the format
macros might not be compatible with the system provided
[`printf()`](man:printf(3)) function, because GLib might use a different
`printf()` implementation internally. The format macros will always work with
GLib API (like [func@GLib.print]), and with any C99 compatible `printf()`
implementation.
## Basic Types
### `gboolean`
A standard boolean type. Variables of this type should only contain the value
`TRUE` or `FALSE`.
Never directly compare the contents of a `gboolean` variable with the values
`TRUE` or `FALSE`. Use `if (condition)` to check a `gboolean` is ‘true’, instead
of `if (condition == TRUE)`. Likewise use `if (!condition)` to check a
`gboolean` is ‘false’.
There is no validation when assigning to a `gboolean` variable and so it could
contain any value represented by a `gint`. This is why the use of `if
(condition)` is recommended. All non-zero values in C evaluate to ‘true’.
### `gpointer`
An untyped pointer, exactly equivalent to `void *`.
The standard C `void *` type should usually be preferred in
new code, but `gpointer` can be used in contexts where a type name
must be a single word, such as in the [method@GObject.Type.name] of
[const@GObject.TYPE_POINTER] or when generating a family of function names for
multiple types using macros.
### `gconstpointer`
An untyped pointer to constant data, exactly equivalent to `const void *`.
The data pointed to should not be changed.
This is typically used in function prototypes to indicate
that the data pointed to will not be altered by the function.
The standard C `const void *` type should usually be preferred in
new code, but `gconstpointer` can be used in contexts where a type name
must be a single word.
### `gchar`
Equivalent to the standard C `char` type.
This type only exists for symmetry with `guchar`.
The standard C `char` type should be preferred in new code.
### `guchar`
Equivalent to the standard C `unsigned char` type.
The standard C `unsigned char` type should usually be preferred in
new code, but `guchar` can be used in contexts where a type name
must be a single word, such as in the [method@GObject.Type.name] of
[const@GObject.TYPE_UCHAR] or when generating a family of function names for
multiple types using macros.
## Naturally Sized Integers
### `gint`
Equivalent to the standard C `int` type.
Values of this type can range from `INT_MIN` to `INT_MAX`,
or equivalently from `G_MININT` to `G_MAXINT`.
This type only exists for symmetry with [`guint`](#guint).
The standard C `int` type should be preferred in new code.
`G_MININT`
: The minimum value which can be held in a `gint`.
This is the same as standard C `INT_MIN`, which is available since C99
and should be preferred in new code.
`G_MAXINT`
: The maximum value which can be held in a `gint`.
This is the same as standard C `INT_MAX`, which is available since C99
and should be preferred in new code.
### `guint`
Equivalent to the standard C `unsigned int` type.
Values of this type can range from `0` to `UINT_MAX`,
or equivalently `0` to `G_MAXUINT`.
The standard C `unsigned int` type should usually be preferred in
new code, but `guint` can be used in contexts where a type name
must be a single word, such as in the [method@GObject.Type.name] of
[const@GObject.TYPE_UINT] or when generating a family of function names for
multiple types using macros.
`G_MAXUINT`
: The maximum value which can be held in a `guint`.
This is the same as standard C `UINT_MAX`, which is available since C99
and should be preferred in new code.
### `gshort`
Equivalent to the standard C `short` type.
Values of this type can range from `SHRT_MIN` to `SHRT_MAX`,
or equivalently `G_MINSHORT` to `G_MAXSHORT`.
This type only exists for symmetry with `gushort`.
The standard C `short` type should be preferred in new code.
`G_MINSHORT`
: The minimum value which can be held in a `gshort`.
This is the same as standard C `SHRT_MIN`, which is available since C99
and should be preferred in new code.
`G_MAXSHORT`
: The maximum value which can be held in a `gshort`.
This is the same as standard C `SHRT_MAX`, which is available since C99
and should be preferred in new code.
### `gushort`
Equivalent to the standard C `unsigned short` type.
Values of this type can range from `0` to `USHRT_MAX`,
or equivalently from `0` to `G_MAXUSHORT`.
The standard C `unsigned short` type should usually be preferred in
new code, but `gushort` can be used in contexts where a type name
must be a single word, such as when generating a family of function
names for multiple types using macros.
`G_MAXUSHORT`
: The maximum value which can be held in a `gushort`.
This is the same as standard C `USHRT_MAX`, which is available since C99
and should be preferred in new code.
### `glong`
Equivalent to the standard C `long` type.
Values of this type can range from `LONG_MIN` to `LONG_MAX`,
or equivalently `G_MINLONG` to `G_MAXLONG`.
This type only exists for symmetry with `gulong`.
The standard C `long` type should be preferred in new code.
`G_MINLONG`
: The minimum value which can be held in a `glong`.
This is the same as standard C `LONG_MIN`, which is available since C99
and should be preferred in new code.
`G_MAXLONG`
: The maximum value which can be held in a `glong`.
This is the same as standard C `ULONG_MAX`, which is available since C99
and should be preferred in new code.
### `gulong`
Equivalent to the standard C `unsigned long` type.
Values of this type can range from `0` to `G_MAXULONG`.
The standard C `unsigned long` type should usually be preferred in
new code, but `gulong` can be used in contexts where a type name
must be a single word, such as in the [method@GObject.Type.name] of
[const@GObject.TYPE_ULONG] or when generating a family of function names for
multiple types using macros.
`G_MAXULONG`
: The maximum value which can be held in a `gulong`.
This is the same as standard C `ULONG_MAX`, which is available since C99
and should be preferred in new code.
## Fixed Width Integers
### `gint8`
A signed integer guaranteed to be 8 bits on all platforms,
similar to the standard C `int8_t`.
The `int8_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `gint8`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `G_MININT8` (= -128) to
`G_MAXINT8` (= 127).
`G_MININT8`
: The minimum value which can be held in a `gint8`.
Since: 2.4
`G_MAXINT8`
: The maximum value which can be held in a `gint8`.
This is the same as standard C `INT8_MAX`, which should be
preferred in new code.
Since: 2.4
### `guint8`
An unsigned integer guaranteed to be 8 bits on all platforms,
similar to the standard C `uint8_t`.
The `uint8_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `guint8`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `0` to `G_MAXUINT8` (= 255).
`G_MAXUINT8`
: The maximum value which can be held in a `guint8`.
This is the same as standard C `UINT8_MAX`, which should be
preferred in new code.
Since: 2.4
### `gint16`
A signed integer guaranteed to be 16 bits on all platforms,
similar to the standard C `int16_t`.
The `int16_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `gint16`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `G_MININT16` (= -32,768) to
`G_MAXINT16` (= 32,767).
To print or scan values of this type, use
`G_GINT16_MODIFIER` and/or `G_GINT16_FORMAT`.
`G_MININT16`
: The minimum value which can be held in a `gint16`.
Since: 2.4
`G_MAXINT16`
: The maximum value which can be held in a `gint16`.
This is the same as standard C `INT16_MAX`, which should be
preferred in new code.
Since: 2.4
`G_GINT16_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `gint16` or `guint16`. It
is a string literal, but doesn’t include the percent-sign, such
that you can add precision and length modifiers between percent-sign
and conversion specifier and append a conversion specifier.
The following example prints `0x7b`;
```c
gint16 value = 123;
g_print ("%#" G_GINT16_MODIFIER "x", value);
```
This is not necessarily the correct modifier for printing and scanning
`int16_t` values, even though the in-memory representation is the same.
Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
Since: 2.4
`G_GINT16_FORMAT`
: This is the platform dependent conversion specifier for scanning and
printing values of type `gint16`. It is a string literal, but doesn’t
include the percent-sign, such that you can add precision and length
modifiers between percent-sign and conversion specifier.
```c
gint16 in;
gint32 out;
sscanf ("42", "%" G_GINT16_FORMAT, &in)
out = in * 1000;
g_print ("%" G_GINT32_FORMAT, out);
```
This is not necessarily the correct format for printing and scanning
`int16_t` values, even though the in-memory representation is the same.
Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
### `guint16`
An unsigned integer guaranteed to be 16 bits on all platforms,
similar to the standard C `uint16_t`.
The `uint16_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `guint16`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `0` to `G_MAXUINT16` (= 65,535).
To print or scan values of this type, use
`G_GINT16_MODIFIER` and/or `G_GUINT16_FORMAT`.
`G_MAXUINT16`
: The maximum value which can be held in a `guint16`.
This is the same as standard C `UINT16_MAX`, which should be
preferred in new code.
Since: 2.4
`G_GUINT16_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `guint16`. See also `G_GINT16_FORMAT`
This is not necessarily the correct modifier for printing and scanning
`uint16_t` values, even though the in-memory representation is the same.
Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`.
### `gint32`
A signed integer guaranteed to be 32 bits on all platforms.
The `int32_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `gint16`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `G_MININT32` (= -2,147,483,648)
to `G_MAXINT32` (= 2,147,483,647).
To print or scan values of this type, use
`G_GINT32_MODIFIER` and/or `G_GINT32_FORMAT`.
Note that on platforms with more than one 32-bit standard integer type,
`gint32` and `int32_t` are not necessarily implemented by the same
32-bit integer type.
For example, on an ILP32 platform where `int` and `long` are both 32-bit,
it might be the case that one of these types is `int` and the other
is `long`.
See [`gsize`](#gsize) for more details of what this implies.
`G_MININT32`
: The minimum value which can be held in a `gint32`.
Since: 2.4
`G_MAXINT32`
: The maximum value which can be held in a `gint32`.
This is the same as standard C `INT32_MAX`, which should be
preferred in new code.
Since: 2.4
`G_GINT32_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `gint32` or `guint32`. It
is a string literal. See also `G_GINT16_MODIFIER`.
This is not necessarily the correct modifier for printing and scanning
`int32_t` values, even though the in-memory representation is the same.
Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
Since: 2.4
`G_GINT32_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `gint32`. See also `G_GINT16_FORMAT`.
This is not necessarily the correct modifier for printing and scanning
`int32_t` values, even though the in-memory representation is the same.
Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
### `guint32`
An unsigned integer guaranteed to be 32 bits on all platforms,
similar to the standard C `uint32_t`.
The `uint32_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `guint32`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `0` to `G_MAXUINT32` (= 4,294,967,295).
To print or scan values of this type, use
`G_GINT32_MODIFIER` and/or `G_GUINT32_FORMAT`.
Note that on platforms with more than one 32-bit standard integer type,
`guint32` and `uint32_t` are not necessarily implemented by the same
32-bit integer type.
See [`gsize`](#gsize) for more details of what this implies.
`G_MAXUINT32`
: The maximum value which can be held in a `guint32`.
This is the same as standard C `UINT32_MAX`, which should be
preferred in new code.
Since: 2.4
`G_GUINT32_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `guint32`. See also `G_GINT16_FORMAT`.
This is not necessarily the correct modifier for printing and scanning
`uint32_t` values, even though the in-memory representation is the same.
Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`.
### `gint64`
A signed integer guaranteed to be 64 bits on all platforms,
similar to the standard C `int64_t`.
The `int64_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `gint64`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `G_MININT64`
(= -9,223,372,036,854,775,808) to `G_MAXINT64`
(= 9,223,372,036,854,775,807).
To print or scan values of this type, use
`G_GINT64_MODIFIER` and/or `G_GINT64_FORMAT`.
Note that on platforms with more than one 64-bit standard integer type,
`gint64` and `int64_t` are not necessarily implemented by the same
64-bit integer type.
For example, on a platform where both `long` and `long long` are 64-bit,
it might be the case that one of those types is used for `gint64`
and the other is used for `int64_t`.
See [`gsize`](#gsize) for more details of what this implies.
`G_MININT64`
: The minimum value which can be held in a `gint64`.
`G_MAXINT64`
: The maximum value which can be held in a `gint64`.
`G_GINT64_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `gint64` or `guint64`.
It is a string literal.
Some platforms do not support printing 64-bit integers, even
though the types are supported. On such platforms `G_GINT64_MODIFIER`
is not defined.
This is not necessarily the correct modifier for printing and scanning
`int64_t` values, even though the in-memory representation is the same.
Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
Since: 2.4
`G_GINT64_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `gint64`. See also `G_GINT16_FORMAT`.
Some platforms do not support scanning and printing 64-bit integers,
even though the types are supported. On such platforms `G_GINT64_FORMAT`
is not defined. Note that [`scanf()`](man:scanf(3)) may not support 64-bit
integers, even if `G_GINT64_FORMAT` is defined. Due to its weak error
handling, `scanf()` is not recommended for parsing anyway; consider using
[func@GLib.ascii_strtoull] instead.
This is not necessarily the correct format for printing and scanning
`int64_t` values, even though the in-memory representation is the same.
Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
`G_GINT64_CONSTANT(val)`
: This macro is used to insert 64-bit integer literals
into the source code.
It is similar to the standard C `INT64_C` macro,
which should be preferred in new code.
### `guint64`
An unsigned integer guaranteed to be 64-bits on all platforms,
similar to the standard C `uint64_t` type.
The `uint64_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires use of `guint64`
(see [`gsize`](#gsize) for more details).
Values of this type can range from `0` to `G_MAXUINT64`
(= 18,446,744,073,709,551,615).
To print or scan values of this type, use
`G_GINT64_MODIFIER` and/or `G_GUINT64_FORMAT`.
Note that on platforms with more than one 64-bit standard integer type,
`guint64` and `uint64_t` are not necessarily implemented by the same
64-bit integer type.
See [`gsize`](#gsize) for more details of what this implies.
`G_MAXUINT64`
: The maximum value which can be held in a `guint64`.
This is the same as standard C `UINT64_MAX`, which should be
preferred in new code.
`G_GUINT64_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `guint64`. See also `G_GINT16_FORMAT`.
Some platforms do not support scanning and printing 64-bit integers,
even though the types are supported. On such platforms `G_GUINT64_FORMAT`
is not defined. Note that [`scanf()`](man:scanf(3)) may not support 64-bit
integers, even if `G_GINT64_FORMAT` is defined. Due to its weak error
handling, `scanf()` is not recommended for parsing anyway; consider using
[func@GLib.ascii_strtoull] instead.
This is not necessarily the correct modifier for printing and scanning
`uint64_t` values, even though the in-memory representation is the same.
Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`.
`G_GUINT64_CONSTANT(val)`
: This macro is used to insert 64-bit unsigned integer
literals into the source code.
It is similar to the standard C `UINT64_C` macro,
which should be preferred in new code.
Since: 2.10
## Floating Point
### `gfloat`
Equivalent to the standard C `float` type.
Values of this type can range from `-FLT_MAX` to `FLT_MAX`,
or equivalently from `-G_MAXFLOAT` to `G_MAXFLOAT`.
`G_MINFLOAT`
: The minimum positive value which can be held in a `gfloat`.
If you are interested in the smallest value which can be held
in a `gfloat`, use `-G_MAXFLOAT`.
This is the same as standard C `FLT_MIN`, which is available since C99
and should be preferred in new code.
`G_MAXFLOAT`
: The maximum value which can be held in a `gfloat`.
This is the same as standard C `FLT_MAX`, which is available since C99
and should be preferred in new code.
### `gdouble`
Equivalent to the standard C `double` type.
Values of this type can range from `-DBL_MAX` to `DBL_MAX`,
or equivalently from `-G_MAXDOUBLE` to `G_MAXDOUBLE`.
`G_MINDOUBLE`
: The minimum positive value which can be held in a `gdouble`.
If you are interested in the smallest value which can be held
in a `gdouble`, use `-G_MAXDOUBLE`.
This is the same as standard C `DBL_MIN`, which is available since C99
and should be preferred in new code.
`G_MAXDOUBLE`
: The maximum value which can be held in a `gdouble`.
This is the same as standard C `DBL_MAX`, which is available since C99
and should be preferred in new code.
## Architecture Sized Integers
### `gsize`
An unsigned integer type of the result of the `sizeof` operator,
corresponding to the `size_t` type defined in C99.
The standard `size_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires `gsize`
(see below for more details).
`gsize` is usually 32 bit wide on a 32-bit platform and 64 bit wide
on a 64-bit platform. Values of this type can range from `0` to
`G_MAXSIZE`.
This type is wide enough to hold the size of the largest possible
memory allocation, but is not guaranteed to be wide enough to hold
the numeric value of a pointer: on platforms that use tagged pointers,
such as [CHERI](https://cheri-cpu.org/), pointers can be numerically
larger than the size of the address space.
If the numeric value of a pointer needs to be stored in an integer
without information loss, use the standard C types `intptr_t` or
`uintptr_t`, or the similar GLib types [`gintptr`](#gintptr) or
[`guintptr`](#guintptr).
To print or scan values of this type, use
`G_GSIZE_MODIFIER` and/or `G_GSIZE_FORMAT`.
Note that on platforms where more than one standard integer type is
the same size, `size_t` and `gsize` are always the same size but are
not necessarily implemented by the same standard integer type.
For example, on an ILP32 platform where `int`, `long` and pointers
are all 32-bit, `size_t` might be `unsigned long` while `gsize`
might be `unsigned int`.
This can result in compiler warnings or unexpected C++ name-mangling
if the two types are used inconsistently.
As a result, changing a type from `gsize` to `size_t` in existing APIs
might be an incompatible API or ABI change, especially if C++
is involved. The safe option is to leave existing APIs using the same type
that they have historically used, and only use the standard C types in
new APIs.
Similar considerations apply to all the fixed-size types
([`gint8`](#gint8), [`guint8`](#guint8), [`gint16`](#gint16),
[`guint16`](#guint16), [`gint32`](#gint32), [`guint32`](#guint32),
[`gint64`](#gint64), [`guint64`](#guint64) and [`goffset`](#goffset)), as well
as [`gintptr`](#gintptr) and [`guintptr`](#guintptr).
Types that are 32 bits or larger are particularly likely to be
affected by this.
`G_MAXSIZE`
: The maximum value which can be held in a `gsize`.
This is the same as standard C `SIZE_MAX` (available since C99),
which should be preferred in new code.
Since: 2.4
`G_GSIZE_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `gsize`. It
is a string literal.
Note that this is not necessarily the correct modifier to scan or
print a `size_t`, even though the in-memory representation is the
same. The Standard C `"z"` modifier should be used for `size_t`,
assuming a C99-compliant `printf` implementation is available.
Since: 2.6
`G_GSIZE_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `gsize`. See also `G_GINT16_FORMAT`.
Note that this is not necessarily the correct format to scan or
print a `size_t`, even though the in-memory representation is the
same. The standard C `"zu"` format should be used for `size_t`,
assuming a C99-compliant `printf` implementation is available.
Since: 2.6
### `gssize`
A signed variant of [`gsize`](#gsize), corresponding to the
`ssize_t` defined in POSIX or the similar `SSIZE_T` in Windows.
In new platform-specific code, consider using `ssize_t` or `SSIZE_T`
directly.
Values of this type can range from `G_MINSSIZE` to `G_MAXSSIZE`.
Note that on platforms where `ssize_t` is implemented, `ssize_t` and
`gssize` might be implemented by different standard integer types
of the same size. Similarly, on Windows, `SSIZE_T` and `gssize`
might be implemented by different standard integer types of the same
size. See [`gsize`](#gsize) for more details.
This type is also not guaranteed to be the same as standard C
`ptrdiff_t`, although they are the same on many platforms.
To print or scan values of this type, use
`G_GSSIZE_MODIFIER` and/or `G_GSSIZE_FORMAT`.
`G_MINSSIZE`
: The minimum value which can be held in a `gssize`.
Since: 2.14
`G_MAXSSIZE`
: The maximum value which can be held in a `gssize`.
Since: 2.14
`G_GSSIZE_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `gssize`. See also `G_GINT16_FORMAT`.
Note that this is not necessarily the correct format to scan or print
a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory
representation is the same.
On POSIX platforms, the `"zd"` format should be used for `ssize_t`.
Since: 2.6
`G_GSSIZE_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `gssize`. It
is a string literal.
Note that this is not necessarily the correct modifier to scan or print
a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory
representation is the same.
On POSIX platforms, the `"z"` modifier should be used for `ssize_t`.
Since: 2.6
### `goffset`
A signed integer type that is used for file offsets,
corresponding to the POSIX type `off_t` as if compiling with
`_FILE_OFFSET_BITS` set to 64. `goffset` is always 64 bits wide, even on
32-bit architectures, and even if `off_t` is only 32 bits.
Values of this type can range from `G_MINOFFSET` to
`G_MAXOFFSET`.
To print or scan values of this type, use
`G_GOFFSET_MODIFIER` and/or `G_GOFFSET_FORMAT`.
On platforms with more than one 64-bit standard integer type,
even if `off_t` is also 64 bits in size, `goffset` and `off_t` are not
necessarily implemented by the same 64-bit integer type.
See [`gsize`](#gsize) for more details of what this implies.
Since: 2.14
`G_MINOFFSET`
: The minimum value which can be held in a `goffset`.
`G_MAXOFFSET`
: The maximum value which can be held in a `goffset`.
`G_GOFFSET_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `goffset`. It is a string
literal. See also `G_GINT64_MODIFIER`.
This modifier should only be used with `goffset` values, and not
with `off_t`, which is not necessarily the same type or even the same size.
Since: 2.20
`G_GOFFSET_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `goffset`. See also `G_GINT64_FORMAT`.
This format should only be used with `goffset` values, and not
with `off_t`, which is not necessarily the same type or even the same size.
Since: 2.20
`G_GOFFSET_CONSTANT(val)`
: This macro is used to insert `goffset` 64-bit integer literals
into the source code.
See also `G_GINT64_CONSTANT()`.
Since: 2.20
### `gintptr`
Corresponds to the C99 type `intptr_t`,
a signed integer type that can hold any pointer.
The standard `intptr_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires `gintptr`.
Note that `intptr_t` and `gintptr` might be implemented by different
standard integer types of the same size. See [`gsize`](#gsize) for more details.
`gintptr` is not guaranteed to be the same type or the same size as
[`gssize`](#gssize), even though they are the same on many CPU architectures.
To print or scan values of this type, use
`G_GINTPTR_MODIFIER` and/or `G_GINTPTR_FORMAT`.
Since: 2.18
`G_GINTPTR_MODIFIER`
: The platform dependent length modifier for conversion specifiers
for scanning and printing values of type `gintptr` or `guintptr`.
It is a string literal.
Note that this is not necessarily the correct modifier to scan or
print an `intptr_t`, even though the in-memory representation is the
same.
Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
`intptr_t`.
Since: 2.22
`G_GINTPTR_FORMAT`
: This is the platform dependent conversion specifier for scanning
and printing values of type `gintptr`.
Note that this is not necessarily the correct format to scan or
print an `intptr_t`, even though the in-memory representation is the
same.
Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
`intptr_t`.
Since: 2.22
### `guintptr`
Corresponds to the C99 type `uintptr_t`,
an unsigned integer type that can hold any pointer.
The standard `uintptr_t` type should be preferred in new code, unless
consistency with pre-existing APIs requires `guintptr`.
Note that `uintptr_t` and `guintptr` might be implemented by different
standard integer types of the same size. See [`gsize`](#gsize) for more details.
`guintptr` is not guaranteed to be the same type or the same size as
[`gsize`](#gsize), even though they are the same on many CPU architectures.
To print or scan values of this type, use
`G_GINTPTR_MODIFIER` and/or `G_GUINTPTR_FORMAT`.
Since: 2.18
`G_GUINTPTR_FORMAT`
: This is the platform dependent conversion specifier
for scanning and printing values of type `guintptr`.
Note that this is not necessarily the correct format to scan or
print a `uintptr_t`, even though the in-memory representation is the
same.
Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for
`uintptr_t`.
Since: 2.22

48
docs/reference/glib/unix.md Normal file
View File

@ -0,0 +1,48 @@
Title: Unix-specific Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2011 Colin Walters
# Unix-specific Utilities
Most of GLib is intended to be portable; in contrast, this set of
functions is designed for programs which explicitly target Unix,
or are using it to build higher level abstractions which would be
conditionally compiled if the platform matches `G_OS_UNIX`.
To use these functions, you must explicitly include the
`glib-unix.h` header.
## File Descriptors
* [func@GLib.unix_open_pipe]
* [func@GLib.unix_set_fd_nonblocking]
## Pipes
The [struct@GLib.UnixPipe] structure can be used to conveniently open and
manipulate a Unix pipe.
<!-- FIXME: https://gitlab.gnome.org/GNOME/gi-docgen/-/issues/173 -->
The methods for it are all static inline for efficiency. They are:
* `g_unix_pipe_open()`
* `g_unix_pipe_get()`
* `g_unix_pipe_steal()`
* `g_unix_pipe_close()`
* `g_unix_pipe_clear()`
## Signals
* [func@GLib.unix_signal_add]
* [func@GLib.unix_signal_add_full]
* [func@GLib.unix_signal_source_new]
## Polling
* [func@GLib.unix_fd_add]
* [func@GLib.unix_fd_add_full]
* [func@GLib.unix_fd_source_new]
## User Database
* [func@GLib.unix_get_passwd_entry]

25
docs/reference/glib/uuid.md Normal file
View File

@ -0,0 +1,25 @@
Title: GUuid
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2017 Bastien Nocera
SPDX-FileCopyrightText: 2017 Marc-André Lureau
# GUuid
A UUID, or Universally unique identifier, is intended to uniquely
identify information in a distributed environment. For the
definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html).
The creation of UUIDs does not require a centralized authority.
UUIDs are of relatively small size (128 bits, or 16 bytes). The
common string representation (ex:
`1d6c0810-2bd6-45f3-9890-0268422a6f14`) needs 37 bytes.
[func@GLib.uuid_string_is_valid] can be used to check whether a string is a
valid UUID.
The UUID specification defines 5 versions, and calling
[func@GLib.uuid_string_random] will generate a unique (or rather random)
UUID of the most common version, version 4.
UUID support was added to GLib in version 2.52.

46
docs/reference/glib/version.md Normal file
View File

@ -0,0 +1,46 @@
Title: Version Information
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2004 Matthias Clasen
SPDX-FileCopyrightText: 2012 Emmanuele Bassi
# Version Information
GLib provides version information, primarily useful in configure
checks for builds that have a configure script. Applications will
not typically use the features described here.
## Run-time Version Numbers
The variables `glib_major_version`, `glib_minor_version`, `glib_micro_version`,
`glib_binary_age` and `glib_interface_age` are all available to check.
They can be compared using the function [func@GLib.check_version].
## Compile-time Version Numbers
* [const@GLib.MAJOR_VERSION]
* [const@GLib.MINOR_VERSION]
* [const@GLib.MICRO_VERSION]
* [func@GLib.CHECK_VERSION]
## Version Numbers
The GLib headers annotate deprecated APIs in a way that produces
compiler warnings if these deprecated APIs are used. The warnings
can be turned off by defining the macro `GLIB_DISABLE_DEPRECATION_WARNINGS`
before including the `glib.h` header.
GLib also provides support for building applications against
defined subsets of deprecated or new GLib APIs. Define the macro
`GLIB_VERSION_MIN_REQUIRED` to specify up to what version of GLib
you want to receive warnings about deprecated APIs. Define the
macro `GLIB_VERSION_MAX_ALLOWED` to specify the newest version of
GLib whose API you want to use.
The macros `GLIB_VERSION_2_2`, `GLIB_VERSION_2_4`, …, `GLIB_VERSION_2_80`, etc.
are defined automatically in each release, and can be used to set the value
of macros like `GLIB_VERSION_MIN_REQUIRED`.
The macros `GLIB_VERSION_CUR_STABLE` and `GLIB_VERSION_PREV_STABLE` are also
automatically defined to point to the right version definitions.

1
docs/reference/glib/version.xml.in
View File

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

73
docs/reference/glib/warnings.md Normal file
View File

@ -0,0 +1,73 @@
Title: Warnings and Assertions
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2018 Endless Mobile, Inc.
SPDX-FileCopyrightText: 2023 Daniel Carpenter
# Warnings and Assertions
GLib defines several warning functions and assertions which can be used to
warn of programmer errors when calling functions, and print error messages
from command line programs.
## Pre-condition Assertions
The [func@GLib.return_if_fail], [func@GLib.return_val_if_fail],
[func@GLib.return_if_reached] and [func@GLib.return_val_if_reached] macros are
intended as pre-condition assertions, to be used at the top of a public function
to check that the function’s arguments are acceptable. Any failure of such a
pre-condition assertion is considered a programming error on the part of the
caller of the public API, and the program is considered to be in an undefined
state afterwards. They are similar to the libc [`assert()`](man:assert(3))
function, but provide more context on failures.
For example:
```c
gboolean
g_dtls_connection_shutdown (GDtlsConnection *conn,
gboolean shutdown_read,
gboolean shutdown_write,
GCancellable *cancellable,
GError **error)
{
// local variable declarations
g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
// function body
return return_val;
}
```
[func@GLib.warn_if_fail] and [func@GLib.warn_if_reached] behave similarly, but
they will not abort the program on failure. The program should be considered to
be in an undefined state if they fail, however.
## Messages
[func@GLib.print] and [func@GLib.printerr] are intended to be used for
output from command line applications, since they output to standard output
and standard error by default — whereas functions like [func@GLib.message] and
[func@GLib.log] may be redirected to special purpose message windows, files, or
the system journal.
The default print handlers may be overridden with [func@GLib.set_print_handler]
and [func@GLib.set_printerr_handler].
### Encoding
If the console encoding is not UTF-8 (as specified by
[func@GLib.get_console_charset]) then these functions convert the message first.
Any Unicode characters not defined by that charset are replaced by `'?'`. On
Linux, [`setlocale()`](man:setlocale(3)) must be called early in `main()` to
load the encoding. This behaviour can be changed by providing custom handlers to
[func@GLib.set_print_handler], [func@GLib.set_printerr_handler] and
[func@GLib.log_set_handler].
## Debugging Utilities
* [func@GLib.on_error_query]
* [func@GLib.on_error_stack_trace]
* [func@GLib.BREAKPOINT]

26
docs/reference/glib/windows.md Normal file
View File

@ -0,0 +1,26 @@
Title: Windows-specific Utilities
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2005 Ross Burton
# Windows-specific Utilities
These functions provide some level of Unix emulation on the
Windows platform. If your application really needs the POSIX
APIs, we suggest you try the [Cygwin project](https://cygwin.com/).
* [type@GLib.Win32OSType]
* [func@GLib.win32_check_windows_version]
* [func@GLib.win32_get_command_line]
* [func@GLib.win32_error_message]
* [func@GLib.win32_getlocale]
* [func@GLib.win32_get_package_installation_directory]
* [func@GLib.win32_get_package_installation_directory_of_module]
* [func@GLib.win32_get_package_installation_subdirectory]
* [func@GLib.win32_get_windows_version]
* [func@GLib.win32_locale_filename_from_utf8]
* [func@GLib.WIN32_HAVE_WIDECHAR_API]
* [func@GLib.WIN32_IS_NT_BASED]
## Deprecated API
* [func@GLib.WIN32_DLLMAIN_FOR_DLL_NAME]

8
docs/reference/glib/xml/gtkdocentities.ent.in
View File

@ -1,8 +0,0 @@
<!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
View File

@ -1,14 +0,0 @@
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
)

187
docs/reference/gobject/gobject-docs.xml
View File

@ -1,187 +0,0 @@
<?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>GObject Reference Manual</title>
<releaseinfo>
for GObject &version;
The latest version of this documentation can be found on-line at
<ulink role="online-location" url="https://developer.gnome.org/gobject/unstable/">https://developer.gnome.org/gobject/unstable/</ulink>.
</releaseinfo>
</bookinfo>
<reference label="II">
<title>API Reference</title>
<xi:include href="xml/gtype.xml" />
<xi:include href="xml/gtypeplugin.xml" />
<xi:include href="xml/gtypemodule.xml" />
<xi:include href="xml/objects.xml" />
<xi:include href="xml/enumerations_flags.xml" />
<xi:include href="xml/gboxed.xml" />
<xi:include href="xml/generic_values.xml" />
<xi:include href="xml/param_value_types.xml" />
<xi:include href="xml/gparamspec.xml" />
<xi:include href="xml/value_collection.xml" />
<xi:include href="xml/signals.xml" />
<xi:include href="xml/gsignalgroup.xml" />
<xi:include href="xml/gclosure.xml" />
<xi:include href="xml/value_arrays.xml" />
<xi:include href="xml/gbinding.xml" />
<xi:include href="xml/gbindinggroup.xml" />
</reference>
<reference label="III">
<title>Tools Reference</title>
<xi:include href="glib-mkenums.xml" />
<xi:include href="glib-genmarshal.xml" />
<xi:include href="gobject-query.xml" />
</reference>
<xi:include href="tut_tools.xml" />
<chapter id="api-index-full">
<title>Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-deprecated" role="deprecated">
<title>Index of deprecated symbols</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-2" role="2.2">
<title>Index of new symbols in 2.2</title>
<xi:include href="xml/api-index-2.2.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-4" role="2.4">
<title>Index of new symbols in 2.4</title>
<xi:include href="xml/api-index-2.4.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-6" role="2.6">
<title>Index of new symbols in 2.6</title>
<xi:include href="xml/api-index-2.6.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-8" role="2.8">
<title>Index of new symbols in 2.8</title>
<xi:include href="xml/api-index-2.8.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-10" role="2.10">
<title>Index of new symbols in 2.10</title>
<xi:include href="xml/api-index-2.10.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-12" role="2.12">
<title>Index of new symbols in 2.12</title>
<xi:include href="xml/api-index-2.12.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-14" role="2.14">
<title>Index of new symbols in 2.14</title>
<xi:include href="xml/api-index-2.14.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-18" role="2.18">
<title>Index of new symbols in 2.18</title>
<xi:include href="xml/api-index-2.18.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-22" role="2.22">
<title>Index of new symbols in 2.22</title>
<xi:include href="xml/api-index-2.22.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-24" role="2.24">
<title>Index of new symbols in 2.24</title>
<xi:include href="xml/api-index-2.24.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-26" role="2.26">
<title>Index of new symbols in 2.26</title>
<xi:include href="xml/api-index-2.26.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-28" role="2.28">
<title>Index of new symbols in 2.28</title>
<xi:include href="xml/api-index-2.28.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-30" role="2.30">
<title>Index of new symbols in 2.30</title>
<xi:include href="xml/api-index-2.30.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-32" role="2.32">
<title>Index of new symbols in 2.32</title>
<xi:include href="xml/api-index-2.32.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-34" role="2.34">
<title>Index of new symbols in 2.34</title>
<xi:include href="xml/api-index-2.34.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-36" role="2.36">
<title>Index of new symbols in 2.36</title>
<xi:include href="xml/api-index-2.36.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-38" role="2.38">
<title>Index of new symbols in 2.38</title>
<xi:include href="xml/api-index-2.38.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-40" role="2.40">
<title>Index of new symbols in 2.40</title>
<xi:include href="xml/api-index-2.40.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-42" role="2.42">
<title>Index of new symbols in 2.42</title>
<xi:include href="xml/api-index-2.42.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-44" role="2.44">
<title>Index of new symbols in 2.44</title>
<xi:include href="xml/api-index-2.44.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-46" role="2.46">
<title>Index of new symbols in 2.46</title>
<xi:include href="xml/api-index-2.46.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-54" role="2.54">
<title>Index of new symbols in 2.54</title>
<xi:include href="xml/api-index-2.54.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-56" role="2.56">
<title>Index of new symbols in 2.56</title>
<xi:include href="xml/api-index-2.56.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-62" role="2.62">
<title>Index of new symbols in 2.62</title>
<xi:include href="xml/api-index-2.62.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-66" role="2.66">
<title>Index of new symbols in 2.66</title>
<xi:include href="xml/api-index-2.66.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-68" role="2.68">
<title>Index of new symbols in 2.68</title>
<xi:include href="xml/api-index-2.68.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-70" role="2.70">
<title>Index of new symbols in 2.70</title>
<xi:include href="xml/api-index-2.70.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-72" role="2.72">
<title>Index of new symbols in 2.72</title>
<xi:include href="xml/api-index-2.72.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-74" role="2.74">
<title>Index of new symbols in 2.74</title>
<xi:include href="xml/api-index-2.74.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-76" role="2.76">
<title>Index of new symbols in 2.76</title>
<xi:include href="xml/api-index-2.76.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-78" role="2.78">
<title>Index of new symbols in 2.78</title>
<xi:include href="xml/api-index-2.78.xml"><xi:fallback /></xi:include>
</chapter>
<chapter id="api-index-2-80" role="2.80">
<title>Index of new symbols in 2.80</title>
<xi:include href="xml/api-index-2.80.xml"><xi:fallback /></xi:include>
</chapter>"
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>

0
docs/reference/gobject/gobject-overrides.txt
View File

1063
docs/reference/gobject/gobject-sections.txt
View File

File diff suppressed because it is too large Load Diff

55
docs/reference/gobject/meson.build
View File

@ -1,57 +1,3 @@
if get_option('gtk_doc')
subdir('xml')
ignore_headers = [
'tests',
'gatomicarray.h',
'gobject_probes.h',
'gobject_trace.h',
'gtype-private.h',
'glib-enumtypes.h',
'gobject-visibility.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
)
gtkdocincl = include_directories('.')
gnome.gtkdoc('gobject',
main_xml : 'gobject-docs.xml',
namespace : 'g',
mode : 'none',
dependencies : [libgobject_dep, libglib_dep],
include_directories : [gtkdocincl],
src_dir : 'gobject',
scan_args : [
'--ignore-decorators=' + '|'.join(ignore_decorators.replace('GLIB', 'GOBJECT')),
'--rebuild-types',
'--ignore-headers=' + ' '.join(ignore_headers),
],
content_files : [
'glib-mkenums.xml',
'glib-genmarshal.xml',
'gobject-query.xml',
'tut_tools.xml'
],
html_assets : [
'images/glue.png'
],
fixxref_args: [
'--html-dir=' + docpath,
'--extra-dir=' + join_paths('gobject', '..', 'glib', 'html'),
],
install: true,
check: false,
)
endif
if get_option('man')
manpages = ['glib-mkenums', 'glib-genmarshal', 'gobject-query']
foreach page : manpages
@ -64,7 +10,6 @@ if get_option('man')
endforeach
endif
# gi-docgen version
expand_content_files = [
'boxed.md',
'concepts.md',

125
docs/reference/gobject/tut_tools.xml
View File

@ -1,125 +0,0 @@
<?xml version='1.0' encoding="UTF-8"?>
<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<part label="V">
<title>Related Tools</title>
<partintro>
<para>
Several useful developer tools have been build around GObject
technology. The next sections briefly introduce them and link to
the respective project pages.
</para>
<para>
For example, writing GObjects is often seen as a tedious task. It
requires a lot of typing and just doing a copy/paste requires a
great deal of care. A lot of projects and scripts have been
written to generate GObject skeleton form boilerplate code, or
even translating higher-level language into plain C.
</para>
</partintro>
<chapter id="tools-vala">
<title>Vala</title>
<para>
From the <ulink url="https://wiki.gnome.org/Projects/Vala">Vala
homepage</ulink> itself: <quote>Vala is a new programming language
that aims to bring modern programming language features to GNOME
developers without imposing any additional runtime requirements
and without using a different ABI compared to applications and
libraries written in C.</quote>
</para>
<para>
The syntax of Vala is similar to C#. The available compiler
translates Vala into GObject C code. It can also compile
non-GObject C, using plain C API.
</para>
</chapter>
<chapter id="tools-gob">
<title>GObject builder</title>
<para>
In order to help a GObject class developer, one obvious idea is
to use some sort of templates for the skeletons and then run
them through a special tool to generate the real C files. <ulink
url="http://www.5z.com/jirka/gob.html">GOB</ulink> (or GOB2) is
such a tool. It is a preprocessor which can be used to build
GObjects with inline C code so that there is no need to edit the
generated C code. The syntax is inspired by Java and Yacc or
Lex. The implementation is intentionally kept simple: the inline C
code provided by the user is not parsed.
</para>
</chapter>
<chapter id="tools-ginspector">
<title>Graphical inspection of GObjects</title>
<para>
Yet another tool that you may find helpful when working with
GObjects is <ulink
url="http://sourceforge.net/projects/g-inspector">G-Inspector</ulink>. It
is able to display GLib/GTK objects and their properties.
</para>
</chapter>
<chapter id="tools-refdb">
<title>Debugging reference count problems</title>
<para>
The reference counting scheme used by GObject does solve quite
a few memory management problems but also introduces new sources of bugs.
In large applications, finding the exact spot where the reference count
of an Object is not properly handled can be very difficult.
</para>
<para>
A useful tool in debugging reference counting problems is to
set breakpoints in gdb on g_object_ref() and g_object_unref().
Once you know the address of the object you are interested in,
you can make the breakpoints conditional:
<programlisting>
break g_object_ref if _object == 0xcafebabe
break g_object_unref if _object == 0xcafebabe
</programlisting>
</para>
</chapter>
<chapter id="tools-gtkdoc">
<title>Writing API docs</title>
<para>The API documentation for most of the GLib, GObject, GTK and GNOME
libraries is built with a combination of complex tools. Typically, the part of
the documentation which describes the behavior of each function is extracted
from the specially-formatted source code comments by a tool named gtk-doc which
generates DocBook XML and merges this DocBook XML with a set of template XML
DocBook files. These XML DocBook files are finally processed with xsltproc
(a small program part of the libxslt library) to generate the final HTML
output. Other tools can be used to generate PDF output from the source XML.
The following code excerpt shows what these comments look like.
<informalexample><programlisting>
/**
* gtk_widget_freeze_child_notify:
* @widget: a #GtkWidget
*
* Stops emission of "child-notify" signals on @widget. The signals are
* queued until gtk_widget_thaw_child_notify() is called on @widget.
*
* This is the analogue of g_object_freeze_notify() for child properties.
**/
void
gtk_widget_freeze_child_notify (GtkWidget *widget)
{
...
</programlisting></informalexample>
</para>
<para>
Thorough
<ulink url="https://developer.gnome.org/gtk-doc-manual/stable/">documentation</ulink>
on how to set up and use gtk-doc in your project is provided on the
<ulink url="https://developer.gnome.org/">GNOME developer website</ulink>.
</para>
</chapter>
</part>

1
docs/reference/gobject/version.xml.in
View File

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

8
docs/reference/gobject/xml/gtkdocentities.ent.in
View File

@ -1,8 +0,0 @@
<!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/gobject/xml/meson.build
View File

@ -1,14 +0,0 @@
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
)

56
docs/reference/meson.build
View File

@ -1,59 +1,3 @@
# The list of minor versions in the 2.x.x series which have had
# GLIB_AVAILABLE_IN_* macros. This should include the current unreleased stable
# version.
first_version = 26
last_version = minor_version.is_odd() ? minor_version + 1 : minor_version
ignore_decorators = [
'GLIB_VAR',
'G_GNUC_INTERNAL',
'G_GNUC_WARN_UNUSED_RESULT',
'GLIB_AVAILABLE_IN_ALL',
]
foreach i : range(first_version, last_version + 2, 2)
version = i.to_string()
ignore_decorators += [
# Note that gtkdoc is going to use those in regex, and the longest match
# must come first. That's why '_FOR()' variant comes first.
# gtkdoc special-case '()' and replace it by a regex matching a symbol name.
'GLIB_AVAILABLE_IN_2_' + version,
'GLIB_DEPRECATED_IN_2_' + version + '_FOR()',
'GLIB_DEPRECATED_IN_2_' + version,
'GLIB_AVAILABLE_STATIC_INLINE_IN_2_' + version,
'GLIB_AVAILABLE_ENUMERATOR_IN_2_' + version,
'GLIB_DEPRECATED_ENUMERATOR_IN_2_' + version + '_FOR()',
'GLIB_DEPRECATED_ENUMERATOR_IN_2_' + version,
'GLIB_AVAILABLE_MACRO_IN_2_' + version,
'GLIB_DEPRECATED_MACRO_IN_2_' + version + '_FOR()',
'GLIB_DEPRECATED_MACRO_IN_2_' + version,
'GLIB_AVAILABLE_TYPE_IN_2_' + version,
'GLIB_DEPRECATED_TYPE_IN_2_' + version + '_FOR()',
'GLIB_DEPRECATED_TYPE_IN_2_' + version,
]
endforeach
ignore_decorators = '|'.join(ignore_decorators)
if get_option('gtk_doc')
# Check we have the minimum gtk-doc version required. Older versions won't
# generate correct documentation.
dependency('gtk-doc', version : '>=1.32.1',
fallback : ['gtk-doc', 'dummy_dep'],
default_options : ['tests=false'])
# We cannot built the API reference off of a static library,
# as symbols might get dropped by the linker
if not glib_build_shared
error('The API reference can only be built against a shared library')
endif
endif
# gi-docgen version
if get_option('gtk_doc') and enable_gir
gidocgen_dep = dependency('gi-docgen', version: '>= 2023.1',
fallback: ['gi-docgen', 'dummy_dep'],

2
gio/gdrive.c
View File

@ -37,7 +37,7 @@
* It’s generally only created for removable hardware or hardware with
* removable media.
*
* `GDrive` is a container class for [class@Gio.Volume] objects that stem from
* `GDrive` is a container class for [iface@Gio.Volume] objects that stem from
* the same piece of media. As such, `GDrive` abstracts a drive with
* (or without) removable media and provides operations for querying
* whether media is available, determining whether media change is

4
gio/gmount.c
View File

@ -54,9 +54,9 @@
* [method@Gio.Mount.unmount_with_operation] with (at least) the `GMount`
* instance and a [type@Gio.AsyncReadyCallback]. The callback will be fired
* when the operation has resolved (either with success or failure), and a
* [struct@Gio.AsyncResult] structure will be passed to the callback. That
* [iface@Gio.AsyncResult] structure will be passed to the callback. That
* callback should then call [method@Gio.Mount.unmount_with_operation_finish]
* with the `GMount` and the [struct@Gio.AsyncResult] data to see if the
* with the `GMount` and the [iface@Gio.AsyncResult] data to see if the
* operation was completed successfully. If an `error` is present when
* [method@Gio.Mount.unmount_with_operation_finish] is called, then it will be
* filled with any error information.

2
gio/gsocketservice.c
View File

@ -47,7 +47,7 @@
*
* The socket service runs on the main loop of the
* thread-default context (see
* [method@GLib.MainContext.push_thread_default_context]) of the thread it is
* [method@GLib.MainContext.push_thread_default]) of the thread it is
* created in, and is not threadsafe in general. However, the calls to start and
* stop the service are thread-safe so these can be used from threads that
* handle incoming clients.

6
gio/gvolume.c
View File

@ -39,7 +39,7 @@
* `GVolume` is the moral equivalent of `GnomeVFSDrive`.
*
* Mounting a `GVolume` instance is an asynchronous operation. For more
* information about asynchronous operations, see [class@Gio.AsyncResult] and
* information about asynchronous operations, see [iface@Gio.AsyncResult] and
* [class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount]
* with (at least) the `GVolume` instance, optionally a
* [class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback].
@ -50,10 +50,10 @@
* for credentials.
*
* The callback will be fired when the operation has resolved (either
* with success or failure), and a [class@Gio.AsyncResult] instance will be
* with success or failure), and a [iface@Gio.AsyncResult] instance will be
* passed to the callback. That callback should then call
* [method@Gio.Volume.mount_finish] with the `GVolume` instance and the
* [class@Gio.AsyncResult] data to see if the operation was completed
* [iface@Gio.AsyncResult] data to see if the operation was completed
* successfully. If a [type@GLib.Error] is present when
* [method@Gio.Volume.mount_finish] is called, then it will be filled with any
* error information.

11
glib/deprecated/gthread-deprecated.c
View File

@ -40,17 +40,6 @@
/* {{{1 Documentation */
/**
* SECTION:threads-deprecated
* @title: Deprecated thread API
* @short_description: old thread APIs (for reference only)
* @see_also: #GThread
*
* These APIs are deprecated. You should not use them in new code.
* This section remains only to assist with understanding code that was
* written to use these APIs at some point in the past.
**/
/**
* GThreadPriority:
* @G_THREAD_PRIORITY_LOW: a priority lower than normal

1139
glib/docs.c
View File

File diff suppressed because it is too large Load Diff

43
glib/gatomic.c
View File

@ -23,49 +23,6 @@
#include "gatomic.h"
/**
* SECTION:atomic_operations
* @title: Atomic Operations
* @short_description: basic atomic integer and pointer operations
* @see_also: #GMutex
*
* The following is a collection of compiler macros to provide atomic
* access to integer and pointer-sized values.
*
* The macros that have 'int' in the name will operate on pointers to
* #gint and #guint. The macros with 'pointer' in the name will operate
* on pointers to any pointer-sized value, including #guintptr. There is
* no support for 64bit operations on platforms with 32bit pointers
* because it is not generally possible to perform these operations
* atomically.
*
* The get, set and exchange operations for integers and pointers
* nominally operate on #gint and #gpointer, respectively. Of the
* arithmetic operations, the 'add' operation operates on (and returns)
* signed integer values (#gint and #gssize) and the 'and', 'or', and
* 'xor' operations operate on (and return) unsigned integer values
* (#guint and #gsize).
*
* All of the operations act as a full compiler and (where appropriate)
* hardware memory barrier. Acquire and release or producer and
* consumer barrier semantics are not available through this API.
*
* It is very important that all accesses to a particular integer or
* pointer be performed using only this API and that different sizes of
* operation are not mixed or used on overlapping memory regions. Never
* read or assign directly from or to a value -- always use this API.
*
* For simple reference counting purposes you should use
* g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
* fall outside of simple reference counting patterns are prone to
* subtle bugs and occasionally undefined behaviour. It is also worth
* noting that since all of these operations require global
* synchronisation of the entire machine, they can be quite slow. In
* the case of performing multiple atomic operations it can often be
* faster to simply acquire a mutex lock around the critical area,
* perform the operations normally and then release the lock.
**/
/**
* G_ATOMIC_LOCK_FREE:
*

24
glib/gbase64.c
View File

@ -31,30 +31,6 @@
#include "gtestutils.h"
#include "glibintl.h"
/**
* SECTION:base64
* @title: Base64 Encoding
* @short_description: encodes and decodes data in Base64 format
*
* Base64 is an encoding that allows a sequence of arbitrary bytes to be
* encoded as a sequence of printable ASCII characters. For the definition
* of Base64, see
* [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
* or
* [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
* Base64 is most commonly used as a MIME transfer encoding
* for email.
*
* GLib supports incremental encoding using g_base64_encode_step() and
* g_base64_encode_close(). Incremental decoding can be done with
* g_base64_decode_step(). To encode or decode data in one go, use
* g_base64_encode() or g_base64_decode(). To avoid memory allocation when
* decoding, you can use g_base64_decode_inplace().
*
* Support for Base64 encoding has been added in GLib 2.12.
*/
static const char base64_alphabet[] =
"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

75
glib/gdataset.c
View File

@ -48,85 +48,12 @@
#include "glib_trace.h"
#include "galloca.h"
/**
* SECTION:datasets
* @title: Datasets
* @short_description: associate groups of data elements with
* particular memory locations
*
* Datasets associate groups of data elements with particular memory
* locations. These are useful if you need to associate data with a
* structure returned from an external library. Since you cannot modify
* the structure, you use its location in memory as the key into a
* dataset, where you can associate any number of data elements with it.
*
* There are two forms of most of the dataset functions. The first form
* uses strings to identify the data elements associated with a
* location. The second form uses #GQuark identifiers, which are
* created with a call to g_quark_from_string() or
* g_quark_from_static_string(). The second form is quicker, since it
* does not require looking up the string in the hash table of #GQuark
* identifiers.
*
* There is no function to create a dataset. It is automatically
* created as soon as you add elements to it.
*
* To add data elements to a dataset use g_dataset_id_set_data(),
* g_dataset_id_set_data_full(), g_dataset_set_data() and
* g_dataset_set_data_full().
*
* To get data elements from a dataset use g_dataset_id_get_data() and
* g_dataset_get_data().
*
* To iterate over all data elements in a dataset use
* g_dataset_foreach() (not thread-safe).
*
* To remove data elements from a dataset use
* g_dataset_id_remove_data() and g_dataset_remove_data().
*
* To destroy a dataset, use g_dataset_destroy().
**/
/**
* SECTION:datalist
* @title: Keyed Data Lists
* @short_description: lists of data elements which are accessible by a
* string or GQuark identifier
*
* Keyed data lists provide lists of arbitrary data elements which can
* be accessed either with a string or with a #GQuark corresponding to
* the string.
*
* The #GQuark methods are quicker, since the strings have to be
* converted to #GQuarks anyway.
*
* Data lists are used for associating arbitrary data with #GObjects,
* using g_object_set_data() and related functions.
*
* To create a datalist, use g_datalist_init().
*
* To add data elements to a datalist use g_datalist_id_set_data(),
* g_datalist_id_set_data_full(), g_datalist_set_data() and
* g_datalist_set_data_full().
*
* To get data elements from a datalist use g_datalist_id_get_data()
* and g_datalist_get_data().
*
* To iterate over all data elements in a datalist use
* g_datalist_foreach() (not thread-safe).
*
* To remove data elements from a datalist use
* g_datalist_id_remove_data() and g_datalist_remove_data().
*
* To remove all data elements from a datalist, use g_datalist_clear().
**/
/**
* GData:
*
* An opaque data structure that represents a keyed data list.
*
* See also: [Keyed data lists][glib-Keyed-Data-Lists].
* See also: [Keyed data lists](datalist-and-dataset.html).
**/
/**

37
glib/gfileutils.c
View File

@ -59,43 +59,6 @@
#include "glibintl.h"
/**
* SECTION:fileutils
* @title: File Utilities
* @short_description: various file-related functions
*
* Do not use these APIs unless you are porting a POSIX application to Windows.
* A more high-level file access API is provided as GIO — see the documentation
* for #GFile.
*
* There is a group of functions which wrap the common POSIX functions
* dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(),
* g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these
* wrappers is to make it possible to handle file names with any Unicode
* characters in them on Windows without having to use ifdefs and the
* wide character API in the application code.
*
* On some Unix systems, these APIs may be defined as identical to their POSIX
* counterparts. For this reason, you must check for and include the necessary
* header files (such as `fcntl.h`) before using functions like g_creat(). You
* must also define the relevant feature test macros.
*
* The pathname argument should be in the GLib file name encoding.
* On POSIX this is the actual on-disk encoding which might correspond
* to the locale settings of the process (or the `G_FILENAME_ENCODING`
* environment variable), or not.
*
* On Windows the GLib file name encoding is UTF-8. Note that the
* Microsoft C library does not use UTF-8, but has separate APIs for
* current system code page and wide characters (UTF-16). The GLib
* wrappers call the wide character API if present (on modern Windows
* systems), otherwise convert to/from the system code page.
*
* Another group of functions allows to open and read directories
* in the GLib file name encoding. These are g_dir_open(),
* g_dir_read_name(), g_dir_rewind(), g_dir_close().
*/
/**
* GFileError:
* @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of

10
glib/ghook.c
View File

@ -38,16 +38,6 @@
#include "gtestutils.h"
#include "gslice.h"
/**
* SECTION:hooks
* @title: Hook Functions
* @short_description: support for manipulating lists of hook functions
*
* The #GHookList, #GHook and their related functions provide support for
* lists of hook functions. Functions can be added and removed from the lists,
* and the list of hook functions can be invoked.
*/
/**
* GHookList:
* @seq_id: the next free #GHook id

18
glib/ghostutils.c
View File

@ -41,24 +41,6 @@
#endif
/**
* SECTION:ghostutils
* @short_description: Internet hostname utilities
*
* Functions for manipulating internet hostnames; in particular, for
* converting between Unicode and ASCII-encoded forms of
* Internationalized Domain Names (IDNs).
*
* The
* [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
* standards allow for the use
* of Unicode domain names in applications, while providing
* backward-compatibility with the old ASCII-only DNS, by defining an
* ASCII-Compatible Encoding of any given Unicode name, which can be
* used with non-IDN-aware applications and protocols. (For example,
* "Παν語.org" maps to "xn--4wa8awb4637h.org".)
**/
#define IDNA_ACE_PREFIX "xn--"
#define IDNA_ACE_PREFIX_LEN 4

15
glib/glib-unix.c
View File

@ -44,21 +44,6 @@ G_STATIC_ASSERT (G_ALIGNOF (GPid) == G_ALIGNOF (pid_t));
* might not be true everywhere. */
G_STATIC_ASSERT (O_NONBLOCK != FD_CLOEXEC);
/**
* SECTION:gunix
* @title: UNIX-specific utilities and integration
* @short_description: pipes, signal handling
* @include: glib-unix.h
*
* Most of GLib is intended to be portable; in contrast, this set of
* functions is designed for programs which explicitly target UNIX,
* or are using it to build higher level abstractions which would be
* conditionally compiled if the platform matches %G_OS_UNIX.
*
* To use these functions, you must explicitly include the
* "glib-unix.h" header.
*/
G_DEFINE_QUARK (g-unix-error-quark, g_unix_error)
static gboolean

30
glib/gmem.c
View File

@ -77,36 +77,6 @@ static GMemVTable glib_mem_vtable = {
realloc,
};
/**
* SECTION:memory
* @Short_Description: general memory-handling
* @Title: Memory Allocation
*
* These functions provide support for allocating and freeing memory.
*
* If any call to allocate memory using functions g_new(), g_new0(), g_renew(),
* g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n()
* fails, the application is terminated. This also means that there is no
* need to check if the call succeeded. On the other hand, the `g_try_...()` family
* of functions returns %NULL on failure that can be used as a check
* for unsuccessful memory allocation. The application is not terminated
* in this case.
*
* As all GLib functions and data structures use `g_malloc()` internally, unless
* otherwise specified, any allocation failure will result in the application
* being terminated.
*
* It's important to match g_malloc() (and wrappers such as g_new()) with
* g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
* g_slice_free(), plain malloc() with free(), and (if you're using C++)
* new with delete and new[] with delete[]. Otherwise bad things can happen,
* since these allocators may use different memory pools (and new/delete call
* constructors and destructors).
*
* Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc
* implementation.
*/
/* --- functions --- */
/**
* g_malloc:

18
glib/gprintf.c
View File

@ -31,7 +31,7 @@
/**
* g_printf:
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output.
*
* An implementation of the standard printf() function which supports
@ -65,7 +65,7 @@ g_printf (gchar const *format,
* g_fprintf:
* @file: (not nullable): the stream to write to.
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output.
*
* An implementation of the standard fprintf() function which supports
@ -98,7 +98,7 @@ g_fprintf (FILE *file,
* is up to the caller to ensure that the allocated buffer is large
* enough to hold the formatted result
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output.
*
* An implementation of the standard sprintf() function which supports
@ -136,7 +136,7 @@ g_sprintf (gchar *string,
* @n: the maximum number of bytes to produce (including the
* terminating nul character).
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the arguments to insert in the output.
*
* A safer form of the standard sprintf() function. The output is guaranteed
@ -179,7 +179,7 @@ g_snprintf (gchar *string,
/**
* g_vprintf:
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output.
*
* An implementation of the standard vprintf() function which supports
@ -204,7 +204,7 @@ g_vprintf (gchar const *format,
* g_vfprintf:
* @file: (not nullable): the stream to write to.
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output.
*
* An implementation of the standard fprintf() function which supports
@ -230,7 +230,7 @@ g_vfprintf (FILE *file,
* g_vsprintf:
* @string: the buffer to hold the output.
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output.
*
* An implementation of the standard vsprintf() function which supports
@ -259,7 +259,7 @@ g_vsprintf (gchar *string,
* @n: the maximum number of bytes to produce (including the
* terminating nul character).
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output.
*
* A safer form of the standard vsprintf() function. The output is guaranteed
@ -300,7 +300,7 @@ g_vsnprintf (gchar *string,
* @string: (not optional) (nullable): the return location for the newly-allocated string,
* which will be %NULL if (and only if) this function fails
* @format: (not nullable): a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of arguments to insert in the output.
*
* An implementation of the GNU vasprintf() function which supports

4
glib/gquark.c
View File

@ -78,8 +78,8 @@ g_quark_init (void)
* Given either the string or the `GQuark` identifier it is possible to
* retrieve the other.
*
* Quarks are used for both [datasets][glib-Datasets] and
* [keyed data lists][glib-Keyed-Data-Lists].
* Quarks are used for both
* [datasets and keyed data lists](datalist-and-dataset.html).
*
* To create a new quark from a string, use [func@GLib.quark_from_string]
* or [func@GLib.quark_from_static_string].

51
glib/grand.c
View File

@ -62,57 +62,6 @@
#include <process.h> /* For getpid() */
#endif
/**
* SECTION:random_numbers
* @title: Random Numbers
* @short_description: pseudo-random number generator
*
* The following functions allow you to use a portable, fast and good
* pseudo-random number generator (PRNG).
*
* Do not use this API for cryptographic purposes such as key
* generation, nonces, salts or one-time pads.
*
* This PRNG is suitable for non-cryptographic use such as in games
* (shuffling a card deck, generating levels), generating data for
* a test suite, etc. If you need random data for cryptographic
* purposes, it is recommended to use platform-specific APIs such
* as `/dev/random` on UNIX, or CryptGenRandom() on Windows.
*
* GRand uses the Mersenne Twister PRNG, which was originally
* developed by Makoto Matsumoto and Takuji Nishimura. Further
* information can be found at
* [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
*
* If you just need a random number, you simply call the g_random_*
* functions, which will create a globally used #GRand and use the
* according g_rand_* functions internally. Whenever you need a
* stream of reproducible random numbers, you better create a
* #GRand yourself and use the g_rand_* functions directly, which
* will also be slightly faster. Initializing a #GRand with a
* certain seed will produce exactly the same series of random
* numbers on all platforms. This can thus be used as a seed for
* e.g. games.
*
* The g_rand*_range functions will return high quality equally
* distributed random numbers, whereas for example the
* `(g_random_int()%max)` approach often
* doesn't yield equally distributed numbers.
*
* GLib changed the seeding algorithm for the pseudo-random number
* generator Mersenne Twister, as used by #GRand. This was necessary,
* because some seeds would yield very bad pseudo-random streams.
* Also the pseudo-random integers generated by g_rand*_int_range()
* will have a slightly better equal distribution with the new
* version of GLib.
*
* 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 `G_RANDOM_VERSION` 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.
*/
/**
* GRand:
*

3
glib/gregex.c
View File

@ -45,7 +45,8 @@
* A `GRegex` is the "compiled" form of a regular expression pattern.
*
* `GRegex` implements regular expression pattern matching using syntax and
* semantics similar to Perl regular expression.
* semantics similar to Perl regular expression. See the
* [PCRE documentation](man:pcrepattern(3)) for the syntax definition.
*
* Some functions accept a @start_position argument, setting it differs
* from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL

14
glib/gshell.c
View File

@ -33,20 +33,6 @@
#include "glibintl.h"
#include "gthread.h"
/**
* SECTION:shell
* @title: Shell-related Utilities
* @short_description: shell-like commandline handling
*
* GLib provides the functions g_shell_quote() and g_shell_unquote()
* to handle shell-like quoting in strings. The function g_shell_parse_argv()
* parses a string similar to the way a POSIX shell (/bin/sh) would.
*
* Note that string handling in shells has many obscure and historical
* corner-cases which these functions do not necessarily reproduce. They
* are good enough in practice, though.
*/
/**
* G_SHELL_ERROR:
*

61
glib/gspawn.c
View File

@ -110,67 +110,6 @@ extern char **environ;
#define HAVE_O_CLOEXEC 1
#endif
/**
* SECTION:spawn
* @Short_description: process launching
* @Title: Spawning Processes
*
* GLib supports spawning of processes with an API that is more
* convenient than the bare UNIX fork() and exec().
*
* The g_spawn family of functions has synchronous (g_spawn_sync())
* and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()),
* as well as convenience variants that take a complete shell-like
* commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()).
*
* See #GSubprocess in GIO for a higher-level API that provides
* stream interfaces for communication with child processes.
*
* An example of using g_spawn_async_with_pipes():
* |[<!-- language="C" -->
* const gchar * const argv[] = { "my-favourite-program", "--args", NULL };
* gint child_stdout, child_stderr;
* GPid child_pid;
* g_autoptr(GError) error = NULL;
*
* // Spawn child process.
* g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL,
* NULL, &child_pid, NULL, &child_stdout,
* &child_stderr, &error);
* if (error != NULL)
* {
* g_error ("Spawning child failed: %s", error->message);
* return;
* }
*
* // Add a child watch function which will be called when the child process
* // exits.
* g_child_watch_add (child_pid, child_watch_cb, NULL);
*
* // You could watch for output on @child_stdout and @child_stderr using
* // #GUnixInputStream or #GIOChannel here.
*
* static void
* child_watch_cb (GPid pid,
* gint status,
* gpointer user_data)
* {
* g_message ("Child %" G_PID_FORMAT " exited %s", pid,
* g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally");
*
* // Free any resources associated with the child here, such as I/O channels
* // on its stdout and stderr FDs. If you have no code to put in the
* // child_watch_cb() callback, you can remove it and the g_child_watch_add()
* // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag,
* // otherwise the child process will stay around as a zombie until this
* // process exits.
*
* g_spawn_close_pid (pid);
* }
* ]|
*/
static gint g_execute (const gchar *file,
gchar **argv,
gchar **argv_buffer,

43
glib/gstrfuncs.c
View File

@ -57,45 +57,6 @@
#include "gprintfint.h"
#include "glibintl.h"
/**
* SECTION:string_utils
* @title: String Utility Functions
* @short_description: various string-related functions
*
* This section describes a number of utility functions for creating,
* duplicating, and manipulating strings.
*
* Note that the functions g_printf(), g_fprintf(), g_sprintf(),
* g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf()
* are declared in the header `gprintf.h` which is not included in `glib.h`
* (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
* explicitly include `<glib/gprintf.h>` in order to use the GLib
* printf() functions.
*
* ## String precision pitfalls # {#string-precision}
*
* While you may use the printf() functions to format UTF-8 strings,
* notice that the precision of a \%Ns parameter is interpreted
* as the number of bytes, not characters to print. On top of that,
* the GNU libc implementation of the printf() functions has the
* "feature" that it checks that the string given for the \%Ns
* parameter consists of a whole number of characters in the current
* encoding. So, unless you are sure you are always going to be in an
* UTF-8 locale or your know your text is restricted to ASCII, avoid
* using \%Ns. If your intention is to format strings for a
* certain number of columns, then \%Ns is not a correct solution
* anyway, since it fails to take wide characters (see g_unichar_iswide())
* into account.
*
* Note also that there are various printf() parameters which are platform
* dependent. GLib provides platform independent macros for these parameters
* which should be used instead. A common example is %G_GUINT64_FORMAT, which
* should be used instead of `%llu` or similar parameters for formatting
* 64-bit integers. These macros are all named `G_*_FORMAT`; see
* [Basic Types][glib-Basic-Types].
*/
/**
* g_ascii_isalnum:
* @c: any character
@ -527,7 +488,7 @@ g_stpcpy (gchar *dest,
/**
* g_strdup_vprintf:
* @format: (not nullable): a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @args: the list of parameters to insert into the format string
*
* Similar to the standard C vsprintf() function but safer, since it
@ -558,7 +519,7 @@ g_strdup_vprintf (const gchar *format,
/**
* g_strdup_printf:
* @format: (not nullable): a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* [string precision pitfalls](string-utils.html#string-precision-pitfalls)
* @...: the parameters to insert into the format string
*
* Similar to the standard C sprintf() function but safer, since it

4
glib/gtrace.c
View File

@ -20,10 +20,6 @@
*/
/*
* SECTION:trace
* @Title: Performance tracing
* @Short_description: Functions for measuring and tracing performance
*
* The performance tracing functions allow for the performance of code using
* GLib to be measured by passing metrics from the current process to an
* external measurement process such as `sysprof-cli` or `sysprofd`.

36
glib/gtrashstack.c
View File

@ -33,35 +33,27 @@
#include "gtrashstack.h"
/**
* SECTION:trash_stack
* @title: Trash Stacks
* @short_description: maintain a stack of unused allocated memory chunks
*
* A #GTrashStack is an efficient way to keep a stack of unused allocated
* memory chunks. Each memory chunk is required to be large enough to hold
* a #gpointer. This allows the stack to be maintained without any space
* overhead, since the stack pointers can be stored inside the memory chunks.
*
* There is no function to create a #GTrashStack. A %NULL #GTrashStack*
* is a perfectly valid empty stack.
*
* There is no longer any good reason to use #GTrashStack. If you have
* extra pieces of memory, free() them and allocate them again later.
*
* Deprecated: 2.48: #GTrashStack is deprecated without replacement
*/
/**
* GTrashStack:
* @next: pointer to the previous element of the stack,
* gets stored in the first `sizeof (gpointer)`
* bytes of the element
*
* Each piece of memory that is pushed onto the stack
* is cast to a GTrashStack*.
* A `GTrashStack` is an efficient way to keep a stack of unused allocated
* memory chunks. Each memory chunk is required to be large enough to hold
* a `gpointer`. This allows the stack to be maintained without any space
* overhead, since the stack pointers can be stored inside the memory chunks.
*
* Deprecated: 2.48: #GTrashStack is deprecated without replacement
* There is no function to create a `GTrashStack`. A `NULL` `GTrashStack*`
* is a perfectly valid empty stack.
*
* Each piece of memory that is pushed onto the stack is cast to a
* `GTrashStack*`.
*
* There is no longer any good reason to use `GTrashStack`. If you have
* extra pieces of memory, `free()` them and allocate them again later.
*
* Deprecated: 2.48: `GTrashStack` is deprecated without replacement
*/
/**

207
glib/guri.c
View File

@ -29,23 +29,74 @@
#include "guriprivate.h"
/**
* SECTION:guri
* @short_description: URI-handling utilities
* @include: glib.h
* GUri:
*
* The #GUri type and related functions can be used to parse URIs into
* The `GUri` type and related functions can be used to parse URIs into
* their components, and build valid URIs from individual components.
*
* Note that #GUri scope is to help manipulate URIs in various applications,
* Since `GUri` only represents absolute URIs, all `GUri`s will have a
* URI scheme, so [method@GLib.Uri.get_scheme] will always return a non-`NULL`
* answer. Likewise, by definition, all URIs have a path component, so
* [method@GLib.Uri.get_path] will always return a non-`NULL` string (which may
* be empty).
*
* If the URI string has an
* [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that
* is, if the scheme is followed by `://` rather than just `:`), then the
* `GUri` will contain a hostname, and possibly a port and ‘userinfo’.
* Additionally, depending on how the `GUri` was constructed/parsed (for example,
* using the `G_URI_FLAGS_HAS_PASSWORD` and `G_URI_FLAGS_HAS_AUTH_PARAMS` flags),
* the userinfo may be split out into a username, password, and
* additional authorization-related parameters.
*
* Normally, the components of a `GUri` will have all `%`-encoded
* characters decoded. However, if you construct/parse a `GUri` with
* `G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in
* the userinfo, path, and query fields (and in the host field if also
* created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if
* the URI may contain binary data or non-UTF-8 text, or if decoding
* the components might change the interpretation of the URI.
*
* For example, with the encoded flag:
*
* ```c
* g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err);
* g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue");
* ```
*
* While the default `%`-decoding behaviour would give:
*
* ```c
* g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err);
* g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value");
* ```
*
* During decoding, if an invalid UTF-8 string is encountered, parsing will fail
* with an error indicating the bad string location:
*
* ```c
* g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err);
* g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
* ```
*
* You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you
* need to handle that case manually. In particular, if the query string
* contains `=` characters that are `%`-encoded, you should let
* [func@GLib.Uri.parse_params] do the decoding once of the query.
*
* `GUri` is immutable once constructed, and can safely be accessed from
* multiple threads. Its reference counting is atomic.
*
* Note that the scope of `GUri` is to help manipulate URIs in various applications,
* following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
* it doesn't intend to cover web browser needs, and doesn't implement the
* it doesn't intend to cover web browser needs, and doesn’t implement the
* [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
* help prevent
* [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
* #GUri is not suitable for formatting URIs for display to the user for making
* `GUri` is not suitable for formatting URIs for display to the user for making
* security-sensitive decisions.
*
* ## Relative and absolute URIs # {#relative-absolute-uris}
* ## Relative and absolute URIs
*
* As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
* hierarchical nature of URIs means that they can either be ‘relative
@ -65,145 +116,85 @@
*
* Absolute URIs have a scheme specified. Any other components of the URI which
* are missing are specified as explicitly unset in the URI, rather than being
* resolved relative to a base URI using g_uri_parse_relative().
* resolved relative to a base URI using [method@GLib.Uri.parse_relative].
*
* For example, a valid absolute URI is `file:///home/bob` or
* `https://search.com?query=string`.
*
* A #GUri instance is always an absolute URI. A string may be an absolute URI
* A `GUri` instance is always an absolute URI. A string may be an absolute URI
* or a relative reference; see the documentation for individual functions as to
* what forms they accept.
*
* ## Parsing URIs
*
* The most minimalist APIs for parsing URIs are g_uri_split() and
* g_uri_split_with_user(). These split a URI into its component
* The most minimalist APIs for parsing URIs are [func@GLib.Uri.split] and
* [func@GLib.Uri.split_with_user]. These split a URI into its component
* parts, and return the parts; the difference between the two is that
* g_uri_split() treats the ‘userinfo’ component of the URI as a
* single element, while g_uri_split_with_user() can (depending on the
* #GUriFlags you pass) treat it as containing a username, password,
* and authentication parameters. Alternatively, g_uri_split_network()
* [func@GLib.Uri.split] treats the ‘userinfo’ component of the URI as a
* single element, while [func@GLib.Uri.split_with_user] can (depending on the
* [flags@GLib.UriFlags] you pass) treat it as containing a username, password,
* and authentication parameters. Alternatively, [func@GLib.Uri.split_network]
* can be used when you are only interested in the components that are
* needed to initiate a network connection to the service (scheme,
* host, and port).
*
* g_uri_parse() is similar to g_uri_split(), but instead of returning
* individual strings, it returns a #GUri structure (and it requires
* [func@GLib.Uri.parse] is similar to [func@GLib.Uri.split], but instead of
* returning individual strings, it returns a `GUri` structure (and it requires
* that the URI be an absolute URI).
*
* g_uri_resolve_relative() and g_uri_parse_relative() allow you to
* resolve a relative URI relative to a base URI.
* g_uri_resolve_relative() takes two strings and returns a string,
* and g_uri_parse_relative() takes a #GUri and a string and returns a
* #GUri.
* [func@GLib.Uri.resolve_relative] and [method@GLib.Uri.parse_relative] allow
* you to resolve a relative URI relative to a base URI.
* [func@GLib.Uri.resolve_relative] takes two strings and returns a string,
* and [method@GLib.Uri.parse_relative] takes a `GUri` and a string and returns a
* `GUri`.
*
* All of the parsing functions take a #GUriFlags argument describing
* All of the parsing functions take a [flags@GLib.UriFlags] argument describing
* exactly how to parse the URI; see the documentation for that type
* for more details on the specific flags that you can pass. If you
* need to choose different flags based on the type of URI, you can
* use g_uri_peek_scheme() on the URI string to check the scheme
* use [func@GLib.Uri.peek_scheme] on the URI string to check the scheme
* first, and use that to decide what flags to parse it with.
*
* For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the
* params for a web URI, so compare the result of g_uri_peek_scheme() against
* `http` and `https`.
* For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the
* params for a web URI, so compare the result of [func@GLib.Uri.peek_scheme]
* against `http` and `https`.
*
* ## Building URIs
*
* g_uri_join() and g_uri_join_with_user() can be used to construct
* [func@GLib.Uri.join] and [func@GLib.Uri.join_with_user] can be used to construct
* valid URI strings from a set of component strings. They are the
* inverse of g_uri_split() and g_uri_split_with_user().
* inverse of [func@GLib.Uri.split] and [func@GLib.Uri.split_with_user].
*
* Similarly, g_uri_build() and g_uri_build_with_user() can be used to
* construct a #GUri from a set of component strings.
* Similarly, [func@GLib.Uri.build] and [func@GLib.Uri.build_with_user] can be
* used to construct a `GUri` from a set of component strings.
*
* As with the parsing functions, the building functions take a
* #GUriFlags argument. In particular, it is important to keep in mind
* [flags@GLib.UriFlags] argument. In particular, it is important to keep in mind
* whether the URI components you are using are already `%`-encoded. If so,
* you must pass the %G_URI_FLAGS_ENCODED flag.
* you must pass the `G_URI_FLAGS_ENCODED` flag.
*
* ## `file://` URIs
*
* Note that Windows and Unix both define special rules for parsing
* `file://` URIs (involving non-UTF-8 character sets on Unix, and the
* interpretation of path separators on Windows). #GUri does not
* implement these rules. Use g_filename_from_uri() and
* g_filename_to_uri() if you want to properly convert between
* interpretation of path separators on Windows). `GUri` does not
* implement these rules. Use [func@GLib.filename_from_uri] and
* [func@GLib.filename_to_uri] if you want to properly convert between
* `file://` URIs and local filenames.
*
* ## URI Equality
*
* Note that there is no `g_uri_equal ()` function, because comparing
* URIs usefully requires scheme-specific knowledge that #GUri does
* not have. #GUri can help with normalization if you use the various
* encoded #GUriFlags as well as %G_URI_FLAGS_SCHEME_NORMALIZE however
* it is not comprehensive.
* URIs usefully requires scheme-specific knowledge that `GUri` does
* not have. `GUri` can help with normalization if you use the various
* encoded [flags@GLib.UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE`
* however it is not comprehensive.
* For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
* thing according to the `data:` URI specification which GLib does not
* handle.
*
* Since: 2.66
*/
/**
* GUri:
*
* A parsed absolute URI.
*
* Since #GUri only represents absolute URIs, all #GUris will have a
* URI scheme, so g_uri_get_scheme() will always return a non-%NULL
* answer. Likewise, by definition, all URIs have a path component, so
* g_uri_get_path() will always return a non-%NULL string (which may be empty).
*
* If the URI string has an
* [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that
* is, if the scheme is followed by `://` rather than just `:`), then the
* #GUri will contain a hostname, and possibly a port and ‘userinfo’.
* Additionally, depending on how the #GUri was constructed/parsed (for example,
* using the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS flags),
* the userinfo may be split out into a username, password, and
* additional authorization-related parameters.
*
* Normally, the components of a #GUri will have all `%`-encoded
* characters decoded. However, if you construct/parse a #GUri with
* %G_URI_FLAGS_ENCODED, then the `%`-encoding will be preserved instead in
* the userinfo, path, and query fields (and in the host field if also
* created with %G_URI_FLAGS_NON_DNS). In particular, this is necessary if
* the URI may contain binary data or non-UTF-8 text, or if decoding
* the components might change the interpretation of the URI.
*
* For example, with the encoded flag:
*
* |[<!-- language="C" -->
* g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err);
* g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue");
* ]|
*
* While the default `%`-decoding behaviour would give:
*
* |[<!-- language="C" -->
* g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err);
* g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value");
* ]|
*
* During decoding, if an invalid UTF-8 string is encountered, parsing will fail
* with an error indicating the bad string location:
*
* |[<!-- language="C" -->
* g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err);
* g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
* ]|
*
* You should pass %G_URI_FLAGS_ENCODED or %G_URI_FLAGS_ENCODED_QUERY if you
* need to handle that case manually. In particular, if the query string
* contains `=` characters that are `%`-encoded, you should let
* g_uri_parse_params() do the decoding once of the query.
*
* #GUri is immutable once constructed, and can safely be accessed from
* multiple threads. Its reference counting is atomic.
*
* Since: 2.66
*/
struct _GUri {
gchar *scheme;
gchar *userinfo;
@ -1072,7 +1063,7 @@ g_uri_split_internal (const gchar *uri_string,
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_ref (which can be an
* [absolute or relative URI][relative-absolute-uris]) according to @flags, and
* [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
* returns the pieces. Any component that doesn't appear in @uri_ref will be
* returned as %NULL (but note that all URIs always have a path component,
* though it may be the empty string).
@ -1139,7 +1130,7 @@ g_uri_split (const gchar *uri_ref,
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_ref (which can be an
* [absolute or relative URI][relative-absolute-uris]) according to @flags, and
* [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
* returns the pieces. Any component that doesn't appear in @uri_ref will be
* returned as %NULL (but note that all URIs always have a path component,
* though it may be the empty string).
@ -1191,7 +1182,7 @@ g_uri_split_with_user (const gchar *uri_ref,
* port, or `-1`
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_string (which must be an [absolute URI][relative-absolute-uris])
* Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris))
* according to @flags, and returns the pieces relevant to connecting to a host.
* See the documentation for g_uri_split() for more details; this is
* mostly a wrapper around that function with simpler arguments.
@ -1260,7 +1251,7 @@ g_uri_split_network (const gchar *uri_string,
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_string according to @flags, to determine whether it is a valid
* [absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
* [absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved
* relative to another URI using g_uri_parse_relative().
*
* If it’s not a valid URI, an error is returned explaining how it’s invalid.
@ -1398,7 +1389,7 @@ remove_dot_segments (gchar *path)
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_string according to @flags. If the result is not a
* valid [absolute URI][relative-absolute-uris], it will be discarded, and an
* valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an
* error returned.
*
* Return value: (transfer full): a new #GUri, or NULL on error.
@ -1424,7 +1415,7 @@ g_uri_parse (const gchar *uri_string,
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_ref according to @flags and, if it is a
* [relative URI][relative-absolute-uris], resolves it relative to @base_uri.
* [relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri.
* If the result is not a valid absolute URI, it will be discarded, and an error
* returned.
*
@ -1555,7 +1546,7 @@ g_uri_parse_relative (GUri *base_uri,
* @error: #GError for error reporting, or %NULL to ignore.
*
* Parses @uri_ref according to @flags and, if it is a
* [relative URI][relative-absolute-uris], resolves it relative to
* [relative URI](#relative-and-absolute-uris), resolves it relative to
* @base_uri_string. If the result is not a valid absolute URI, it will be
* discarded, and an error returned.
*

8
glib/gutils.c
View File

@ -79,14 +79,6 @@
#endif
/**
* SECTION:misc_utils
* @title: Miscellaneous Utility Functions
* @short_description: a selection of portable utility functions
*
* These are portable utility functions.
*/
#ifdef G_PLATFORM_WIN32
# include <windows.h>
# ifndef GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS

22
glib/guuid.c
View File

@ -35,28 +35,6 @@ typedef struct {
guint8 bytes[16];
} GUuid;
/**
* SECTION:uuid
* @title: GUuid
* @short_description: a universally unique identifier
*
* A UUID, or Universally unique identifier, is intended to uniquely
* identify information in a distributed environment. For the
* definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html).
*
* The creation of UUIDs does not require a centralized authority.
*
* UUIDs are of relatively small size (128 bits, or 16 bytes). The
* common string representation (ex:
* 1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes.
*
* The UUID specification defines 5 versions, and calling
* g_uuid_string_random() will generate a unique (or rather random)
* UUID of the most common version, version 4.
*
* Since: 2.52
*/
/*
* g_uuid_to_string:
* @uuid: a #GUuid

8
glib/gvariant-core.c
View File

@ -49,14 +49,6 @@
* Most GVariant API functions are in gvariant.c.
*/
/**
* GVariant:
*
* #GVariant is an opaque data structure and can only be accessed
* using the following functions.
*
* Since: 2.24
**/
struct _GVariant
/* see below for field member documentation */
{

179
glib/gvariant.c
View File

@ -36,115 +36,114 @@
#include <string.h>
/**
* SECTION:gvariant
* @title: GVariant
* @short_description: strongly typed value datatype
* @see_also: GVariantType
* GVariant:
*
* #GVariant is a variant datatype; it can contain one or more values
* `GVariant` is a variant datatype; it can contain one or more values
* along with information about the type of the values.
*
* A #GVariant may contain simple types, like an integer, or a boolean value;
* A `GVariant` may contain simple types, like an integer, or a boolean value;
* or complex types, like an array of two strings, or a dictionary of key
* value pairs. A #GVariant is also immutable: once it's been created neither
* value pairs. A `GVariant` is also immutable: once it’s been created neither
* its type nor its content can be modified further.
*
* GVariant is useful whenever data needs to be serialized, for example when
* sending method parameters in D-Bus, or when saving settings using GSettings.
* `GVariant` is useful whenever data needs to be serialized, for example when
* sending method parameters in D-Bus, or when saving settings using
* [class@Gio.Settings].
*
* When creating a new #GVariant, you pass the data you want to store in it
* When creating a new `GVariant`, you pass the data you want to store in it
* along with a string representing the type of data you wish to pass to it.
*
* For instance, if you want to create a #GVariant holding an integer value you
* For instance, if you want to create a `GVariant` holding an integer value you
* can use:
*
* |[<!-- language="C" -->
* GVariant *v = g_variant_new ("u", 40);
* ]|
* ```c
* GVariant *v = g_variant_new ("u", 40);
* ```
*
* The string "u" in the first argument tells #GVariant that the data passed to
* the constructor (40) is going to be an unsigned integer.
* The string `u` in the first argument tells `GVariant` that the data passed to
* the constructor (`40`) is going to be an unsigned integer.
*
* More advanced examples of #GVariant in use can be found in documentation for
* [GVariant format strings][gvariant-format-strings-pointers].
* More advanced examples of `GVariant` in use can be found in documentation for
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* The range of possible values is determined by the type.
*
* The type system used by #GVariant is #GVariantType.
* The type system used by `GVariant` is [type@GLib.VariantType].
*
* #GVariant instances always have a type and a value (which are given
* at construction time). The type and value of a #GVariant instance
* can never change other than by the #GVariant itself being
* destroyed. A #GVariant cannot contain a pointer.
* `GVariant` instances always have a type and a value (which are given
* at construction time). The type and value of a `GVariant` instance
* can never change other than by the `GVariant` itself being
* destroyed. A `GVariant` cannot contain a pointer.
*
* #GVariant is reference counted using g_variant_ref() and
* g_variant_unref(). #GVariant also has floating reference counts --
* see g_variant_ref_sink().
* `GVariant` is reference counted using [method@GLib.Variant.ref] and
* [method@GLib.Variant.unref]. `GVariant` also has floating reference counts —
* see [method@GLib.Variant.ref_sink].
*
* #GVariant is completely threadsafe. A #GVariant instance can be
* `GVariant` is completely threadsafe. A `GVariant` instance can be
* concurrently accessed in any way from any number of threads without
* problems.
*
* #GVariant is heavily optimised for dealing with data in serialized
* `GVariant` is heavily optimised for dealing with data in serialized
* form. It works particularly well with data located in memory-mapped
* files. It can perform nearly all deserialization operations in a
* small constant time, usually touching only a single memory page.
* Serialized #GVariant data can also be sent over the network.
* Serialized `GVariant` data can also be sent over the network.
*
* #GVariant is largely compatible with D-Bus. Almost all types of
* #GVariant instances can be sent over D-Bus. See #GVariantType for
* exceptions. (However, #GVariant's serialization format is not the same
* as the serialization format of a D-Bus message body: use #GDBusMessage,
* in the gio library, for those.)
* `GVariant` is largely compatible with D-Bus. Almost all types of
* `GVariant` instances can be sent over D-Bus. See [type@GLib.VariantType] for
* exceptions. (However, `GVariant`’s serialization format is not the same
* as the serialization format of a D-Bus message body: use
* [class@Gio.DBusMessage], in the GIO library, for those.)
*
* For space-efficiency, the #GVariant serialization format does not
* automatically include the variant's length, type or endianness,
* For space-efficiency, the `GVariant` serialization format does not
* automatically include the variant’s length, type or endianness,
* which must either be implied from context (such as knowledge that a
* particular file format always contains a little-endian
* %G_VARIANT_TYPE_VARIANT which occupies the whole length of the file)
* `G_VARIANT_TYPE_VARIANT` which occupies the whole length of the file)
* or supplied out-of-band (for instance, a length, type and/or endianness
* indicator could be placed at the beginning of a file, network message
* or network stream).
*
* A #GVariant's size is limited mainly by any lower level operating
* system constraints, such as the number of bits in #gsize. For
* A `GVariant`’s size is limited mainly by any lower level operating
* system constraints, such as the number of bits in `gsize`. For
* example, it is reasonable to have a 2GB file mapped into memory
* with #GMappedFile, and call g_variant_new_from_data() on it.
* with [struct@GLib.MappedFile], and call [ctor@GLib.Variant.new_from_data] on
* it.
*
* For convenience to C programmers, #GVariant features powerful
* For convenience to C programmers, `GVariant` features powerful
* varargs-based value construction and destruction. This feature is
* designed to be embedded in other libraries.
*
* There is a Python-inspired text language for describing #GVariant
* values. #GVariant includes a printer for this language and a parser
* There is a Python-inspired text language for describing `GVariant`
* values. `GVariant` includes a printer for this language and a parser
* with type inferencing.
*
* ## Memory Use
*
* #GVariant tries to be quite efficient with respect to memory use.
* `GVariant` tries to be quite efficient with respect to memory use.
* This section gives a rough idea of how much memory is used by the
* current implementation. The information here is subject to change
* in the future.
*
* The memory allocated by #GVariant can be grouped into 4 broad
* The memory allocated by `GVariant` can be grouped into 4 broad
* purposes: memory for serialized data, memory for the type
* information cache, buffer management memory and memory for the
* #GVariant structure itself.
* `GVariant` structure itself.
*
* ## Serialized Data Memory
*
* This is the memory that is used for storing GVariant data in
* This is the memory that is used for storing `GVariant` data in
* serialized form. This is what would be sent over the network or
* what would end up on disk, not counting any indicator of the
* endianness, or of the length or type of the top-level variant.
*
* The amount of memory required to store a boolean is 1 byte. 16,
* 32 and 64 bit integers and double precision floating point numbers
* use their "natural" size. Strings (including object path and
* use their ‘natural’ size. Strings (including object path and
* signature strings) are stored with a nul terminator, and as such
* use the length of the string plus 1 byte.
*
* Maybe types use no space at all to represent the null value and
* ‘Maybe’ types use no space at all to represent the null value and
* use the same amount of space (sometimes plus one byte) as the
* equivalent non-maybe-typed value to represent the non-null case.
*
@ -170,39 +169,39 @@
* In the case that the dictionary is empty, 0 bytes are required for
* the serialization.
*
* If we add an item "width" that maps to the int32 value of 500 then
* we will use 4 byte to store the int32 (so 6 for the variant
* If we add an item ‘width’ that maps to the int32 value of 500 then
* we will use 4 bytes to store the int32 (so 6 for the variant
* containing it) and 6 bytes for the string. The variant must be
* aligned to 8 after the 6 bytes of the string, so that's 2 extra
* aligned to 8 after the 6 bytes of the string, so that’s 2 extra
* bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
* for the dictionary entry. An additional 1 byte is added to the
* array as a framing offset making a total of 15 bytes.
*
* If we add another entry, "title" that maps to a nullable string
* If we add another entry, ‘title’ that maps to a nullable string
* that happens to have a value of null, then we use 0 bytes for the
* null value (and 3 bytes for the variant to contain it along with
* its type string) plus 6 bytes for the string. Again, we need 2
* padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
*
* We now require extra padding between the two items in the array.
* After the 14 bytes of the first item, that's 2 bytes required.
* After the 14 bytes of the first item, that’s 2 bytes required.
* We now require 2 framing offsets for an extra two
* bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
* dictionary.
*
* ## Type Information Cache
*
* For each GVariant type that currently exists in the program a type
* For each `GVariant` type that currently exists in the program a type
* information structure is kept in the type information cache. The
* type information structure is required for rapid deserialization.
*
* Continuing with the above example, if a #GVariant exists with the
* type "a{sv}" then a type information struct will exist for
* "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
* Continuing with the above example, if a `GVariant` exists with the
* type `a{sv}` then a type information struct will exist for
* `a{sv}`, `{sv}`, `s`, and `v`. Multiple uses of the same type
* will share the same type information. Additionally, all
* single-digit types are stored in read-only static memory and do
* not contribute to the writable memory footprint of a program using
* #GVariant.
* `GVariant`.
*
* Aside from the type information structures stored in read-only
* memory, there are two forms of type information. One is used for
@ -210,23 +209,23 @@
* maybe types. The other is used for container types where there
* are multiple element types: tuples and dictionary entries.
*
* Array type info structures are 6 * sizeof (void *), plus the
* Array type info structures are `6 * sizeof (void *)`, plus the
* memory required to store the type string itself. This means that
* on 32-bit systems, the cache entry for "a{sv}" would require 30
* bytes of memory (plus malloc overhead).
* on 32-bit systems, the cache entry for `a{sv}` would require 30
* bytes of memory (plus allocation overhead).
*
* Tuple type info structures are 6 * sizeof (void *), plus 4 *
* sizeof (void *) for each item in the tuple, plus the memory
* Tuple type info structures are `6 * sizeof (void *)`, plus `4 *
* sizeof (void *)` for each item in the tuple, plus the memory
* required to store the type string itself. A 2-item tuple, for
* example, would have a type information structure that consumed
* writable memory in the size of 14 * sizeof (void *) (plus type
* writable memory in the size of `14 * sizeof (void *)` (plus type
* string) This means that on 32-bit systems, the cache entry for
* "{sv}" would require 61 bytes of memory (plus malloc overhead).
* `{sv}` would require 61 bytes of memory (plus allocation overhead).
*
* This means that in total, for our "a{sv}" example, 91 bytes of
* This means that in total, for our `a{sv}` example, 91 bytes of
* type information would be allocated.
*
* The type information cache, additionally, uses a #GHashTable to
* The type information cache, additionally, uses a [struct@GLib.HashTable] to
* store and look up the cached items and stores a pointer to this
* hash table in static storage. The hash table is freed when there
* are zero items in the type cache.
@ -238,34 +237,34 @@
*
* ## Buffer Management Memory
*
* #GVariant uses an internal buffer management structure to deal
* `GVariant` uses an internal buffer management structure to deal
* with the various different possible sources of serialized data
* that it uses. The buffer is responsible for ensuring that the
* correct call is made when the data is no longer in use by
* #GVariant. This may involve a g_free() or a g_slice_free() or
* even g_mapped_file_unref().
* `GVariant`. This may involve a [func@GLib.free] or
* even [method@GLib.MappedFile.unref].
*
* One buffer management structure is used for each chunk of
* serialized data. The size of the buffer management structure
* is 4 * (void *). On 32-bit systems, that's 16 bytes.
* is `4 * (void *)`. On 32-bit systems, that’s 16 bytes.
*
* ## GVariant structure
*
* The size of a #GVariant structure is 6 * (void *). On 32-bit
* systems, that's 24 bytes.
* The size of a `GVariant` structure is `6 * (void *)`. On 32-bit
* systems, that’s 24 bytes.
*
* #GVariant structures only exist if they are explicitly created
* with API calls. For example, if a #GVariant is constructed out of
* `GVariant` structures only exist if they are explicitly created
* with API calls. For example, if a `GVariant` is constructed out of
* serialized data for the example given above (with the dictionary)
* then although there are 9 individual values that comprise the
* entire dictionary (two keys, two values, two variants containing
* the values, two dictionary entries, plus the dictionary itself),
* only 1 #GVariant instance exists -- the one referring to the
* only 1 `GVariant` instance exists — the one referring to the
* dictionary.
*
* If calls are made to start accessing the other values then
* #GVariant instances will exist for those values only for as long
* as they are in use (ie: until you call g_variant_unref()). The
* `GVariant` instances will exist for those values only for as long
* as they are in use (ie: until you call [method@GLib.Variant.unref]). The
* type information is shared. The serialized data and the buffer
* management structure for that serialized data is shared by the
* child.
@ -276,13 +275,15 @@
* strings to variants (with two entries, as given above), we are
* using 91 bytes of memory for type information, 29 bytes of memory
* for the serialized data, 16 bytes for buffer management and 24
* bytes for the #GVariant instance, or a total of 160 bytes, plus
* malloc overhead. If we were to use g_variant_get_child_value() to
* access the two dictionary entries, we would use an additional 48
* bytes for the `GVariant` instance, or a total of 160 bytes, plus
* allocation overhead. If we were to use [method@GLib.Variant.get_child_value]
* to access the two dictionary entries, we would use an additional 48
* bytes. If we were to have other dictionaries of the same type, we
* would use more memory for the serialized data and buffer
* management for those dictionaries, but the type information would
* be shared.
*
* Since: 2.24
*/
/* definition of GVariant structure is in gvariant-core.c */
@ -964,7 +965,7 @@ g_variant_new_dict_entry (GVariant *key,
* @format_string determines the C types that are used for unpacking
* the values and also determines if the values are copied or borrowed,
* see the section on
* [GVariant format strings][gvariant-format-strings-pointers].
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* This function is currently implemented with a linear scan. If you
* plan to do many lookups then #GVariantDict may be more efficient.
@ -4045,7 +4046,7 @@ g_variant_dict_init (GVariantDict *dict,
*
* @format_string determines the C types that are used for unpacking the
* values and also determines if the values are copied or borrowed, see the
* section on [GVariant format strings][gvariant-format-strings-pointers].
* section on [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* Returns: %TRUE if a value was unpacked
*
@ -5505,7 +5506,7 @@ g_variant_new_va (const gchar *format_string,
* @format_string determines the C types that are used for unpacking
* the values and also determines if the values are copied or borrowed,
* see the section on
* [GVariant format strings][gvariant-format-strings-pointers].
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* Since: 2.24
**/
@ -5559,7 +5560,7 @@ g_variant_get (GVariant *value,
* @format_string determines the C types that are used for unpacking
* the values and also determines if the values are copied or borrowed,
* see the section on
* [GVariant format strings][gvariant-format-strings-pointers].
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* Since: 2.24
**/
@ -5654,7 +5655,7 @@ g_variant_builder_add (GVariantBuilder *builder,
* @format_string determines the C types that are used for unpacking
* the values and also determines if the values are copied or borrowed,
* see the section on
* [GVariant format strings][gvariant-format-strings-pointers].
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* Since: 2.24
**/
@ -5727,7 +5728,7 @@ g_variant_get_child (GVariant *value,
* the values and also determines if the values are copied or borrowed.
*
* See the section on
* [GVariant format strings][gvariant-format-strings-pointers].
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
*
@ -5826,7 +5827,7 @@ g_variant_iter_next (GVariantIter *iter,
* the values and also determines if the values are copied or borrowed.
*
* See the section on
* [GVariant format strings][gvariant-format-strings-pointers].
* [`GVariant` format strings](gvariant-format-strings.html#pointers).
*
* Returns: %TRUE if a value was unpacked, or %FALSE if there was no
* value

170
glib/gvarianttype.c
View File

@ -32,158 +32,160 @@
/**
* SECTION:gvarianttype
* @title: GVariantType
* @short_description: introduction to the GVariant type system
* @see_also: #GVariantType, #GVariant
* GVariantType:
*
* This section introduces the GVariant type system. It is based, in
* A type in the [type@GLib.Variant] type system.
*
* This section introduces the [type@GLib.Variant] type system. It is based, in
* large part, on the D-Bus type system, with two major changes and
* some minor lifting of restrictions. The
* [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
* therefore, provides a significant amount of
* information that is useful when working with GVariant.
* information that is useful when working with [type@GLib.Variant].
*
* The first major change with respect to the D-Bus type system is the
* introduction of maybe (or "nullable") types. Any type in GVariant can be
* converted to a maybe type, in which case, "nothing" (or "null") becomes a
* valid value. Maybe types have been added by introducing the
* character "m" to type strings.
* introduction of maybe (or ‘nullable’) types. Any type in [type@GLib.Variant]
* can be converted to a maybe type, in which case, `nothing` (or `null`)
* becomes a valid value. Maybe types have been added by introducing the
* character `m` to type strings.
*
* The second major change is that the GVariant type system supports the
* concept of "indefinite types" -- types that are less specific than
* The second major change is that the [type@GLib.Variant] type system supports
* the concept of ‘indefinite types’ — types that are less specific than
* the normal types found in D-Bus. For example, it is possible to speak
* of "an array of any type" in GVariant, where the D-Bus type system
* would require you to speak of "an array of integers" or "an array of
* strings". Indefinite types have been added by introducing the
* characters "*", "?" and "r" to type strings.
* of ‘an array of any type’ in [type@GLib.Variant], where the D-Bus type system
* would require you to speak of ‘an array of integers’ or ‘an array of
* strings’. Indefinite types have been added by introducing the
* characters `*`, `?` and `r` to type strings.
*
* Finally, all arbitrary restrictions relating to the complexity of
* types are lifted along with the restriction that dictionary entries
* may only appear nested inside of arrays.
*
* Just as in D-Bus, GVariant types are described with strings ("type
* strings"). Subject to the differences mentioned above, these strings
* Just as in D-Bus, [type@GLib.Variant] types are described with strings (‘type
* strings’). Subject to the differences mentioned above, these strings
* are of the same form as those found in D-Bus. Note, however: D-Bus
* always works in terms of messages and therefore individual type
* strings appear nowhere in its interface. Instead, "signatures"
* strings appear nowhere in its interface. Instead, ‘signatures’
* are a concatenation of the strings of the type of each argument in a
* message. GVariant deals with single values directly so GVariant type
* strings always describe the type of exactly one value. This means
* that a D-Bus signature string is generally not a valid GVariant type
* string -- except in the case that it is the signature of a message
* containing exactly one argument.
* message. [type@GLib.Variant] deals with single values directly so
* [type@GLib.Variant] type strings always describe the type of exactly one
* value. This means that a D-Bus signature string is generally not a valid
* [type@GLib.Variant] type string — except in the case that it is the signature
* of a message containing exactly one argument.
*
* An indefinite type is similar in spirit to what may be called an
* abstract type in other type systems. No value can exist that has an
* indefinite type as its type, but values can exist that have types
* that are subtypes of indefinite types. That is to say,
* g_variant_get_type() will never return an indefinite type, but
* calling g_variant_is_of_type() with an indefinite type may return
* %TRUE. For example, you cannot have a value that represents "an
* array of no particular type", but you can have an "array of integers"
* which certainly matches the type of "an array of no particular type",
* since "array of integers" is a subtype of "array of no particular
* type".
* [method@GLib.Variant.get_type] will never return an indefinite type, but
* calling [method@GLib.Variant.is_of_type] with an indefinite type may return
* true. For example, you cannot have a value that represents ‘an
* array of no particular type’, but you can have an ‘array of integers’
* which certainly matches the type of ‘an array of no particular type’,
* since ‘array of integers’ is a subtype of ‘array of no particular
* type’.
*
* This is similar to how instances of abstract classes may not
* directly exist in other type systems, but instances of their
* non-abstract subtypes may. For example, in GTK, no object that has
* the type of #GtkBin can exist (since #GtkBin is an abstract class),
* but a #GtkWindow can certainly be instantiated, and you would say
* that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
* #GtkBin).
* the type of [class@Gtk.Widget] can exist (since [class@Gtk.Widget] is an
* abstract class), but a [class@Gtk.Window] can certainly be instantiated, and
* you would say that the [class@Gtk.Window] is a [class@Gtk.Widget] (since
* [class@Gtk.Window] is a subclass of [class@Gtk.Widget]).
*
* Two types may not be compared by value; use [method@GLib.VariantType.equal]
* or [method@GLib.VariantType.is_subtype_of] May be copied using
* [method@GLib.VariantType.copy] and freed using [method@GLib.VariantType.free].
*
* ## GVariant Type Strings
*
* A GVariant type string can be any of the following:
* A [type@GLib.Variant] type string can be any of the following:
*
* - any basic type string (listed below)
*
* - "v", "r" or "*"
*
* - one of the characters 'a' or 'm', followed by another type string
*
* - the character '(', followed by a concatenation of zero or more other
* type strings, followed by the character ')'
*
* - the character '{', followed by a basic type string (see below),
* followed by another type string, followed by the character '}'
* - `v`, `r` or `*`
* - one of the characters `a` or `m`, followed by another type string
* - the character `(`, followed by a concatenation of zero or more other
* type strings, followed by the character `)`
* - the character `{`, followed by a basic type string (see below),
* followed by another type string, followed by the character `}`
*
* A basic type string describes a basic type (as per
* g_variant_type_is_basic()) and is always a single character in length.
* The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
* "h", "d", "s", "o", "g" and "?".
* [method@GLib.VariantType.is_basic]) and is always a single character in
* length. The valid basic type strings are `b`, `y`, `n`, `q`, `i`, `u`, `x`,
* `t`, `h`, `d`, `s`, `o`, `g` and `?`.
*
* The above definition is recursive to arbitrary depth. "aaaaai" and
* "(ui(nq((y)))s)" are both valid type strings, as is
* "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant
* imposes a limit on recursion depth of 65 nested containers. This is the
* limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to
* be nested in a top-level tuple.
* The above definition is recursive to arbitrary depth. `aaaaai` and
* `(ui(nq((y)))s)` are both valid type strings, as is
* `a(aa(ui)(qna{ya(yd)}))`. In order to not hit memory limits,
* [type@GLib.Variant] imposes a limit on recursion depth of 65 nested
* containers. This is the limit in the D-Bus specification (64) plus one to
* allow a [class@Gio.DBusMessage] to be nested in a top-level tuple.
*
* The meaning of each of the characters is as follows:
* - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
* - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte.
* - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer.
* - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer.
* - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer.
* - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer.
* - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer.
* - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer.
* - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value
*
* - `b`: the type string of `G_VARIANT_TYPE_BOOLEAN`; a boolean value.
* - `y`: the type string of `G_VARIANT_TYPE_BYTE`; a byte.
* - `n`: the type string of `G_VARIANT_TYPE_INT16`; a signed 16 bit integer.
* - `q`: the type string of `G_VARIANT_TYPE_UINT16`; an unsigned 16 bit integer.
* - `i`: the type string of `G_VARIANT_TYPE_INT32`; a signed 32 bit integer.
* - `u`: the type string of `G_VARIANT_TYPE_UINT32`; an unsigned 32 bit integer.
* - `x`: the type string of `G_VARIANT_TYPE_INT64`; a signed 64 bit integer.
* - `t`: the type string of `G_VARIANT_TYPE_UINT64`; an unsigned 64 bit integer.
* - `h`: the type string of `G_VARIANT_TYPE_HANDLE`; a signed 32 bit value
* that, by convention, is used as an index into an array of file
* descriptors that are sent alongside a D-Bus message.
* - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
* - `d`: the type string of `G_VARIANT_TYPE_DOUBLE`; a double precision
* floating point value.
* - `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
* - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
* - `s`: the type string of `G_VARIANT_TYPE_STRING`; a string.
* - `o`: the type string of `G_VARIANT_TYPE_OBJECT_PATH`; a string in the form
* of a D-Bus object path.
* - `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of
* - `g`: the type string of `G_VARIANT_TYPE_SIGNATURE`; a string in the form of
* a D-Bus type signature.
* - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
* - `?`: the type string of `G_VARIANT_TYPE_BASIC`; an indefinite type that
* is a supertype of any of the basic types.
* - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that
* - `v`: the type string of `G_VARIANT_TYPE_VARIANT`; a container type that
* contain any other type of value.
* - `a`: used as a prefix on another type string to mean an array of that
* type; the type string "ai", for example, is the type of an array of
* type; the type string `ai`, for example, is the type of an array of
* signed 32-bit integers.
* - `m`: used as a prefix on another type string to mean a "maybe", or
* "nullable", version of that type; the type string "ms", for example,
* - `m`: used as a prefix on another type string to mean a ‘maybe’, or
* ‘nullable’, version of that type; the type string `ms`, for example,
* is the type of a value that maybe contains a string, or maybe contains
* nothing.
* - `()`: used to enclose zero or more other concatenated type strings to
* create a tuple type; the type string "(is)", for example, is the type of
* create a tuple type; the type string `(is)`, for example, is the type of
* a pair of an integer and a string.
* - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is
* - `r`: the type string of `G_VARIANT_TYPE_TUPLE`; an indefinite type that is
* a supertype of any tuple type, regardless of the number of items.
* - `{}`: used to enclose a basic type string concatenated with another type
* string to create a dictionary entry type, which usually appears inside of
* an array to form a dictionary; the type string "a{sd}", for example, is
* an array to form a dictionary; the type string `a{sd}`, for example, is
* the type of a dictionary that maps strings to double precision floating
* point values.
*
* The first type (the basic type) is the key type and the second type is
* the value type. The reason that the first type is restricted to being a
* basic type is so that it can easily be hashed.
* - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is
* - `*`: the type string of `G_VARIANT_TYPE_ANY`; the indefinite type that is
* a supertype of all types. Note that, as with all type strings, this
* character represents exactly one type. It cannot be used inside of tuples
* to mean "any number of items".
* to mean ‘any number of items’.
*
* Any type string of a container that contains an indefinite type is,
* itself, an indefinite type. For example, the type string "a*"
* (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
* that is a supertype of every array type. "(*s)" is a supertype
* itself, an indefinite type. For example, the type string `a*`
* (corresponding to `G_VARIANT_TYPE_ARRAY`) is an indefinite type
* that is a supertype of every array type. `(*s)` is a supertype
* of all tuples that contain exactly two items where the second
* item is a string.
*
* "a{?*}" is an indefinite type that is a supertype of all arrays
* `a{?*}` is an indefinite type that is a supertype of all arrays
* containing dictionary entries where the key is any basic type and
* the value is any type at all. This is, by definition, a dictionary,
* so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
* so this type string corresponds to `G_VARIANT_TYPE_DICTIONARY`. Note
* that, due to the restriction that the key of a dictionary entry must
* be a basic type, "{**}" is not a valid type string.
* be a basic type, `{**}` is not a valid type string.
*
* Since: 2.24
*/

9
glib/gvarianttype.h
View File

@ -31,15 +31,6 @@
G_BEGIN_DECLS
/**
* GVariantType:
*
* A type in the GVariant type system.
*
* Two types may not be compared by value; use g_variant_type_equal() or
* g_variant_type_is_subtype_of(). May be copied using
* g_variant_type_copy() and freed using g_variant_type_free().
**/
typedef struct _GVariantType GVariantType;
/**

22
glib/gversion.c
View File

@ -28,28 +28,6 @@
#include "gversion.h"
/**
* SECTION:version
* @Title: Version Information
* @Short_description: variables and functions to check the GLib version
*
* GLib provides version information, primarily useful in configure
* checks for builds that have a configure script. Applications will
* not typically use the features described here.
*
* The GLib headers annotate deprecated APIs in a way that produces
* compiler warnings if these deprecated APIs are used. The warnings
* can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS
* before including the glib.h header.
*
* GLib also provides support for building applications against
* defined subsets of deprecated or new GLib APIs. Define the macro
* %GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib
* you want to receive warnings about deprecated APIs. Define the
* macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of
* GLib whose API you want to use.
*/
/**
* glib_major_version:
*