[glibmm] Regenerated docs XML
- From: Murray Cumming <murrayc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glibmm] Regenerated docs XML
- Date: Wed, 26 Feb 2014 13:12:20 +0000 (UTC)
commit e5fcac653822cbeba113a54e78e8e8f3fa318d56
Author: Murray Cumming <murrayc murrayc com>
Date: Wed Feb 26 13:35:07 2014 +0100
Regenerated docs XML
gio/src/gio_docs.xml | 2309 ++++++++++++-----------
glib/src/glib_docs.xml | 5096 ++++++++++++++++++++++++-----------------------
2 files changed, 3797 insertions(+), 3608 deletions(-)
---
diff --git a/gio/src/gio_docs.xml b/gio/src/gio_docs.xml
index 56933d9..281e8ee 100644
--- a/gio/src/gio_docs.xml
+++ b/gio/src/gio_docs.xml
@@ -1495,6 +1495,71 @@ process. See g_application_command_line_set_exit_status().
</return>
</signal>
+<signal name="GApplication::handle-local-options">
+<description>
+The ::handle-local-options signal is emitted on the local instance
+after the parsing of the commandline options has occurred.
+
+You can add options to be recognised during commandline option
+parsing using g_application_add_main_option_entries() and
+g_application_add_option_group().
+
+Signal handlers can inspect @options (along with values pointed to
+from the @arg_data of an installed #GOptionEntrys) in order to
+decide to perform certain actions, including direct local handling
+(which may be useful for options like --version).
+
+If the options have been "handled" then a non-negative value should
+be returned. In this case, the return value is the exit status: 0
+for success and a positive value for failure. -1 means to continue
+normal processing.
+
+In the event that the application is marked
+%G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
+send the @option dictionary to the primary instance where it can be
+read with g_application_command_line_get_options(). The signal
+handler can modify the dictionary before returning, and the
+modified dictionary will be sent.
+
+In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set,
+"normal processing" will treat the remaining uncollected command
+line arguments as filenames or URIs. If there are no arguments,
+the application is activated by g_application_activate(). One or
+more arguments results in a call to g_application_open().
+
+If you want to handle the local commandline arguments for yourself
+by converting them to calls to g_application_open() or
+g_action_group_activate_action() then you must be sure to register
+the application first. You should probably not call
+g_application_activate() for yourself, however: just return -1 and
+allow the default handler to do it for you. This will ensure that
+the `--gapplication-service` switch works properly (i.e. no activation
+in that case).
+
+Note that this signal is emitted from the default implementation of
+local_command_line(). If you override that function and don't
+chain up then this signal will never be emitted.
+
+You can override local_command_line() if you need more powerful
+capabilities than what is provided here, but this should not
+normally be required.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the application
+</parameter_description>
+</parameter>
+<parameter name="options">
+<parameter_description> the options dictionary
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</signal>
+
<signal name="GApplication::open">
<description>
The ::open signal is emitted on the primary instance when there are
@@ -1727,16 +1792,14 @@ thread that is running the operation.
Note that disconnecting from this signal (or any signal) in a
multi-threaded program is prone to race conditions. For instance
-it is possible that a signal handler may be invoked even
-<emphasis>after</emphasis> a call to
-g_signal_handler_disconnect() for that handler has already
-returned.
+it is possible that a signal handler may be invoked even after
+a call to g_signal_handler_disconnect() for that handler has
+already returned.
-There is also a problem when cancellation happen
-right before connecting to the signal. If this happens the
-signal will unexpectedly not be emitted, and checking before
-connecting to the signal leaves a race condition where this is
-still happening.
+There is also a problem when cancellation happens right before
+connecting to the signal. If this happens the signal will
+unexpectedly not be emitted, and checking before connecting to
+the signal leaves a race condition where this is still happening.
In order to make it safe and easy to connect handlers there
are two helper functions: g_cancellable_connect() and
@@ -1744,13 +1807,13 @@ g_cancellable_disconnect() which protect against problems
like this.
An example of how to us this:
-|[
-/<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
+|[<!-- language="C" -->
+// Make sure we don't do unnecessary work if already cancelled
if (g_cancellable_set_error_if_cancelled (cancellable, error))
return;
-/<!-- -->* Set up all the data needed to be able to
-* handle cancellation of the operation *<!-- -->/
+// Set up all the data needed to be able to handle cancellation
+// of the operation
my_data = my_data_new (...);
id = 0;
@@ -1759,12 +1822,12 @@ id = g_cancellable_connect (cancellable,
G_CALLBACK (cancelled_handler)
data, NULL);
-/<!-- -->* cancellable operation here... *<!-- -->/
+// cancellable operation here...
g_cancellable_disconnect (cancellable, id);
-/<!-- -->* cancelled_handler is never called after this, it
-* is now safe to free the data *<!-- -->/
+// cancelled_handler is never called after this, it is now safe
+// to free the data
my_data_free (my_data);
]|
@@ -1876,7 +1939,7 @@ Since: 2.34
</parameter_description>
</parameter>
<parameter name="mechanism">
-<parameter_description> The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
+<parameter_description> The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
</parameter_description>
</parameter>
</parameters>
@@ -1958,21 +2021,15 @@ supports exchanging UNIX file descriptors with the remote peer.
Emitted when the connection is closed.
The cause of this event can be
-<itemizedlist>
-<listitem><para>
-If g_dbus_connection_close() is called. In this case
+
+- If g_dbus_connection_close() is called. In this case
@remote_peer_vanished is set to %FALSE and @error is %NULL.
-</para></listitem>
-<listitem><para>
-If the remote peer closes the connection. In this case
+
+- If the remote peer closes the connection. In this case
@remote_peer_vanished is set to %TRUE and @error is set.
-</para></listitem>
-<listitem><para>
-If the remote peer sends invalid or malformed data. In this
-case @remote_peer_vanished is set to %FALSE and @error
-is set.
-</para></listitem>
-</itemizedlist>
+
+- If the remote peer sends invalid or malformed data. In this
+case @remote_peer_vanished is set to %FALSE and @error is set.
Upon receiving this signal, you should give up your reference to
@connection. You are guaranteed that this signal is emitted only
@@ -1983,16 +2040,16 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> The #GDBusConnection emitting the signal.
+<parameter_description> the #GDBusConnection emitting the signal
</parameter_description>
</parameter>
<parameter name="remote_peer_vanished">
<parameter_description> %TRUE if @connection is closed because the
-remote peer closed its end of the connection.
+remote peer closed its end of the connection
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> A #GError with more details about the event or %NULL.
+<parameter_description> a #GError with more details about the event or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -2271,11 +2328,11 @@ determine if the method call is authorized.
Note that this signal is emitted in a thread dedicated to
handling the method call so handlers are allowed to perform
-blocking IO. This means that it is appropriate to call
-e.g. <ulink
-url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</ulink>
-with the <ulink
-url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS">POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION</ulink>
flag set.
+blocking IO. This means that it is appropriate to call e.g.
+[polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync)
+with the
+[POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS)
+flag set.
If %FALSE is returned then no further handlers are run and the
signal handler must take a reference to @invocation and finish
@@ -2610,7 +2667,7 @@ This signal exists purely as a convenience to avoid having to
connect signals to all interface proxies managed by @manager.
This signal is emitted in the
-<link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+[thread-default main context][g-main-context-push-thread-default]
that @manager was constructed in.
Since: 2.30
@@ -2649,7 +2706,7 @@ This signal exists purely as a convenience to avoid having to
connect signals to all interface proxies managed by @manager.
This signal is emitted in the
-<link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+[thread-default main context][g-main-context-push-thread-default]
that @manager was constructed in.
Since: 2.30
@@ -2711,9 +2768,9 @@ be used in managers for well-known names.
Emitted when a method is invoked by a remote caller and used to
determine if the method call is authorized.
-This signal is like #GDBusInterfaceSkeleton<!-- -->'s
-#GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
-for the enclosing object.
+This signal is like #GDBusInterfaceSkeleton's
+#GDBusInterfaceSkeleton::g-authorize-method signal,
+except that it is for the enclosing object.
The default class handler just returns %TRUE.
@@ -2774,8 +2831,8 @@ If the proxy has the flag
@invalidated_properties will always be empty.
This signal corresponds to the
-<literal>PropertiesChanged</literal> D-Bus signal on the
-<literal>org.freedesktop.DBus.Properties</literal> interface.
+`PropertiesChanged` D-Bus signal on the
+`org.freedesktop.DBus.Properties` interface.
Since: 2.26
@@ -2901,9 +2958,9 @@ the #GDBusConnection::closed signal.
If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD
then the signal is emitted in a new thread dedicated to the
-connection. Otherwise the signal is emitted in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread that @server was constructed in.
+connection. Otherwise the signal is emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that @server was constructed in.
You are guaranteed that signal handlers for this signal runs
before incoming messages on @connection are processed. This means
@@ -4410,7 +4467,7 @@ for each affected key. If any other connected handler returns
</parameter>
<parameter name="keys">
<parameter_description>
-an array of #GQuark<!-- -->s for the changed keys, or %NULL
+an array of #GQuarks for the changed keys, or %NULL
</parameter_description>
</parameter>
<parameter name="n_keys">
@@ -4556,6 +4613,14 @@ Indicates that the action was just activated.
@parameter will always be of the expected type. In the event that
an incorrect type was given, no signal will be emitted.
+Since GLib 2.40, if no handler is connected to this signal then the
+default behaviour for boolean-stated actions with a %NULL parameter
+type is to toggle them via the #GSimpleAction::change-state signal.
+For stateful actions where the state type is equal to the parameter
+type, the default is to forward them directly to
+#GSimpleAction::change-state. This should allow almost all users
+of #GSimpleAction to connect only one handler or the other.
+
Since: 2.28
</description>
@@ -4582,13 +4647,12 @@ an incorrect type was given, no signal will be emitted.
If no handler is connected to this signal then the default
behaviour is to call g_simple_action_set_state() to set the state
-to the requested value. If you connect a signal handler then no
-default action is taken. If the state should change then you must
+to the requested value. If you connect a signal handler then no
+default action is taken. If the state should change then you must
call g_simple_action_set_state() from the handler.
-<example>
-<title>Example 'change-state' handler</title>
-<programlisting>
+An example of a 'change-state' handler:
+|[<!-- language="C" -->
static void
change_volume_state (GSimpleAction *action,
GVariant *value,
@@ -4602,11 +4666,10 @@ requested = g_variant_get_int32 (value);
if (0 <= requested && requested <= 10)
g_simple_action_set_state (action, value);
}
-</programlisting>
-</example>
+]|
-The handler need not set the state to the requested value. It
-could set it to any value at all, or take some other action.
+The handler need not set the state to the requested value.
+It could set it to any value at all, or take some other action.
Since: 2.30
@@ -4631,80 +4694,40 @@ Among other things, this can be used to provide progress
information about a network connection in the UI. The meanings of
the different @event values are as follows:
-<variablelist>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_RESOLVING:</term>
-<listitem><para>
- client is about to look up @connectable in DNS.
- connection will be %NULL.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_RESOLVED:</term>
-<listitem><para>
- client has successfully resolved @connectable in DNS.
- connection will be %NULL.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_CONNECTING:</term>
-<listitem><para>
- client is about to make a connection to a remote host;
-either a proxy server or the destination server itself.
- connection is the #GSocketConnection, which is not yet
+- %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
+in DNS. @connection will be %NULL.
+
+- %G_SOCKET_CLIENT_RESOLVED: @client has successfully resolved
+ connectable in DNS. @connection will be %NULL.
+
+- %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
+to a remote host; either a proxy server or the destination server
+itself. @connection is the #GSocketConnection, which is not yet
connected. Since GLib 2.40, you can access the remote
address via g_socket_connection_get_remote_address().
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_CONNECTED:</term>
-<listitem><para>
- client has successfully connected to a remote host.
- connection is the connected #GSocketConnection.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
-<listitem><para>
- client is about to negotiate with a proxy to get it to
-connect to @connectable. @connection is the
-#GSocketConnection to the proxy server.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
-<listitem><para>
- client has negotiated a connection to @connectable through
-a proxy server. @connection is the stream returned from
-g_proxy_connect(), which may or may not be a
-#GSocketConnection.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
-<listitem><para>
- client is about to begin a TLS handshake. @connection is a
-#GTlsClientConnection.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
-<listitem><para>
- client has successfully completed the TLS handshake.
- connection is a #GTlsClientConnection.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>%G_SOCKET_CLIENT_COMPLETE:</term>
-<listitem><para>
- client has either successfully connected to @connectable
-(in which case @connection is the #GSocketConnection that
-it will be returning to the caller) or has failed (in which
-case @connection is %NULL and the client is about to return
-an error).
-</para></listitem>
-</varlistentry>
-</variablelist>
+
+- %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
+to a remote host. @connection is the connected #GSocketConnection.
+
+- %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
+with a proxy to get it to connect to @connectable. @connection is
+the #GSocketConnection to the proxy server.
+
+- %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
+connection to @connectable through a proxy server. @connection is
+the stream returned from g_proxy_connect(), which may or may not
+be a #GSocketConnection.
+
+- %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
+handshake. @connection is a #GTlsClientConnection.
+
+- %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
+the TLS handshake. @connection is a #GTlsClientConnection.
+
+- %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
+to @connectable (in which case @connection is the #GSocketConnection
+that it will be returning to the caller) or has failed (in which
+case @connection is %NULL and the client is about to return an error).
Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
multiple times (or not at all) for a given connectable (in
@@ -4971,7 +4994,7 @@ Note that it is a programmer error to mix 'incompatible' flags. For
example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
%G_SUBPROCESS_FLAGS_STDOUT_SILENCE.
-Since: 2.36
+Since: 2.40
</description>
<parameters>
@@ -20032,9 +20055,7 @@ and adding them to a #GActionMap.
Each action is constructed as per one #GActionEntry.
-<example>
-<title>Using g_action_map_add_action_entries()</title>
-<programlisting>
+|[<!-- language="C" -->
static void
activate_quit (GSimpleAction *simple,
GVariant *parameter,
@@ -20065,8 +20086,7 @@ g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (en
return G_ACTION_GROUP (group);
}
-</programlisting>
-</example>
+]|
Since: 2.32
@@ -20314,8 +20334,8 @@ content types from a given @appinfo, %FALSE if not.
Creates a new #GAppInfo from the given information.
Note that for @commandline, the quoting rules of the Exec key of the
-<ulink url="http://freedesktop.org/Standards/desktop-entry-spec">freedesktop.org Desktop
-Entry Specification</ulink> are applied. For example, if the @commandline contains
+[freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
+are applied. For example, if the @commandline contains
percent-encoded URIs, the percent-character must be doubled in order to prevent it from
being swallowed by Exec key unquoting. See the specification for exact quoting rules.
@@ -20348,8 +20368,8 @@ being swallowed by Exec key unquoting. See the specification for exact quoting r
Tries to delete a #GAppInfo.
On some platforms, there may be a difference between user-defined
-#GAppInfo<!-- -->s which can be deleted, and system-wide ones which
-cannot. See g_app_info_can_delete().
+#GAppInfos which can be deleted, and system-wide ones which cannot.
+See g_app_info_can_delete().
Virtual: do_delete
Since: 2.20
@@ -20384,7 +20404,7 @@ Creates a duplicate of a #GAppInfo.
<function name="g_app_info_equal">
<description>
-Checks if two #GAppInfo<!-- -->s are equal.
+Checks if two #GAppInfos are equal.
</description>
@@ -20408,17 +20428,16 @@ Gets a list of all of the applications currently registered
on this system.
For desktop files, this includes applications that have
-<literal>NoDisplay=true</literal> set or are excluded from
-display by means of <literal>OnlyShowIn</literal> or
-<literal>NotShowIn</literal>. See g_app_info_should_show().
+`NoDisplay=true` set or are excluded from display by means
+of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
The returned list does not include applications which have
-the <literal>Hidden</literal> key set.
+the `Hidden` key set.
</description>
<parameters>
</parameters>
-<return> a newly allocated #GList of references to #GAppInfo<!---->s.
+<return> a newly allocated #GList of references to #GAppInfos.
</return>
</function>
@@ -20700,17 +20719,16 @@ a textual URI you want to pass in as argument, consider using
g_app_info_launch_uris() instead.
The launched application inherits the environment of the launching
-process, but it can be modified with g_app_launch_context_setenv() and
-g_app_launch_context_unsetenv().
+process, but it can be modified with g_app_launch_context_setenv()
+and g_app_launch_context_unsetenv().
-On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
+On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
environment variable with the path of the launched desktop file and
-<envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
-id of the launched process. This can be used to ignore
-<envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
-by further processes. The <envar>DISPLAY</envar> and
-<envar>DESKTOP_STARTUP_ID</envar> environment variables are also
-set, based on information provided in @launch_context.
+`GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+should it be inherited by further processes. The `DISPLAY` and
+`DESKTOP_STARTUP_ID` environment variables are also set, based
+on information provided in @launch_context.
</description>
@@ -20994,7 +21012,7 @@ Checks if the application supports reading files and directories from URIs.
<description>
Gets the display string for the @context. This is used to ensure new
applications are started on the same display as the launching
-application, by setting the <envar>DISPLAY</envar> environment variable.
+application, by setting the `DISPLAY` environment variable.
</description>
@@ -21021,7 +21039,7 @@ application, by setting the <envar>DISPLAY</envar> environment varia
Gets the complete environment variable list to be passed to
the child process when @context is used to launch an application.
This is a %NULL-terminated array of strings, where each string has
-the form <literal>KEY=VALUE</literal>.
+the form `KEY=VALUE`.
Since: 2.32
@@ -21041,12 +21059,10 @@ child's environment
<function name="g_app_launch_context_get_startup_notify_id">
<description>
Initiates startup notification for the application and returns the
-<envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
-if supported.
+`DESKTOP_STARTUP_ID` for the launched operation, if supported.
-Startup notification IDs are defined in the <ulink
-url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
-FreeDesktop.Org Startup Notifications standard</ulink>.
+Startup notification IDs are defined in the
+[FreeDesktop.Org Startup Notifications
standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
</description>
@@ -21169,6 +21185,113 @@ Since: 2.28
<return></return>
</function>
+<function name="g_application_add_main_option_entries">
+<description>
+Adds main option entries to be handled by @application.
+
+This function is comparable to g_option_context_add_main_entries().
+
+After the commandline arguments are parsed, the
+#GApplication::handle-local-options signal will be emitted. At this
+point, the application can inspect the values pointed to by @arg_data
+in the given #GOptionEntrys.
+
+Unlike #GOptionContext, #GApplication supports giving a %NULL
+ arg_data for a non-callback #GOptionEntry. This results in the
+argument in question being packed into a #GVariantDict which is also
+passed to #GApplication::handle-local-options, where it can be
+inspected and modified. If %G_APPLICATION_HANDLES_COMMAND_LINE is
+set, then the resulting dictionary is sent to the primary instance,
+where g_application_command_line_get_options_dict() will return it.
+This "packing" is done according to the type of the argument --
+booleans for normal flags, strings for strings, bytestrings for
+filenames, etc. The packing only occurs if the flag is given (ie: we
+do not pack a "false" #GVariant in the case that a flag is missing).
+
+In general, it is recommended that all commandline arguments are
+parsed locally. The options dictionary should then be used to
+transmit the result of the parsing to the primary instance, where
+g_variant_dict_lookup() can be used. For local options, it is
+possible to either use @arg_data in the usual way, or to consult (and
+potentially remove) the option from the options dictionary.
+
+This function is new in GLib 2.40. Before then, the only real choice
+was to send all of the commandline arguments (options and all) to the
+primary instance for handling. #GApplication ignored them completely
+on the local side. Calling this function "opts in" to the new
+behaviour, and in particular, means that unrecognised options will be
+treated as errors. Unrecognised options have never been ignored when
+%G_APPLICATION_HANDLES_COMMAND_LINE is unset.
+
+If #GApplication::handle-local-options needs to see the list of
+filenames, then the use of %G_OPTION_REMAINING is recommended. If
+ arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
+the options dictionary. If you do use %G_OPTION_REMAINING then you
+need to handle these arguments for yourself because once they are
+consumed, they will no longer be visible to the default handling
+(which treats them as filenames to be opened).
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> a #GApplication
+</parameter_description>
+</parameter>
+<parameter name="entries">
+<parameter_description> (array zero-terminated=1) (element-type GOptionEntry) a
+%NULL-terminated list of #GOptionEntrys
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_application_add_option_group">
+<description>
+Adds a #GOptionGroup to the commandline handling of @application.
+
+This function is comparable to g_option_context_add_group().
+
+Unlike g_application_add_main_option_entries(), this function does
+not deal with %NULL @arg_data and never transmits options to the
+primary instance.
+
+The reason for that is because, by the time the options arrive at the
+primary instance, it is typically too late to do anything with them.
+Taking the GTK option group as an example: GTK will already have been
+initialised by the time the #GApplication::command-line handler runs.
+In the case that this is not the first-running instance of the
+application, the existing instance may already have been running for
+a very long time.
+
+This means that the options from #GOptionGroup are only really usable
+in the case that the instance of the application being run is the
+first instance. Passing options like `--display=` or `--gdk-debug=`
+on future runs will have no effect on the existing primary instance.
+
+Calling this function will cause the options in the supplied option
+group to be parsed, but it does not cause you to be "opted in" to the
+new functionality whereby unrecognised options are rejected even if
+%G_APPLICATION_HANDLES_COMMAND_LINE was given.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="group">
+<parameter_description> a #GOptionGroup
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
<function name="g_application_command_line_create_file_for_arg">
<description>
Creates a #GFile corresponding to a filename that was given as part
@@ -21200,7 +21323,12 @@ Since: 2.36
<description>
Gets the list of arguments that was passed on the command line.
-The strings in the array may contain non-utf8 data.
+The strings in the array may contain non-UTF-8 data on UNIX (such as
+filenames or arguments given in the system locale) but are always in
+UTF-8 on Windows.
+
+If you wish to use the return value with #GOptionContext, you must
+use g_option_context_parse_strv().
The return value is %NULL-terminated and should be freed using
g_strfreev().
@@ -21319,6 +21447,32 @@ Since: 2.28
</return>
</function>
+<function name="g_application_command_line_get_options_dict">
+<description>
+Gets the options there were passed to g_application_command_line().
+
+If you did not override local_command_line() then these are the same
+options that were parsed according to the #GOptionEntrys added to the
+application with g_application_add_main_option_entries() and possibly
+modified from your GApplication::handle-local-options handler.
+
+If no options were sent then an empty dictionary is returned so that
+you don't need to check for %NULL.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="cmdline">
+<parameter_description> a #GApplicationCommandLine
+</parameter_description>
+</parameter>
+</parameters>
+<return> a #GVariantDict with the options
+
+</return>
+</function>
+
<function name="g_application_command_line_get_platform_data">
<description>
Gets the platform data associated with the invocation of @cmdline.
@@ -21718,13 +21872,20 @@ g_application_set_application_id().
For convenience, the restrictions on application identifiers are
reproduced here:
-<itemizedlist>
-<listitem>Application identifiers must contain only the ASCII characters
"[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
-<listitem>Application identifiers must contain at least one '.' (period) character (and thus at least
three elements).</listitem>
-<listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
-<listitem>Application identifiers must not contain consecutive '.' (period)
characters.</listitem>
-<listitem>Application identifiers must not exceed 255 characters.</listitem>
-</itemizedlist>
+
+- Application identifiers must contain only the ASCII characters
+"[A-Z][a-z][0-9]_-." and must not begin with a digit.
+
+- Application identifiers must contain at least one '.' (period)
+character (and thus at least three elements).
+
+- Application identifiers must not begin or end with a '.' (period)
+character.
+
+- Application identifiers must not contain consecutive '.' (period)
+characters.
+
+- Application identifiers must not exceed 255 characters.
</description>
@@ -21936,57 +22097,40 @@ This function is intended to be run from main() and its return value
is intended to be returned by main(). Although you are expected to pass
the @argc, @argv parameters from main() to this function, it is possible
to pass %NULL if @argv is not available or commandline handling is not
-required.
-
-First, the local_command_line() virtual function is invoked.
-This function always runs on the local instance. It gets passed a pointer
-to a %NULL-terminated copy of @argv and is expected to remove the arguments
-that it handled (shifting up remaining arguments). See
-<xref linkend="gapplication-example-cmdline2"/> for an example of
-parsing @argv manually. Alternatively, you may use the #GOptionContext API,
-after setting <literal>argc = g_strv_length (argv);</literal>.
-
-The last argument to local_command_line() is a pointer to the @status
-variable which can used to set the exit status that is returned from
-g_application_run().
-
-If local_command_line() returns %TRUE, the command line is expected
-to be completely handled, including possibly registering as the primary
-instance, calling g_application_activate() or g_application_open(), etc.
-
-If local_command_line() returns %FALSE then the application is registered
-and the #GApplication::command-line signal is emitted in the primary
-instance (which may or may not be this instance). The signal handler
-gets passed a #GApplicationCommandLine object that (among other things)
-contains the remaining commandline arguments that have not been handled
-by local_command_line().
-
-If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
-flag set then the default implementation of local_command_line()
-always returns %FALSE immediately, resulting in the commandline
-always being handled in the primary instance.
-
-Otherwise, the default implementation of local_command_line() tries
-to do a couple of things that are probably reasonable for most
-applications. First, g_application_register() is called to attempt
-to register the application. If that works, then the command line
-arguments are inspected. If no commandline arguments are given, then
-g_application_activate() is called. If commandline arguments are
-given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
-are assumed to be filenames and g_application_open() is called.
-
-If you need to handle commandline arguments that are not filenames,
-and you don't mind commandline handling to happen in the primary
-instance, you should set %G_APPLICATION_HANDLES_COMMAND_LINE and
-process the commandline arguments in your #GApplication::command-line
-signal handler, either manually or using the #GOptionContext API.
+required. Note that on Windows, @argc and @argv are ignored, and
+g_win32_get_command_line() is called internally (for proper support
+of Unicode commandline arguments).
+
+#GApplication will attempt to parse the commandline arguments. You
+can add commandline flags to the list of recognised options by way of
+g_application_add_main_option_entries(). After this, the
+#GApplication::handle-local-options signal is emitted, from which the
+application can inspect the values of its #GOptionEntrys.
+
+#GApplication::handle-local-options is a good place to handle options
+such as `--version`, where an immediate reply from the local process is
+desired (instead of communicating with an already-running instance).
+A #GApplication::handle-local-options handler can stop further processing
+by returning a non-negative value, which then becomes the exit status of
+the process.
+
+What happens next depends on the flags: if
+%G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
+commandline arguments are sent to the primary instance, where a
+#GApplication::command-line signal is emitted. Otherwise, the
+remaining commandline arguments are assumed to be a list of files.
+If there are no files listed, the application is activated via the
+#GApplication::activate signal. If there are one or more files, and
+%G_APPLICATION_HANDLES_OPEN was specified then the files are opened
+via the #GApplication::open signal.
If you are interested in doing more complicated local handling of the
commandline then you should implement your own #GApplication subclass
and override local_command_line(). In this case, you most likely want
to return %TRUE from your local_command_line() implementation to
suppress the default handling. See
-<xref linkend="gapplication-example-cmdline2"/> for an example.
+[gapplication-example-cmdline2.c][gapplication-example-cmdline2]
+for an example.
If, after the above is done, the use count of the application is zero
then the exit status is returned immediately. If the use count is
@@ -22320,8 +22464,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the operation.
+<parameter_description> the [I/O priority][io-priority] of the operation
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -22387,8 +22530,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the operation.
+<parameter_description> the [I/O priority][io-priority] of the operation
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -22474,8 +22616,7 @@ the value, and other property value pairs, and ended by %NULL.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the operation.
+<parameter_description> the [I/O priority][io-priority] of the operation
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -22521,8 +22662,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the operation.
+<parameter_description> the [I/O priority][io-priority] of the operation
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -22605,13 +22745,12 @@ If @res is a #GSimpleAsyncResult, this is equivalent to
g_simple_async_result_propagate_error(). Otherwise it returns
%FALSE.
-This can be used for legacy error handling in async
-<literal>_finish ()</literal> wrapper functions that traditionally
-handled #GSimpleAsyncResult error returns themselves rather than
-calling into the virtual method. This should not be used in new
-code; #GAsyncResult errors that are set by virtual methods should
-also be extracted by virtual methods, to enable subclasses to chain
-up correctly.
+This can be used for legacy error handling in async *_finish()
+wrapper functions that traditionally handled #GSimpleAsyncResult
+error returns themselves rather than calling into the virtual method.
+This should not be used in new code; #GAsyncResult errors that are
+set by virtual methods should also be extracted by virtual methods,
+to enable subclasses to chain up correctly.
Since: 2.34
@@ -22704,8 +22843,7 @@ of bytes that are required to fill the buffer.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -23050,19 +23188,19 @@ Since: 2.26
</description>
<parameters>
<parameter name="bus_type">
-<parameter_description> A #GBusType.
+<parameter_description> a #GBusType
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is satisfied.
+<parameter_description> a #GAsyncReadyCallback to call when the request is satisfied
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> the data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -23087,15 +23225,17 @@ Since: 2.26
</description>
<parameters>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+to g_bus_get()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+<return> a #GDBusConnection or %NULL if @error is set.
+Free with g_object_unref().
</return>
</function>
@@ -23124,19 +23264,20 @@ Since: 2.26
</description>
<parameters>
<parameter name="bus_type">
-<parameter_description> A #GBusType.
+<parameter_description> a #GBusType
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+<return> a #GDBusConnection or %NULL if @error is set.
+Free with g_object_unref().
</return>
</function>
@@ -23145,33 +23286,32 @@ Since: 2.26
<description>
Starts acquiring @name on the bus specified by @bus_type and calls
@name_acquired_handler and @name_lost_handler when the name is
-acquired respectively lost. Callbacks will be invoked in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this function from.
+acquired respectively lost. Callbacks will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this function from.
You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
callbacks will be invoked after calling this function - there are three
possible cases:
-<itemizedlist>
-<listitem><para>
- name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
-</para></listitem>
-<listitem><para>
- bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
-</para></listitem>
-<listitem><para>
- bus_acquired_handler then @name_acquired_handler (if the name was obtained).
-</para></listitem>
-</itemizedlist>
+
+- @name_lost_handler with a %NULL connection (if a connection to the bus
+can't be made).
+
+- @bus_acquired_handler then @name_lost_handler (if the name can't be
+obtained)
+
+- @bus_acquired_handler then @name_acquired_handler (if the name was
+obtained).
+
When you are done owning the name, just call g_bus_unown_name()
with the owner id this function returns.
If the name is acquired or lost (for example another application
could acquire the name if you allow replacement or the application
-currently owning the name exits), the handlers are also invoked. If the
-#GDBusConnection that is used for attempting to own the name
-closes, then @name_lost_handler is invoked since it is no
-longer possible for other processes to access the process.
+currently owning the name exits), the handlers are also invoked.
+If the #GDBusConnection that is used for attempting to own the name
+closes, then @name_lost_handler is invoked since it is no longer
+possible for other processes to access the process.
You cannot use g_bus_own_name() several times for the same name (unless
interleaved with calls to g_bus_unown_name()) - only the first call
@@ -23190,7 +23330,7 @@ in @bus_acquired_handler since you are guaranteed that this will run
before @name is requested from the bus.
This behavior makes it very simple to write applications that wants
-to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
+to [own names][gdbus-owning-names] and export objects.
Simply register objects to be exported in @bus_acquired_handler and
unregister the objects (if any) in @name_lost_handler.
@@ -23199,39 +23339,39 @@ Since: 2.26
</description>
<parameters>
<parameter name="bus_type">
-<parameter_description> The type of bus to own a name on.
+<parameter_description> the type of bus to own a name on
</parameter_description>
</parameter>
<parameter name="name">
-<parameter_description> The well-known name to own.
+<parameter_description> the well-known name to own
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> A set of flags from the #GBusNameOwnerFlags enumeration.
+<parameter_description> a set of flags from the #GBusNameOwnerFlags enumeration
</parameter_description>
</parameter>
<parameter name="bus_acquired_handler">
-<parameter_description> Handler to invoke when connected to the bus of type @bus_type or %NULL.
+<parameter_description> handler to invoke when connected to the bus of type @bus_type or %NULL
</parameter_description>
</parameter>
<parameter name="name_acquired_handler">
-<parameter_description> Handler to invoke when @name is acquired or %NULL.
+<parameter_description> handler to invoke when @name is acquired or %NULL
</parameter_description>
</parameter>
<parameter name="name_lost_handler">
-<parameter_description> Handler to invoke when @name is lost or %NULL.
+<parameter_description> handler to invoke when @name is lost or %NULL
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> User data to pass to handlers.
+<parameter_description> user data to pass to handlers
</parameter_description>
</parameter>
<parameter name="user_data_free_func">
-<parameter_description> Function for freeing @user_data or %NULL.
+<parameter_description> function for freeing @user_data or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> An identifier (never 0) that an be used with
+<return> an identifier (never 0) that an be used with
g_bus_unown_name() to stop owning the name.
</return>
@@ -23247,73 +23387,73 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="name">
-<parameter_description> The well-known name to own.
+<parameter_description> the well-known name to own
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> A set of flags from the #GBusNameOwnerFlags enumeration.
+<parameter_description> a set of flags from the #GBusNameOwnerFlags enumeration
</parameter_description>
</parameter>
<parameter name="name_acquired_handler">
-<parameter_description> Handler to invoke when @name is acquired or %NULL.
+<parameter_description> handler to invoke when @name is acquired or %NULL
</parameter_description>
</parameter>
<parameter name="name_lost_handler">
-<parameter_description> Handler to invoke when @name is lost or %NULL.
+<parameter_description> handler to invoke when @name is lost or %NULL
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> User data to pass to handlers.
+<parameter_description> user data to pass to handlers
</parameter_description>
</parameter>
<parameter name="user_data_free_func">
-<parameter_description> Function for freeing @user_data or %NULL.
+<parameter_description> function for freeing @user_data or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> An identifier (never 0) that an be used with
-g_bus_unown_name() to stop owning the name.
+<return> an identifier (never 0) that an be used with
+g_bus_unown_name() to stop owning the name
</return>
</function>
<function name="g_bus_own_name_on_connection_with_closures">
<description>
-Version of g_bus_own_name_on_connection() using closures instead of callbacks for
-easier binding in other languages.
+Version of g_bus_own_name_on_connection() using closures instead of
+callbacks for easier binding in other languages.
Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="name">
-<parameter_description> The well-known name to own.
+<parameter_description> the well-known name to own
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> A set of flags from the #GBusNameOwnerFlags enumeration.
+<parameter_description> a set of flags from the #GBusNameOwnerFlags enumeration
</parameter_description>
</parameter>
<parameter name="name_acquired_closure">
<parameter_description> #GClosure to invoke when @name is
-acquired or %NULL.
+acquired or %NULL
</parameter_description>
</parameter>
<parameter name="name_lost_closure">
-<parameter_description> #GClosure to invoke when @name is lost or
-%NULL.
+<parameter_description> #GClosure to invoke when @name is lost
+or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> An identifier (never 0) that an be used with
+<return> an identifier (never 0) that an be used with
g_bus_unown_name() to stop owning the name.
</return>
@@ -23329,34 +23469,34 @@ Since: 2.26
</description>
<parameters>
<parameter name="bus_type">
-<parameter_description> The type of bus to own a name on.
+<parameter_description> the type of bus to own a name on
</parameter_description>
</parameter>
<parameter name="name">
-<parameter_description> The well-known name to own.
+<parameter_description> the well-known name to own
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> A set of flags from the #GBusNameOwnerFlags enumeration.
+<parameter_description> a set of flags from the #GBusNameOwnerFlags enumeration
</parameter_description>
</parameter>
<parameter name="bus_acquired_closure">
<parameter_description> #GClosure to invoke when connected to
-the bus of type @bus_type or %NULL.
+the bus of type @bus_type or %NULL
</parameter_description>
</parameter>
<parameter name="name_acquired_closure">
<parameter_description> #GClosure to invoke when @name is
-acquired or %NULL.
+acquired or %NULL
</parameter_description>
</parameter>
<parameter name="name_lost_closure">
<parameter_description> #GClosure to invoke when @name is lost or
-%NULL.
+%NULL
</parameter_description>
</parameter>
</parameters>
-<return> An identifier (never 0) that an be used with
+<return> an identifier (never 0) that an be used with
g_bus_unown_name() to stop owning the name.
</return>
@@ -23371,7 +23511,7 @@ Since: 2.26
</description>
<parameters>
<parameter name="owner_id">
-<parameter_description> An identifier obtained from g_bus_own_name()
+<parameter_description> an identifier obtained from g_bus_own_name()
</parameter_description>
</parameter>
</parameters>
@@ -23399,9 +23539,9 @@ Since: 2.26
Starts watching @name on the bus specified by @bus_type and calls
@name_appeared_handler and @name_vanished_handler when the name is
known to have a owner respectively known to lose its
-owner. Callbacks will be invoked in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this function from.
+owner. Callbacks will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this function from.
You are guaranteed that one of the handlers will be invoked after
calling this function. When you are done watching the name, just
@@ -23420,11 +23560,11 @@ is, if @name_appeared_handler is invoked then you are
guaranteed that the next time one of the handlers is invoked, it
will be @name_vanished_handler. The reverse is also true.
-This behavior makes it very simple to write applications that wants
-to take action when a certain name exists, see <xref
-linkend="gdbus-watching-names"/>. Basically, the application
-should create object proxies in @name_appeared_handler and destroy
-them again (if any) in @name_vanished_handler.
+This behavior makes it very simple to write applications that want
+to take action when a certain [name exists][gdbus-watching-names].
+Basically, the application should create object proxies in
+ name_appeared_handler and destroy them again (if any) in
+ name_vanished_handler
Since: 2.26
@@ -24131,7 +24271,8 @@ returned string with g_free()
<description>
Gets the generic icon name for a content type.
-See the <ulink
url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
specification for more on the generic icon name.
Since: 2.34
@@ -24243,7 +24384,8 @@ of content types, with the best guess coming first.
The types returned all have the form x-content/foo, e.g.
x-content/audio-cdda (for audio CDs) or x-content/image-dcf
-(for a camera memory card). See the <ulink
url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+(for a camera memory card). See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
specification for more on x-content types.
This function is useful in the implementation of
@@ -24307,15 +24449,14 @@ while on win32 it is "*".
<description>
Gets a list of strings containing all the registered content types
known to the system. The list and its data should be freed using
-<programlisting>
-g_list_free_full (list, g_free);
-</programlisting>
+g_list_free_full (list, g_free).
</description>
<parameters>
</parameters>
-<return> #GList of the registered content types
+<return> list of the registered
+content types
</return>
</function>
@@ -24977,8 +25118,7 @@ Since: 2.20
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -25278,8 +25418,7 @@ Since: 2.20
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -25338,8 +25477,8 @@ Reads a string from the data input stream, up to the first
occurrence of any of the stop characters.
In contrast to g_data_input_stream_read_until(), this function
-does <emphasis>not</emphasis> consume the stop character. You have
-to use g_data_input_stream_read_byte() to get it before calling
+does not consume the stop character. You have to use
+g_data_input_stream_read_byte() to get it before calling
g_data_input_stream_read_upto() again.
Note that @stop_chars may contain '\0' if @stop_chars_len is
@@ -25389,8 +25528,8 @@ The asynchronous version of g_data_input_stream_read_upto().
It is an error to have two outstanding calls to this function.
In contrast to g_data_input_stream_read_until(), this function
-does <emphasis>not</emphasis> consume the stop character. You have
-to use g_data_input_stream_read_byte() to get it before calling
+does not consume the stop character. You have to use
+g_data_input_stream_read_byte() to get it before calling
g_data_input_stream_read_upto() again.
Note that @stop_chars may contain '\0' if @stop_chars_len is
@@ -25418,8 +25557,7 @@ nul-terminated
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -25443,9 +25581,9 @@ of the request.
Finish an asynchronous call started by
g_data_input_stream_read_upto_async().
-Note that this function does <emphasis>not</emphasis> consume the
-stop character. You have to use g_data_input_stream_read_byte() to
-get it before calling g_data_input_stream_read_upto_async() again.
+Note that this function does not consume the stop character. You
+have to use g_data_input_stream_read_byte() to get it before calling
+g_data_input_stream_read_upto_async() again.
Since: 2.24
@@ -25836,10 +25974,10 @@ Since: 2.32
Escape @string so it can appear in a D-Bus address as the value
part of a key-value pair.
-For instance, if @string is <code>/run/bus-for-:0</code>,
-this function would return <code>/run/bus-for-%3A0</code>,
+For instance, if @string is "/run/bus-for-:0",
+this function would return "/run/bus-for-%3A0",
which could be used in a D-Bus address like
-<code>unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0</code>.
+"unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
Since: 2.36
@@ -25868,19 +26006,20 @@ Since: 2.26
</description>
<parameters>
<parameter name="bus_type">
-<parameter_description> A #GBusType.
+<parameter_description> a #GBusType
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A valid D-Bus address string for @bus_type or %NULL if @error is set.
+<return> a valid D-Bus address string for @bus_type or %NULL if
+ error is set
</return>
</function>
@@ -26094,7 +26233,7 @@ Since: 2.34
</parameter_description>
</parameter>
<parameter name="mechanism">
-<parameter_description> The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
+<parameter_description> The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
</parameter_description>
</parameter>
</parameters>
@@ -26171,25 +26310,25 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="filter_function">
-<parameter_description> A filter function.
+<parameter_description> a filter function
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> User data to pass to @filter_function.
+<parameter_description> user data to pass to @filter_function
</parameter_description>
</parameter>
<parameter name="user_data_free_func">
-<parameter_description> Function to free @user_data with when filter
-is removed or %NULL.
+<parameter_description> function to free @user_data with when filter
+is removed or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A filter identifier that can be used with
-g_dbus_connection_remove_filter().
+<return> a filter identifier that can be used with
+g_dbus_connection_remove_filter()
</return>
</function>
@@ -26212,7 +26351,7 @@ then any non-%NULL return value will be of this type.
If the @parameters #GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.:
-|[
+|[<!-- language="C" -->
g_dbus_connection_call (connection,
"org.freedesktop.StringThings",
"/org/freedesktop/StringThings",
@@ -26229,8 +26368,9 @@ NULL,
NULL);
]|
-This is an asynchronous method. When the operation is finished, @callback will be invoked
-in the <link linkend="g-main-context-push-thread-default">thread-default main
loop</link>
+This is an asynchronous method. When the operation is finished,
+ callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
of the thread you are calling this method from. You can then call
g_dbus_connection_call_finish() to get the result of the operation.
See g_dbus_connection_call_sync() for the synchronous version of this
@@ -26244,56 +26384,56 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="bus_name">
-<parameter_description> A unique or well-known bus name or %NULL if
- connection is not a message bus connection.
+<parameter_description> a unique or well-known bus name or %NULL if
+ connection is not a message bus connection
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> Path of remote object.
+<parameter_description> path of remote object
</parameter_description>
</parameter>
<parameter name="interface_name">
-<parameter_description> D-Bus interface to invoke method on.
+<parameter_description> D-Bus interface to invoke method on
</parameter_description>
</parameter>
<parameter name="method_name">
-<parameter_description> The name of the method to invoke.
+<parameter_description> the name of the method to invoke
</parameter_description>
</parameter>
<parameter name="parameters">
-<parameter_description> A #GVariant tuple with parameters for the method
-or %NULL if not passing parameters.
+<parameter_description> a #GVariant tuple with parameters for the method
+or %NULL if not passing parameters
</parameter_description>
</parameter>
<parameter name="reply_type">
-<parameter_description> The expected type of the reply, or %NULL.
+<parameter_description> the expected type of the reply, or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags from the #GDBusCallFlags enumeration.
+<parameter_description> flags from the #GDBusCallFlags enumeration
</parameter_description>
</parameter>
<parameter name="timeout_msec">
-<parameter_description> The timeout in milliseconds, -1 to use the default
-timeout or %G_MAXINT for no timeout.
+<parameter_description> the timeout in milliseconds, -1 to use the default
+timeout or %G_MAXINT for no timeout
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is
-satisfied or %NULL if you don't care about the result of the
-method invocation.
+<parameter_description> a #GAsyncReadyCallback to call when the request
+is satisfied or %NULL if you don't care about the result of the
+method invocation
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> the data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -26309,15 +26449,15 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_call().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_call()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -26346,7 +26486,7 @@ value will be of this type.
If the @parameters #GVariant is floating, it is consumed.
This allows convenient 'inline' use of g_variant_new(), e.g.:
-|[
+|[<!-- language="C" -->
g_dbus_connection_call_sync (connection,
"org.freedesktop.StringThings",
"/org/freedesktop/StringThings",
@@ -26371,50 +26511,50 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="bus_name">
-<parameter_description> A unique or well-known bus name or %NULL if
- connection is not a message bus connection.
+<parameter_description> a unique or well-known bus name or %NULL if
+ connection is not a message bus connection
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> Path of remote object.
+<parameter_description> path of remote object
</parameter_description>
</parameter>
<parameter name="interface_name">
-<parameter_description> D-Bus interface to invoke method on.
+<parameter_description> D-Bus interface to invoke method on
</parameter_description>
</parameter>
<parameter name="method_name">
-<parameter_description> The name of the method to invoke.
+<parameter_description> the name of the method to invoke
</parameter_description>
</parameter>
<parameter name="parameters">
-<parameter_description> A #GVariant tuple with parameters for the method
-or %NULL if not passing parameters.
+<parameter_description> a #GVariant tuple with parameters for the method
+or %NULL if not passing parameters
</parameter_description>
</parameter>
<parameter name="reply_type">
-<parameter_description> The expected type of the reply, or %NULL.
+<parameter_description> the expected type of the reply, or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags from the #GDBusCallFlags enumeration.
+<parameter_description> flags from the #GDBusCallFlags enumeration
</parameter_description>
</parameter>
<parameter name="timeout_msec">
-<parameter_description> The timeout in milliseconds, -1 to use the default
-timeout or %G_MAXINT for no timeout.
+<parameter_description> the timeout in milliseconds, -1 to use the default
+timeout or %G_MAXINT for no timeout
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -26435,56 +26575,56 @@ Since: 2.30
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="bus_name">
-<parameter_description> A unique or well-known bus name or %NULL if
- connection is not a message bus connection.
+<parameter_description> a unique or well-known bus name or %NULL if
+ connection is not a message bus connection
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> Path of remote object.
+<parameter_description> path of remote object
</parameter_description>
</parameter>
<parameter name="interface_name">
-<parameter_description> D-Bus interface to invoke method on.
+<parameter_description> D-Bus interface to invoke method on
</parameter_description>
</parameter>
<parameter name="method_name">
-<parameter_description> The name of the method to invoke.
+<parameter_description> the name of the method to invoke
</parameter_description>
</parameter>
<parameter name="parameters">
-<parameter_description> A #GVariant tuple with parameters for the method
-or %NULL if not passing parameters.
+<parameter_description> a #GVariant tuple with parameters for the method
+or %NULL if not passing parameters
</parameter_description>
</parameter>
<parameter name="reply_type">
-<parameter_description> The expected type of the reply, or %NULL.
+<parameter_description> the expected type of the reply, or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags from the #GDBusCallFlags enumeration.
+<parameter_description> flags from the #GDBusCallFlags enumeration
</parameter_description>
</parameter>
<parameter name="timeout_msec">
-<parameter_description> The timeout in milliseconds, -1 to use the default
-timeout or %G_MAXINT for no timeout.
+<parameter_description> the timeout in milliseconds, -1 to use the default
+timeout or %G_MAXINT for no timeout
</parameter_description>
</parameter>
<parameter name="fd_list">
-<parameter_description> A #GUnixFDList or %NULL.
+<parameter_description> a #GUnixFDList or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is
+<parameter_description> a #GAsyncReadyCallback to call when the request is
satisfied or %NULL if you don't * care about the result of the
-method invocation.
+method invocation
</parameter_description>
</parameter>
<parameter name="user_data">
@@ -26504,19 +26644,20 @@ Since: 2.30
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="out_fd_list">
-<parameter_description> Return location for a #GUnixFDList or %NULL.
+<parameter_description> return location for a #GUnixFDList or %NULL
</parameter_description>
</parameter>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_call_with_unix_fd_list().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
+g_dbus_connection_call_with_unix_fd_list()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -26537,58 +26678,58 @@ Since: 2.30
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="bus_name">
-<parameter_description> A unique or well-known bus name or %NULL if
- connection is not a message bus connection.
+<parameter_description> a unique or well-known bus name or %NULL
+if @connection is not a message bus connection
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> Path of remote object.
+<parameter_description> path of remote object
</parameter_description>
</parameter>
<parameter name="interface_name">
-<parameter_description> D-Bus interface to invoke method on.
+<parameter_description> D-Bus interface to invoke method on
</parameter_description>
</parameter>
<parameter name="method_name">
-<parameter_description> The name of the method to invoke.
+<parameter_description> the name of the method to invoke
</parameter_description>
</parameter>
<parameter name="parameters">
-<parameter_description> A #GVariant tuple with parameters for the method
-or %NULL if not passing parameters.
+<parameter_description> a #GVariant tuple with parameters for
+the method or %NULL if not passing parameters
</parameter_description>
</parameter>
<parameter name="reply_type">
-<parameter_description> The expected type of the reply, or %NULL.
+<parameter_description> the expected type of the reply, or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags from the #GDBusCallFlags enumeration.
+<parameter_description> flags from the #GDBusCallFlags enumeration
</parameter_description>
</parameter>
<parameter name="timeout_msec">
-<parameter_description> The timeout in milliseconds, -1 to use the default
-timeout or %G_MAXINT for no timeout.
+<parameter_description> the timeout in milliseconds, -1 to use the default
+timeout or %G_MAXINT for no timeout
</parameter_description>
</parameter>
<parameter name="fd_list">
-<parameter_description> A #GUnixFDList or %NULL.
+<parameter_description> a #GUnixFDList or %NULL
</parameter_description>
</parameter>
<parameter name="out_fd_list">
-<parameter_description> Return location for a #GUnixFDList or %NULL.
+<parameter_description> return location for a #GUnixFDList or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -26613,16 +26754,16 @@ If @connection is already closed, this method fails with
%G_IO_ERROR_CLOSED.
When @connection has been closed, the #GDBusConnection::closed
-signal is emitted in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread that @connection was constructed in.
+signal is emitted in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that @connection was constructed in.
This is an asynchronous method. When the operation is finished,
- callback will be invoked in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this method from. You can
+ callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can
then call g_dbus_connection_close_finish() to get the result of the
-operation. See g_dbus_connection_close_sync() for the synchronous
+operation. See g_dbus_connection_close_sync() for the synchronous
version.
Since: 2.26
@@ -26630,20 +26771,20 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is
-satisfied or %NULL if you don't care about the result.
+<parameter_description> a #GAsyncReadyCallback to call when the request is
+satisfied or %NULL if you don't care about the result
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> The data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -26659,19 +26800,20 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_close().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+to g_dbus_connection_close()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the operation succeeded, %FALSE if @error is set.
+<return> %TRUE if the operation succeeded, %FALSE if @error is set
</return>
</function>
@@ -26688,19 +26830,19 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the operation succeeded, %FALSE if @error is set.
+<return> %TRUE if the operation succeeded, %FALSE if @error is set
</return>
</function>
@@ -26718,37 +26860,37 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="destination_bus_name">
-<parameter_description> The unique bus name for the destination
-for the signal or %NULL to emit to all listeners.
+<parameter_description> the unique bus name for the destination
+for the signal or %NULL to emit to all listeners
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> Path of remote object.
+<parameter_description> path of remote object
</parameter_description>
</parameter>
<parameter name="interface_name">
-<parameter_description> D-Bus interface to emit a signal on.
+<parameter_description> D-Bus interface to emit a signal on
</parameter_description>
</parameter>
<parameter name="signal_name">
-<parameter_description> The name of the signal to emit.
+<parameter_description> the name of the signal to emit
</parameter_description>
</parameter>
<parameter name="parameters">
-<parameter_description> A #GVariant tuple with parameters for the signal
-or %NULL if not passing parameters.
+<parameter_description> a #GVariant tuple with parameters for the signal
+or %NULL if not passing parameters
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> Return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE unless @error is set.
+<return> %TRUE unless @error is set
</return>
</function>
@@ -26849,17 +26991,16 @@ Since: 2.32
Asynchronously flushes @connection, that is, writes all queued
outgoing message to the transport and then flushes the transport
(using g_output_stream_flush_async()). This is useful in programs
-that wants to emit a D-Bus signal and then exit
-immediately. Without flushing the connection, there is no guarantee
-that the message has been sent to the networking buffers in the OS
-kernel.
+that wants to emit a D-Bus signal and then exit immediately. Without
+flushing the connection, there is no guaranteed that the message has
+been sent to the networking buffers in the OS kernel.
This is an asynchronous method. When the operation is finished,
- callback will be invoked in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this method from. You can
+ callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from. You can
then call g_dbus_connection_flush_finish() to get the result of the
-operation. See g_dbus_connection_flush_sync() for the synchronous
+operation. See g_dbus_connection_flush_sync() for the synchronous
version.
Since: 2.26
@@ -26867,20 +27008,20 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is
-satisfied or %NULL if you don't care about the result.
+<parameter_description> a #GAsyncReadyCallback to call when the
+request is satisfied or %NULL if you don't care about the result
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> The data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -26896,19 +27037,20 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_flush().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+to g_dbus_connection_flush()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the operation succeeded, %FALSE if @error is set.
+<return> %TRUE if the operation succeeded, %FALSE if @error is set
</return>
</function>
@@ -26925,19 +27067,19 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the operation succeeded, %FALSE if @error is set.
+<return> %TRUE if the operation succeeded, %FALSE if @error is set
</return>
</function>
@@ -26951,11 +27093,11 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
-<return> Zero or more flags from the #GDBusCapabilityFlags enumeration.
+<return> zero or more flags from the #GDBusCapabilityFlags enumeration
</return>
</function>
@@ -26971,12 +27113,12 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
-<return> Whether the process is terminated when @connection is
-closed by the remote peer.
+<return> whether the process is terminated when @connection is
+closed by the remote peer
</return>
</function>
@@ -26991,7 +27133,7 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
@@ -27014,12 +27156,12 @@ Since: 2.34
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
<return> the last used serial or zero when no message has been sent
-within the current thread.
+within the current thread
</return>
</function>
@@ -27041,12 +27183,12 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
-<return> A #GCredentials or %NULL if not available. Do not free
-this object, it is owned by @connection.
+<return> a #GCredentials or %NULL if not available.
+Do not free this object, it is owned by @connection.
</return>
</function>
@@ -27084,11 +27226,11 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
-<return> The unique name or %NULL if @connection is not a message
+<return> the unique name or %NULL if @connection is not a message
bus connection. Do not free this string, it is owned by
@connection.
@@ -27104,11 +27246,11 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the connection is closed, %FALSE otherwise.
+<return> %TRUE if the connection is closed, %FALSE otherwise
</return>
</function>
@@ -27141,31 +27283,31 @@ Since: 2.26
</description>
<parameters>
<parameter name="stream">
-<parameter_description> A #GIOStream.
+<parameter_description> a #GIOStream
</parameter_description>
</parameter>
<parameter name="guid">
-<parameter_description> The GUID to use if a authenticating as a server or %NULL.
+<parameter_description> the GUID to use if a authenticating as a server or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags describing how to make the connection.
+<parameter_description> flags describing how to make the connection
</parameter_description>
</parameter>
<parameter name="observer">
-<parameter_description> A #GDBusAuthObserver or %NULL.
+<parameter_description> a #GDBusAuthObserver or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is satisfied.
+<parameter_description> a #GAsyncReadyCallback to call when the request is satisfied
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> the data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -27181,15 +27323,17 @@ Since: 2.26
</description>
<parameters>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_new().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback
+passed to g_dbus_connection_new().
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+<return> a #GDBusConnection or %NULL if @error is set. Free
+with g_object_unref().
</return>
</function>
@@ -27222,27 +27366,27 @@ Since: 2.26
</description>
<parameters>
<parameter name="address">
-<parameter_description> A D-Bus address.
+<parameter_description> a D-Bus address
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags describing how to make the connection.
+<parameter_description> flags describing how to make the connection
</parameter_description>
</parameter>
<parameter name="observer">
-<parameter_description> A #GDBusAuthObserver or %NULL.
+<parameter_description> a #GDBusAuthObserver or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is satisfied.
+<parameter_description> a #GAsyncReadyCallback to call when the request is satisfied
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> the data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -27258,15 +27402,17 @@ Since: 2.26
</description>
<parameters>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_new().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+to g_dbus_connection_new()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+<return> a #GDBusConnection or %NULL if @error is set. Free with
+g_object_unref().
</return>
</function>
@@ -27294,27 +27440,28 @@ Since: 2.26
</description>
<parameters>
<parameter name="address">
-<parameter_description> A D-Bus address.
+<parameter_description> a D-Bus address
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags describing how to make the connection.
+<parameter_description> flags describing how to make the connection
</parameter_description>
</parameter>
<parameter name="observer">
-<parameter_description> A #GDBusAuthObserver or %NULL.
+<parameter_description> a #GDBusAuthObserver or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+<return> a #GDBusConnection or %NULL if @error is set. Free with
+g_object_unref().
</return>
</function>
@@ -27342,31 +27489,31 @@ Since: 2.26
</description>
<parameters>
<parameter name="stream">
-<parameter_description> A #GIOStream.
+<parameter_description> a #GIOStream
</parameter_description>
</parameter>
<parameter name="guid">
-<parameter_description> The GUID to use if a authenticating as a server or %NULL.
+<parameter_description> the GUID to use if a authenticating as a server or %NULL
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags describing how to make the connection.
+<parameter_description> flags describing how to make the connection
</parameter_description>
</parameter>
<parameter name="observer">
-<parameter_description> A #GDBusAuthObserver or %NULL.
+<parameter_description> a #GDBusAuthObserver or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+<return> a #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
</return>
</function>
@@ -27376,19 +27523,20 @@ Since: 2.26
Registers callbacks for exported objects at @object_path with the
D-Bus interface that is described in @interface_info.
-Calls to functions in @vtable (and @user_data_free_func) will
-happen in the <link linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this method from.
+Calls to functions in @vtable (and @user_data_free_func) will happen
+in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
Note that all #GVariant values passed to functions in @vtable will match
the signature given in @interface_info - if a remote caller passes
-incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
+incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
is returned to the remote caller.
Additionally, if the remote caller attempts to invoke methods or
access properties not mentioned in @interface_info the
-<literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
-<literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
+`org.freedesktop.DBus.Error.UnknownMethod` resp.
+`org.freedesktop.DBus.Error.InvalidArgs` errors
are returned to the caller.
It is considered a programming error if the
@@ -27400,60 +27548,59 @@ If an existing callback is already registered at @object_path and
GDBus automatically implements the standard D-Bus interfaces
org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
-and org.freedesktop.Peer, so you don't have to implement those for
-the objects you export. You <emphasis>can</emphasis> implement
-org.freedesktop.DBus.Properties yourself, e.g. to handle getting
-and setting of properties asynchronously.
+and org.freedesktop.Peer, so you don't have to implement those for the
+objects you export. You can implement org.freedesktop.DBus.Properties
+yourself, e.g. to handle getting and setting of properties asynchronously.
Note that the reference count on @interface_info will be
incremented by 1 (unless allocated statically, e.g. if the
reference count is -1, see g_dbus_interface_info_ref()) for as long
as the object is exported. Also note that @vtable will be copied.
-See <xref linkend="gdbus-server"/> for an example of how to use this method.
+See this [server][gdbus-server] for an example of how to use this method.
Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> The object path to register at.
+<parameter_description> the object path to register at
</parameter_description>
</parameter>
<parameter name="interface_info">
-<parameter_description> Introspection data for the interface.
+<parameter_description> introspection data for the interface
</parameter_description>
</parameter>
<parameter name="vtable">
-<parameter_description> A #GDBusInterfaceVTable to call into or %NULL.
+<parameter_description> a #GDBusInterfaceVTable to call into or %NULL
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> Data to pass to functions in @vtable.
+<parameter_description> data to pass to functions in @vtable
</parameter_description>
</parameter>
<parameter name="user_data_free_func">
-<parameter_description> Function to call when the object path is unregistered.
+<parameter_description> function to call when the object path is unregistered
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
<return> 0 if @error is set, otherwise a registration id (never 0)
-that can be used with g_dbus_connection_unregister_object() .
+that can be used with g_dbus_connection_unregister_object()
</return>
</function>
<function name="g_dbus_connection_register_subtree">
<description>
-Registers a whole subtree of <quote>dynamic</quote> objects.
+Registers a whole subtree of dynamic objects.
The @enumerate and @introspection functions in @vtable are used to
convey, to remote callers, what nodes exist in the subtree rooted
@@ -27468,9 +27615,9 @@ where to dispatch the call. The collected #GDBusInterfaceVTable and
#gpointer will be used to call into the interface vtable for processing
the request.
-All calls into user-provided code will be invoked in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this method from.
+All calls into user-provided code will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
If an existing subtree is already registered at @object_path or
then @error is set to #G_IO_ERROR_EXISTS.
@@ -27479,45 +27626,46 @@ Note that it is valid to register regular objects (using
g_dbus_connection_register_object()) in a subtree registered with
g_dbus_connection_register_subtree() - if so, the subtree handler
is tried as the last resort. One way to think about a subtree
-handler is to consider it a <quote>fallback handler</quote>
-for object paths not registered via g_dbus_connection_register_object()
-or other bindings.
+handler is to consider it a fallback handler for object paths not
+registered via g_dbus_connection_register_object() or other bindings.
Note that @vtable will be copied so you cannot change it after
registration.
-See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
+See this [server][gdbus-subtree-server] for an example of how to use
+this method.
Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> The object path to register the subtree at.
+<parameter_description> the object path to register the subtree at
</parameter_description>
</parameter>
<parameter name="vtable">
-<parameter_description> A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
+<parameter_description> a #GDBusSubtreeVTable to enumerate, introspect and
+dispatch nodes in the subtree
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags used to fine tune the behavior of the subtree.
+<parameter_description> flags used to fine tune the behavior of the subtree
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> Data to pass to functions in @vtable.
+<parameter_description> data to pass to functions in @vtable
</parameter_description>
</parameter>
<parameter name="user_data_free_func">
-<parameter_description> Function to call when the subtree is unregistered.
+<parameter_description> function to call when the subtree is unregistered
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -27562,9 +27710,9 @@ If @connection is closed then the operation will fail with
%G_IO_ERROR_CLOSED. If @message is not well-formed,
the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
-See <xref linkend="gdbus-server"/> and <xref
-linkend="gdbus-unix-fd-client"/> for an example of how to use this
-low-level API to send and receive UNIX file descriptors.
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
Note that @message must be unlocked, unless @flags contain the
%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
@@ -27574,29 +27722,29 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="message">
-<parameter_description> A #GDBusMessage
+<parameter_description> a #GDBusMessage
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags affecting how the message is sent.
+<parameter_description> flags affecting how the message is sent
</parameter_description>
</parameter>
<parameter name="out_serial">
-<parameter_description> Return location for serial number assigned
-to @message when sending it or %NULL.
+<parameter_description> return location for serial number assigned
+to @message when sending it or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> Return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
<return> %TRUE if the message was well-formed and queued for
-transmission, %FALSE if @error is set.
+transmission, %FALSE if @error is set
</return>
</function>
@@ -27617,8 +27765,9 @@ If @connection is closed then the operation will fail with
fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed,
the operation fails with %G_IO_ERROR_INVALID_ARGUMENT.
-This is an asynchronous method. When the operation is finished, @callback will be invoked
-in the <link linkend="g-main-context-push-thread-default">thread-default main
loop</link>
+This is an asynchronous method. When the operation is finished, @callback
+will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
of the thread you are calling this method from. You can then call
g_dbus_connection_send_message_with_reply_finish() to get the result of the operation.
See g_dbus_connection_send_message_with_reply_sync() for the synchronous version.
@@ -27626,47 +27775,47 @@ See g_dbus_connection_send_message_with_reply_sync() for the synchronous version
Note that @message must be unlocked, unless @flags contain the
%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
-See <xref linkend="gdbus-server"/> and <xref
-linkend="gdbus-unix-fd-client"/> for an example of how to use this
-low-level API to send and receive UNIX file descriptors.
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="message">
-<parameter_description> A #GDBusMessage.
+<parameter_description> a #GDBusMessage
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags affecting how the message is sent.
+<parameter_description> flags affecting how the message is sent
</parameter_description>
</parameter>
<parameter name="timeout_msec">
-<parameter_description> The timeout in milliseconds, -1 to use the default
-timeout or %G_MAXINT for no timeout.
+<parameter_description> the timeout in milliseconds, -1 to use the default
+timeout or %G_MAXINT for no timeout
</parameter_description>
</parameter>
<parameter name="out_serial">
-<parameter_description> Return location for serial number assigned
-to @message when sending it or %NULL.
+<parameter_description> return location for serial number assigned
+to @message when sending it or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> A #GAsyncReadyCallback to call when the request is
-satisfied or %NULL if you don't care about the result.
+<parameter_description> a #GAsyncReadyCallback to call when the request
+is satisfied or %NULL if you don't care about the result
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> The data to pass to @callback.
+<parameter_description> The data to pass to @callback
</parameter_description>
</parameter>
</parameters>
@@ -27682,9 +27831,9 @@ occurred. That is to say that the returned #GDBusMessage object may
be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
g_dbus_message_to_gerror() to transcode this to a #GError.
-See <xref linkend="gdbus-server"/> and <xref
-linkend="gdbus-unix-fd-client"/> for an example of how to use this
-low-level API to send and receive UNIX file descriptors.
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
Since: 2.26
@@ -27695,15 +27844,16 @@ Since: 2.26
</parameter_description>
</parameter>
<parameter name="res">
-<parameter_description> A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
g_dbus_connection_send_message_with_reply().
+<parameter_description> a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
+g_dbus_connection_send_message_with_reply()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> teturn location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A locked #GDBusMessage or %NULL if @error is set.
+<return> a locked #GDBusMessage or %NULL if @error is set
</return>
</function>
@@ -27732,9 +27882,9 @@ occurred. That is to say that the returned #GDBusMessage object may
be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use
g_dbus_message_to_gerror() to transcode this to a #GError.
-See <xref linkend="gdbus-server"/> and <xref
-linkend="gdbus-unix-fd-client"/> for an example of how to use this
-low-level API to send and receive UNIX file descriptors.
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
Note that @message must be unlocked, unless @flags contain the
%G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
@@ -27744,37 +27894,38 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="message">
-<parameter_description> A #GDBusMessage.
+<parameter_description> a #GDBusMessage
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags affecting how the message is sent.
+<parameter_description> flags affecting how the message is sent.
</parameter_description>
</parameter>
<parameter name="timeout_msec">
-<parameter_description> The timeout in milliseconds, -1 to use the default
-timeout or %G_MAXINT for no timeout.
+<parameter_description> the timeout in milliseconds, -1 to use the default
+timeout or %G_MAXINT for no timeout
</parameter_description>
</parameter>
<parameter name="out_serial">
-<parameter_description> Return location for serial number assigned
-to @message when sending it or %NULL.
+<parameter_description> return location for serial number
+assigned to @message when sending it or %NULL
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> A #GCancellable or %NULL.
+<parameter_description> a #GCancellable or %NULL
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> Return location for error or %NULL.
+<parameter_description> return location for error or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
+<return> a locked #GDBusMessage that is the reply
+to @message or %NULL if @error is set
</return>
</function>
@@ -27797,12 +27948,12 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="exit_on_close">
-<parameter_description> Whether the process should be terminated
-when @connection is closed by the remote peer.
+<parameter_description> whether the process should be terminated
+when @connection is closed by the remote peer
</parameter_description>
</parameter>
</parameters>
@@ -27811,11 +27962,10 @@ when @connection is closed by the remote peer.
<function name="g_dbus_connection_signal_subscribe">
<description>
-Subscribes to signals on @connection and invokes @callback with a
-whenever the signal is received. Note that @callback
-will be invoked in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread you are calling this method from.
+Subscribes to signals on @connection and invokes @callback with a whenever
+the signal is received. Note that @callback will be invoked in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread you are calling this method from.
If @connection is not a message bus connection, @sender must be
%NULL.
@@ -27837,51 +27987,53 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="sender">
-<parameter_description> Sender name to match on (unique or well-known name)
-or %NULL to listen from all senders.
+<parameter_description> sender name to match on (unique or well-known name)
+or %NULL to listen from all senders
</parameter_description>
</parameter>
<parameter name="interface_name">
<parameter_description> D-Bus interface name to match on or %NULL to
-match on all interfaces.
+match on all interfaces
</parameter_description>
</parameter>
<parameter name="member">
-<parameter_description> D-Bus signal name to match on or %NULL to match on all signals.
+<parameter_description> D-Bus signal name to match on or %NULL to match on
+all signals
</parameter_description>
</parameter>
<parameter name="object_path">
-<parameter_description> Object path to match on or %NULL to match on all object paths.
+<parameter_description> object path to match on or %NULL to match on
+all object paths
</parameter_description>
</parameter>
<parameter name="arg0">
-<parameter_description> Contents of first string argument to match on or %NULL
-to match on all kinds of arguments.
+<parameter_description> contents of first string argument to match on or %NULL
+to match on all kinds of arguments
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Flags describing how to subscribe to the signal (currently unused).
+<parameter_description> flags describing how to subscribe to the signal (currently unused)
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> Callback to invoke when there is a signal matching the requested data.
+<parameter_description> callback to invoke when there is a signal matching the requested data
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> User data to pass to @callback.
+<parameter_description> user data to pass to @callback
</parameter_description>
</parameter>
<parameter name="user_data_free_func">
-<parameter_description> Function to free @user_data with when
-subscription is removed or %NULL.
+<parameter_description> function to free @user_data with when
+subscription is removed or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
+<return> a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
</return>
</function>
@@ -27895,11 +28047,12 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="subscription_id">
-<parameter_description> A subscription id obtained from g_dbus_connection_signal_subscribe().
+<parameter_description> a subscription id obtained from
+g_dbus_connection_signal_subscribe()
</parameter_description>
</parameter>
</parameters>
@@ -27918,7 +28071,7 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
</parameters>
@@ -27984,15 +28137,16 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="registration_id">
-<parameter_description> A registration id obtained from g_dbus_connection_register_object().
+<parameter_description> a registration id obtained from
+g_dbus_connection_register_object()
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the object was unregistered, %FALSE otherwise.
+<return> %TRUE if the object was unregistered, %FALSE otherwise
</return>
</function>
@@ -28006,15 +28160,16 @@ Since: 2.26
</description>
<parameters>
<parameter name="connection">
-<parameter_description> A #GDBusConnection.
+<parameter_description> a #GDBusConnection
</parameter_description>
</parameter>
<parameter name="registration_id">
-<parameter_description> A subtree registration id obtained from g_dbus_connection_register_subtree().
+<parameter_description> a subtree registration id obtained from
+g_dbus_connection_register_subtree()
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the subtree was unregistered, %FALSE otherwise.
+<return> %TRUE if the subtree was unregistered, %FALSE otherwise
</return>
</function>
@@ -28026,7 +28181,7 @@ a registered error (cf. g_dbus_error_register_error()), the corresponding
D-Bus error name will be returned.
Otherwise the a name of the form
-<literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
+`org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
will be used. This allows other GDBus applications to map the error
on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
@@ -28052,8 +28207,8 @@ Since: 2.26
Gets the D-Bus error name used for @error, if any.
This function is guaranteed to return a D-Bus error name for all
-#GError<!-- -->s returned from functions handling remote method
-calls (e.g. g_dbus_connection_call_finish()) unless
+#GErrors returned from functions handling remote method calls
+(e.g. g_dbus_connection_call_finish()) unless
g_dbus_error_strip_remote_error() has been used on @error.
Since: 2.26
@@ -28061,11 +28216,12 @@ Since: 2.26
</description>
<parameters>
<parameter name="error">
-<parameter_description> A #GError.
+<parameter_description> a #GError
</parameter_description>
</parameter>
</parameters>
-<return> An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
+<return> an allocated string or %NULL if the D-Bus error name
+could not be found. Free with g_free().
</return>
</function>
@@ -28140,7 +28296,7 @@ Since: 2.26
<function name="g_dbus_error_register_error">
<description>
Creates an association to map between @dbus_error_name and
-#GError<!-- -->s specified by @error_domain and @error_code.
+#GErrors specified by @error_domain and @error_code.
This is typically done in the routine that returns the #GQuark for
an error domain.
@@ -28331,72 +28487,31 @@ Since: 2.26
<function name="g_dbus_gvalue_to_gvariant">
<description>
-Converts a #GValue to a #GVariant of the type indicated by the @type parameter.
+Converts a #GValue to a #GVariant of the type indicated by the @type
+parameter.
The conversion is using the following rules:
-<table frame='all'>
-<title>#GValue / #GVariant conversion rules</title>
-<tgroup cols='2' align='left' colsep='1' rowsep='1'>
-<thead>
-<row>
-<entry>If the #GType for @gvalue is...</entry>
-<entry>... then @type must be</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry>#G_TYPE_STRING</entry>
-<entry><link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, <link
linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link>, <link
linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link> or <link
linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_STRV</entry>
-<entry><link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>, <link
linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> or <link
linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_BOOLEAN</entry>
-<entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_UCHAR</entry>
-<entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_INT</entry>
-<entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link
linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_UINT</entry>
-<entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link
linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_INT64</entry>
-<entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_UINT64</entry>
-<entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_DOUBLE</entry>
-<entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry>
-</row>
-<row>
-<entry>#G_TYPE_VARIANT</entry>
-<entry>Any #GVariantType</entry>
-</row>
-</tbody>
-</tgroup>
-</table>
+
+- #G_TYPE_STRING: 's', 'o', 'g' or 'ay'
+- #G_TYPE_STRV: 'as', 'ao' or 'aay'
+- #G_TYPE_BOOLEAN: 'b'
+- #G_TYPE_UCHAR: 'y'
+- #G_TYPE_INT: 'i', 'n'
+- #G_TYPE_UINT: 'u', 'q'
+- #G_TYPE_INT64 'x'
+- #G_TYPE_UINT64: 't'
+- #G_TYPE_DOUBLE: 'd'
+- #G_TYPE_VARIANT: Any #GVariantType
+
This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type
-is <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. It will
-also fail for any #GType (including e.g. #G_TYPE_OBJECT and
-#G_TYPE_BOXED derived-types) not in the table above.
+is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType
+(including e.g. #G_TYPE_OBJECT and #G_TYPE_BOXED derived-types) not
+in the table above.
Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
-%NULL, the <emphasis>empty</emphasis> #GVariant instance (never
-%NULL) for @type is returned (e.g. 0 for scalar types, the empty
-string for string types, <literal>'/'</literal> for object path
-types, the empty array for any array type and so on).
+%NULL, the empty #GVariant instance (never %NULL) for @type is
+returned (e.g. 0 for scalar types, the empty string for string types,
+'/' for object path types, the empty array for any array type and so on).
See the g_dbus_gvariant_to_gvalue() function for how to convert a
#GVariant to a #GValue.
@@ -28406,17 +28521,17 @@ Since: 2.30
</description>
<parameters>
<parameter name="gvalue">
-<parameter_description> A #GValue to convert to a #GVariant.
+<parameter_description> A #GValue to convert to a #GVariant
</parameter_description>
</parameter>
<parameter name="type">
-<parameter_description> A #GVariantType.
+<parameter_description> A #GVariantType
</parameter_description>
</parameter>
</parameters>
-<return> A #GVariant (never floating) of #GVariantType
- type holding the data from @gvalue or %NULL in case of
-failure. Free with g_variant_unref().
+<return> A #GVariant (never floating) of #GVariantType @type holding
+the data from @gvalue or %NULL in case of failure. Free with
+g_variant_unref().
</return>
</function>
@@ -28490,17 +28605,16 @@ Since: 2.30
<description>
Gets the #GDBusObject that @interface_ belongs to, if any.
-<warning>It is not safe to use the returned object if @interface_
-or the returned object is being used from other threads. See
-g_dbus_interface_dup_object() for a thread-safe
-alternative.</warning>
+It is not safe to use the returned object if @interface_ or
+the returned object is being used from other threads. See
+g_dbus_interface_dup_object() for a thread-safe alternative.
Since: 2.30
</description>
<parameters>
<parameter name="interface_">
-<parameter_description> An exported D-Bus interface.
+<parameter_description> An exported D-Bus interface
</parameter_description>
</parameter>
</parameters>
@@ -28559,7 +28673,7 @@ Appends an XML representation of @info (and its children) to @string_builder.
This function is typically used for generating introspection XML
documents at run-time for handling the
-<literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
+`org.freedesktop.DBus.Introspectable.Introspect`
method.
Since: 2.26
@@ -28760,7 +28874,7 @@ emitted immediately.
For example, an exported D-Bus interface may queue up property
changes and emit the
-<literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
+`org.freedesktop.DBus.Properties::Propert``
signal later (e.g. in an idle handler). This technique is useful
for collapsing multiple property changes into one.
@@ -28886,7 +29000,9 @@ Since: 2.30
</parameter_description>
</parameter>
</parameters>
-<return> A #GVariant of type <link
linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref().
+<return> A #GVariant of type
+['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS].
+Free with g_variant_unref().
</return>
</function>
@@ -29813,7 +29929,7 @@ Produces a human-readable multi-line description of @message.
The contents of the description has no ABI guarantees, the contents
and formatting is subject to change at any time. Typical output
looks something like this:
-<programlisting>
+|[
Type: method-call
Flags: none
Version: 0
@@ -29826,9 +29942,9 @@ destination -> ':1.146'
Body: ()
UNIX File Descriptors:
(none)
-</programlisting>
+]|
or
-<programlisting>
+|[
Type: method-return
Flags: no-reply-expected
Version: 0
@@ -29841,7 +29957,7 @@ num-unix-fds -> uint32 1
Body: ()
UNIX File Descriptors:
fd 12:
dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
-</programlisting>
+]|
Since: 2.26
@@ -30341,9 +30457,9 @@ you need to use low-level protocol features, such as UNIX file
descriptor passing, that cannot be properly expressed in the
#GVariant API.
-See <xref linkend="gdbus-server"/> and <xref
-linkend="gdbus-unix-fd-client"/> for an example of how to use this
-low-level API to send and receive UNIX file descriptors.
+See this [server][gdbus-server] and [client][gdbus-unix-fd-client]
+for an example of how to use this low-level API to send and receive
+UNIX file descriptors.
Since: 2.26
@@ -30535,12 +30651,11 @@ See g_dbus_error_encode_gerror() for details about what error name
will be returned on the wire. In a nutshell, if the given error is
registered using g_dbus_error_register_error() the name given
during registration is used. Otherwise, a name of the form
-<literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
-used. This provides transparent mapping of #GError between
-applications using GDBus.
+`org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
+transparent mapping of #GError between applications using GDBus.
If you are writing an application intended to be portable,
-<emphasis>always</emphasis> register errors with g_dbus_error_register_error()
+always register errors with g_dbus_error_register_error()
or use g_dbus_method_invocation_return_dbus_error().
This method will free @invocation, you cannot use it afterwards.
@@ -30742,7 +30857,7 @@ Since: 2.30
Appends an XML representation of @info (and its children) to @string_builder.
This function is typically used for generating introspection XML documents at run-time for
-handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
+handling the `org.freedesktop.DBus.Introspectable.Introspect` method.
Since: 2.26
@@ -30793,10 +30908,10 @@ Since: 2.26
Parses @xml_data and returns a #GDBusNodeInfo representing the data.
The introspection XML must contain exactly one top-level
-<tag class="starttag">node</tag> element.
+<node> element.
Note that this routine is using a
-<link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
+[GMarkup][glib-Simple-XML-Subset-Parser.description]-based
parser that only accepts a subset of valid XML documents.
Since: 2.26
@@ -31003,7 +31118,7 @@ Asynchronously creates a new #GDBusObjectManagerClient object.
This is an asynchronous failable constructor. When the result is
ready, @callback will be invoked in the
-<link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+[thread-default main context][g-main-context-push-thread-default]
of the thread you are calling this method from. You can
then call g_dbus_object_manager_client_new_finish() to get the result. See
g_dbus_object_manager_client_new_sync() for the synchronous version.
@@ -31087,7 +31202,7 @@ Like g_dbus_object_manager_client_new() but takes a #GBusType instead of a
This is an asynchronous failable constructor. When the result is
ready, @callback will be invoked in the
-<link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+[thread-default main loop][g-main-context-push-thread-default]
of the thread you are calling this method from. You can
then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
@@ -31399,10 +31514,9 @@ Since: 2.30
<function name="g_dbus_object_manager_server_export_uniquely">
<description>
Like g_dbus_object_manager_server_export() but appends a string of
-the form <literal>_N</literal> (with N being a natural number) to
- object<!-- -->'s object path if an object with the given path
-already exists. As such, the #GDBusObjectProxy:g-object-path property
-of @object may be modified.
+the form _N (with N being a natural number) to @object's object path
+if an object with the given path already exists. As such, the
+#GDBusObjectProxy:g-object-path property of @object may be modified.
Since: 2.30
@@ -31752,7 +31866,7 @@ compatible with the D-Bus protocol, the operation fails with
If the @parameters #GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.:
-|[
+|[<!-- language="C" -->
g_dbus_proxy_call (proxy,
"TwoStrings",
g_variant_new ("(ss)",
@@ -31771,7 +31885,7 @@ then the return value is checked against the return type.
This is an asynchronous method. When the operation is finished,
@callback will be invoked in the
-<link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+[thread-default main context][g-main-context-push-thread-default]
of the thread you are calling this method from.
You can then call g_dbus_proxy_call_finish() to get the result of
the operation. See g_dbus_proxy_call_sync() for the synchronous
@@ -31866,7 +31980,7 @@ compatible with the D-Bus protocol, the operation fails with
If the @parameters #GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.:
-|[
+|[<!-- language="C" -->
g_dbus_proxy_call_sync (proxy,
"TwoStrings",
g_variant_new ("(ss)",
@@ -32292,7 +32406,7 @@ g_dbus_proxy_new_finish() to get the result.
See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.
-See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
Since: 2.26
@@ -32364,7 +32478,7 @@ Since: 2.26
<description>
Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection.
-See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
Since: 2.26
@@ -32436,7 +32550,7 @@ Since: 2.26
<description>
Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
-See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
Since: 2.26
@@ -32500,7 +32614,7 @@ will be requested to launch a name owner for the name.
This is a synchronous failable constructor. See g_dbus_proxy_new()
and g_dbus_proxy_new_finish() for the asynchronous version.
-See <xref linkend="gdbus-wellknown-proxy"/> for an example of how #GDBusProxy can be used.
+#GDBusProxy is used in this [example][gdbus-wellknown-proxy].
Since: 2.26
@@ -32558,7 +32672,7 @@ it, then @value is checked against the type of the property.
If the @value #GVariant is floating, it is consumed. This allows
convenient 'inline' use of g_variant_new(), e.g.
-|[
+|[<!-- language="C" -->
g_dbus_proxy_set_cached_property (proxy,
"SomeProperty",
g_variant_new ("(si)",
@@ -32566,20 +32680,19 @@ g_variant_new ("(si)",
42));
]|
-Normally you will not need to use this method since @proxy is
-tracking changes using the
-<literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
-D-Bus signal. However, for performance reasons an object may decide
-to not use this signal for some properties and instead use a
-proprietary out-of-band mechanism to transmit changes.
+Normally you will not need to use this method since @proxy
+is tracking changes using the
+`org.freedesktop.DBus.Properties.PropertiesChanged`
+D-Bus signal. However, for performance reasons an object may
+decide to not use this signal for some properties and instead
+use a proprietary out-of-band mechanism to transmit changes.
As a concrete example, consider an object with a property
-<literal>ChatroomParticipants</literal> which is an array of
-strings. Instead of transmitting the same (long) array every time
-the property changes, it is more efficient to only transmit the
-delta using e.g. signals <literal>ChatroomParticipantJoined(String
-name)</literal> and <literal>ChatroomParticipantParted(String
-name)</literal>.
+`ChatroomParticipants` which is an array of strings. Instead of
+transmitting the same (long) array every time the property changes,
+it is more efficient to only transmit the delta using e.g. signals
+`ChatroomParticipantJoined(String name)` and
+`ChatroomParticipantParted(String name)`.
Since: 2.26
@@ -32735,8 +32848,7 @@ incoming connections.
The returned #GDBusServer isn't active - you have to start it with
g_dbus_server_start().
-See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
-be used.
+#GDBusServer is used in this [example][gdbus-peer-to-peer].
This is a synchronous failable constructor. See
g_dbus_server_new() for the asynchronous version.
@@ -33008,7 +33120,7 @@ Since: 2.30
<description>
Checks if the application info should be shown in menus that list available
applications for a specific name of the desktop, based on the
-<literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys.
+`OnlyShowIn` and `NotShowIn` keys.
If @desktop_env is %NULL, then the name of the desktop set with
g_desktop_app_info_set_desktop_env() is used.
@@ -33030,7 +33142,7 @@ Since: 2.30
</parameter>
</parameters>
<return> %TRUE if the @info should be shown in @desktop_env according to the
-<literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
+`OnlyShowIn` and `NotShowIn` keys, %FALSE
otherwise.
</return>
@@ -33263,13 +33375,13 @@ Creates a new #GDesktopAppInfo based on a desktop file id.
A desktop file id is the basename of the desktop file, including the
.desktop extension. GIO is looking for a desktop file with this name
-in the <filename>applications</filename> subdirectories of the XDG data
-directories (i.e. the directories specified in the
-<envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment
-variables). GIO also supports the prefix-to-subdirectory mapping that is
-described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu
Spec</ulink>
+in the `applications` subdirectories of the XDG
+data directories (i.e. the directories specified in the `XDG_DATA_HOME`
+and `XDG_DATA_DIRS` environment variables). GIO also supports the
+prefix-to-subdirectory mapping that is described in the
+[Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
(i.e. a desktop id of kde-foo.desktop will match
-<filename>/usr/share/applications/kde/foo.desktop</filename>).
+`/usr/share/applications/kde/foo.desktop`).
</description>
@@ -33347,20 +33459,19 @@ list with g_free().
Sets the name of the desktop that the application is running in.
This is used by g_app_info_should_show() and
g_desktop_app_info_get_show_in() to evaluate the
-<literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
+`OnlyShowIn` and `NotShowIn`
desktop entry fields.
-The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop
-Menu specification</ulink> recognizes the following:
-<simplelist>
-<member>GNOME</member>
-<member>KDE</member>
-<member>ROX</member>
-<member>XFCE</member>
-<member>LXDE</member>
-<member>Unity</member>
-<member>Old</member>
-</simplelist>
+The
+[Desktop Menu specification](http://standards.freedesktop.org/menu-spec/latest/)
+recognizes the following:
+- GNOME
+- KDE
+- ROX
+- XFCE
+- LXDE
+- Unity
+- Old
Should be called only once; subsequent calls are ignored.
@@ -34078,7 +34189,7 @@ Since: 2.18
<function name="g_emblemed_icon_add_emblem">
<description>
-Adds @emblem to the #GList of #GEmblem <!-- -->s.
+Adds @emblem to the #GList of #GEmblems.
Since: 2.18
@@ -34126,7 +34237,7 @@ Since: 2.18
</parameter>
</parameters>
<return> a #GList of
-#GEmblem <!-- -->s that is owned by @emblemed
+#GEmblems that is owned by @emblemed
</return>
</function>
@@ -34239,8 +34350,7 @@ of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -34484,7 +34594,7 @@ returns %FALSE if "*" was used when creating the matcher.
<function name="g_file_attribute_matcher_new">
<description>
Creates a new file attribute matcher, which matches attributes
-against a given string. #GFileAttributeMatcher<!-- -->s are reference
+against a given string. #GFileAttributeMatchers are reference
counted structures, and are created with a reference count of 1. If
the number of references falls to 0, the #GFileAttributeMatcher is
automatically destroyed.
@@ -34495,18 +34605,13 @@ concatenated with a single comma (e.g. "standard::type,standard::is-hidden&
The wildcard "*" may be used to match all keys and namespaces, or
"namespace::*" will match all keys in a given namespace.
-Examples of strings to use:
-<table>
-<title>File Attribute Matcher strings and results</title>
-<tgroup cols='2' align='left'><thead>
-<row><entry> Matcher String </entry><entry> Matches
</entry></row></thead>
-<tbody>
-<row><entry>"*"</entry><entry>matches all
attributes.</entry></row>
-<row><entry>"standard::is-hidden"</entry><entry>matches only the key
is-hidden in the standard namespace.</entry></row>
-<row><entry>"standard::type,unix::*"</entry><entry>matches the type key in
the standard namespace and
-all keys in the unix namespace.</entry></row>
-</tbody></tgroup>
-</table>
+## Examples of file attribute matcher strings and results
+
+- `"*"`: matches all attributes.
+- `"standard::is-hidden"`: matches only the key is-hidden in the
+standard namespace.
+- `"standard::type,unix::*"`: matches the type key in the standard
+namespace and all keys in the unix namespace.
</description>
@@ -34516,7 +34621,7 @@ all keys in the unix namespace.</entry></row>
</parameter_description>
</parameter>
</parameters>
-<return> a #GFileAttributeMatcher.
+<return> a #GFileAttributeMatcher
</return>
</function>
@@ -34706,8 +34811,7 @@ g_file_copy_finish() to get the result of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -34873,8 +34977,7 @@ of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -35001,8 +35104,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -35098,8 +35200,7 @@ Since: 2.34
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -35413,8 +35514,7 @@ the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -35507,8 +35607,7 @@ g_file_enumerator_close_finish().
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -35568,7 +35667,7 @@ directory of @enumerator. This function is primarily intended to be used
inside loops with g_file_enumerator_next_file().
This is a convenience method that's equivalent to:
-|[
+|[<!-- language="C" -->
gchar *name = g_file_info_get_name (info);
GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
name);
@@ -35711,8 +35810,7 @@ priority is %G_PRIORITY_DEFAULT.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">io priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -35856,8 +35954,7 @@ get the result of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -36116,9 +36213,9 @@ when no longer needed.
<description>
Gets the URI scheme for a #GFile.
RFC 3986 decodes the scheme as:
-<programlisting>
+|[
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
-</programlisting>
+]|
Common schemes include "file", "http", "ftp", etc.
This call does no blocking I/O.
@@ -36291,7 +36388,7 @@ Clears the status information from @info.
<function name="g_file_info_copy_into">
<description>
-Copies all of the <link linkend="gio-GFileAttribute">GFileAttribute</link>s
+Copies all of the [GFileAttribute][gio-GFileAttribute]
from @src_info to @dest_info.
</description>
@@ -36692,7 +36789,7 @@ Gets the edit name for a file.
<function name="g_file_info_get_etag">
<description>
-Gets the <link linkend="gfile-etag">entity tag</link> for a given
+Gets the [entity tag][gfile-etag] for a given
#GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE.
@@ -37285,7 +37382,7 @@ See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE.
</parameter_description>
</parameter>
<parameter name="content_type">
-<parameter_description> a content type. See <link
linkend="gio-GContentType">GContentType</link>.
+<parameter_description> a content type. See [GContentType][gio-GContentType]
</parameter_description>
</parameter>
</parameters>
@@ -37596,8 +37693,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -37729,8 +37825,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="gio-GIOScheduler">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][gio-GIOScheduler] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -38065,8 +38160,7 @@ Since: 2.38
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -38192,9 +38286,9 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
<description>
Recursively measures the disk usage of @file.
-This is essentially an analog of the '<literal>du</literal>' command,
-but it also reports the number of directories and non-directory files
-encountered (including things like symbolic links).
+This is essentially an analog of the 'du' command, but it also
+reports the number of directories and non-directory files encountered
+(including things like symbolic links).
By default, errors are only reported against the toplevel file
itself. Errors found while recursing are silently ignored, unless
@@ -38276,8 +38370,7 @@ Since: 2.38
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -38448,9 +38541,8 @@ Emits the #GFileMonitor::changed signal if a change
has taken place. Should be called from file monitor
implementations only.
-The signal will be emitted from an idle handler (in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-context</link>).
+The signal will be emitted from an idle handler (in the
+[thread-default main context][g-main-context-push-thread-default]).
</description>
<parameters>
@@ -38788,6 +38880,15 @@ relative path resolved relative to the current working directory.
This operation never fails, but the returned object might not
support any I/O operation if @arg points to a malformed path.
+Note that on Windows, this function expects its argument to be in
+UTF-8 -- not the system code page. This means that you
+should not use this function with string from argv as it is passed
+to main(). g_win32_get_command_line() will return a UTF-8 version of
+the commandline. #GApplication also uses UTF-8 but
+g_application_command_line_create_file_for_arg() may be more useful
+for you there. It is also always possible to use this function with
+#GOptionContext arguments of type %G_OPTION_ARG_FILENAME.
+
</description>
<parameters>
@@ -38972,8 +39073,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -39105,8 +39205,7 @@ g_file_output_stream_query_info().
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="gio-GIOScheduler">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][gio-GIOScheduler] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -39421,8 +39520,7 @@ operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -39560,8 +39658,7 @@ then call g_file_query_info_finish() to get the result of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -39723,8 +39820,7 @@ of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -39823,7 +39919,7 @@ possible too, and depend on what kind of filesystem the file is on.
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> an optional <link linkend="gfile-etag">entity tag</link>
+<parameter_description> an optional [entity tag][gfile-etag]
for the current #GFile, or #NULL to ignore
</parameter_description>
</parameter>
@@ -39869,8 +39965,8 @@ of the operation.
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> an <link linkend="gfile-etag">entity tag</link>
-for the current #GFile, or NULL to ignore
+<parameter_description> an [entity tag][gfile-etag] for the current #GFile,
+or %NULL to ignore
</parameter_description>
</parameter>
<parameter name="make_backup">
@@ -39882,8 +39978,7 @@ for the current #GFile, or NULL to ignore
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -39937,8 +40032,8 @@ changed the next time it is saved over.
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> the old <link linkend="gfile-etag">entity tag</link>
-for the document, or %NULL
+<parameter_description> the old [entity-tag][gfile-etag] for the document,
+or %NULL
</parameter_description>
</parameter>
<parameter name="make_backup">
@@ -39950,7 +40045,7 @@ for the document, or %NULL
</parameter_description>
</parameter>
<parameter name="new_etag">
-<parameter_description> a location to a new <link linkend="gfile-etag">entity
tag</link>
+<parameter_description> a location to a new [entity tag][gfile-etag]
for the document. This should be freed with g_free() when no longer
needed, or %NULL
</parameter_description>
@@ -39986,10 +40081,10 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
If @make_backup is %TRUE, this function will attempt to
make a backup of @file.
-<warning><para>No copy of @content will be made, so it must stay valid until
- callback is called. See g_file_replace_contents_bytes_async() for a #GBytes
-version that will automatically hold a reference to the contents (without
-copying) for the duration of the call.</para></warning>
+Note that no copy of @content will be made, so it must stay valid
+until @callback is called. See g_file_replace_contents_bytes_async()
+for a #GBytes version that will automatically hold a reference to the
+contents (without copying) for the duration of the call.
</description>
<parameters>
@@ -40006,7 +40101,7 @@ copying) for the duration of the call.</para></warning>
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> a new <link linkend="gfile-etag">entity tag</link> for the
@file, or %NULL
+<parameter_description> a new [entity tag][gfile-etag] for the @file, or %NULL
</parameter_description>
</parameter>
<parameter name="make_backup">
@@ -40057,7 +40152,7 @@ Since: 2.40
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> a new <link linkend="gfile-etag">entity tag</link> for the
@file, or %NULL
+<parameter_description> a new [entity tag][gfile-etag] for the @file, or %NULL
</parameter_description>
</parameter>
<parameter name="make_backup">
@@ -40102,7 +40197,7 @@ tag for the document, if present.
</parameter_description>
</parameter>
<parameter name="new_etag">
-<parameter_description> a location of a new <link linkend="gfile-etag">entity
tag</link>
+<parameter_description> a location of a new [entity tag][gfile-etag]
for the document. This should be freed with g_free() when it is no
longer needed, or %NULL
</parameter_description>
@@ -40164,7 +40259,7 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> an optional <link linkend="gfile-etag">entity tag</link>
+<parameter_description> an optional [entity tag][gfile-etag]
for the current #GFile, or #NULL to ignore
</parameter_description>
</parameter>
@@ -40214,8 +40309,8 @@ Since: 2.22
</parameter_description>
</parameter>
<parameter name="etag">
-<parameter_description> an <link linkend="gfile-etag">entity tag</link>
-for the current #GFile, or NULL to ignore
+<parameter_description> an [entity tag][gfile-etag] for the current #GFile,
+or %NULL to ignore
</parameter_description>
</parameter>
<parameter name="make_backup">
@@ -40227,8 +40322,7 @@ for the current #GFile, or NULL to ignore
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -40633,8 +40727,7 @@ the result of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -40793,8 +40886,7 @@ the result of the operation.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -40996,11 +41088,10 @@ Since: 2.22
<function name="g_file_supports_thread_contexts">
<description>
-Checks if @file supports <link
-linkend="g-main-context-push-thread-default-context">thread-default
-contexts</link>. If this returns %FALSE, you cannot perform
-asynchronous operations on @file in a thread that has a
-thread-default context.
+Checks if @file supports
+[thread-default contexts][g-main-context-push-thread-default-context].
+If this returns %FALSE, you cannot perform asynchronous operations on
+ file in a thread that has a thread-default context.
Since: 2.22
@@ -41063,8 +41154,7 @@ Since: 2.38
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -41555,19 +41645,14 @@ get @icon back from the returned string.
The encoding of the returned string is proprietary to #GIcon except
in the following two cases
-<itemizedlist>
-<listitem><para>
-If @icon is a #GFileIcon, the returned string is a native path
-(such as <literal>/path/to/my icon.png</literal>) without escaping
+- If @icon is a #GFileIcon, the returned string is a native path
+(such as `/path/to/my icon.png`) without escaping
if the #GFile for @icon is a native file. If the file is not
native, the returned string is the result of g_file_get_uri()
-(such as <literal>sftp://path/to/my%20icon.png</literal>).
-</para></listitem>
-<listitem><para>
-If @icon is a #GThemedIcon with exactly one name, the encoding is
-simply the name (such as <literal>network-server</literal>).
-</para></listitem>
-</itemizedlist>
+(such as `sftp://path/to/my\%20icon.png`).
+
+- If @icon is a #GThemedIcon with exactly one name, the encoding is
+simply the name (such as `network-server`).
Virtual: to_tokens
Since: 2.20
@@ -42141,7 +42226,7 @@ g_object_ref()'d if it will be stored
<function name="g_inet_socket_address_get_flowinfo">
<description>
-Gets the <literal>sin6_flowinfo</literal> field from @address,
+Gets the `sin6_flowinfo` field from @address,
which must be an IPv6 address.
Since: 2.32
@@ -42178,7 +42263,7 @@ Since: 2.22
<function name="g_inet_socket_address_get_scope_id">
<description>
-Gets the <literal>sin6_scope_id</literal> field from @address,
+Gets the `sin6_scope_id` field from @address,
which must be an IPv6 address.
Since: 2.32
@@ -42217,6 +42302,32 @@ Since: 2.22
</return>
</function>
+<function name="g_inet_socket_address_new_from_string">
+<description>
+Creates a new #GInetSocketAddress for @address and @port.
+
+If @address is an IPv6 address, it can also contain a scope ID
+(separated from the address by a "<literal>%</literal>").
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="address">
+<parameter_description> the string form of an IP address
+</parameter_description>
+</parameter>
+<parameter name="port">
+<parameter_description> a port number
+</parameter_description>
+</parameter>
+</parameters>
+<return> a new #GInetSocketAddress, or %NULL if @address cannot be
+parsed.
+
+</return>
+</function>
+
<function name="g_initable_init">
<description>
Initializes the object implementing the interface.
@@ -42234,8 +42345,7 @@ the object doesn't support cancellable initialization the error
If the object is not initialized, or initialization returns with an
error, then all operations on the object except g_object_ref() and
g_object_unref() are considered to be invalid, and have undefined
-behaviour. See the <xref linkend="ginitable"/> section introduction
-for more details.
+behaviour. See the [introduction][ginitable] for more details.
Implementations of this method must be idempotent, i.e. multiple calls
to this function with the same argument should return the same results.
@@ -42480,8 +42590,7 @@ override one you must override all.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -42698,7 +42807,7 @@ read data into (which should be at least count bytes long).
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
+<parameter_description> the [I/O priority][io-priority]
of the request.
</parameter_description>
</parameter>
@@ -42803,8 +42912,7 @@ priority. Default priority is %G_PRIORITY_DEFAULT.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -42974,8 +43082,7 @@ However, if you override one, you must override all.
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -43153,7 +43260,7 @@ The list is sorted by priority, beginning with the highest priority.
</parameter>
</parameters>
<return> a #GList of
-#GIOExtension<!-- -->s. The list is owned by GIO and should not be
+#GIOExtensions. The list is owned by GIO and should not be
modified.
</return>
</function>
@@ -43654,7 +43761,7 @@ Deprecated: use #GThreadPool or g_task_run_in_thread()
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
+<parameter_description> the [I/O priority][io-priority]
of the request.
</parameter_description>
</parameter>
@@ -44356,14 +44463,14 @@ is non-%NULL then it makes most sense to give @data as %NULL and
@size as 0 (allowing #GMemoryOutputStream to do the initial
allocation for itself).
-|[
-/ * a stream that can grow * /
+|[<!-- language="C" -->
+// a stream that can grow
stream = g_memory_output_stream_new (NULL, 0, realloc, free);
-/ * another stream that can grow * /
+// another stream that can grow
stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free);
-/ * a fixed-size stream * /
+// a fixed-size stream
data = malloc (200);
stream3 = g_memory_output_stream_new (data, 200, NULL, free);
]|
@@ -44999,8 +45106,7 @@ first would be populated with the "Undo" and "Redo" items, a
second with the "Cut", "Copy" and "Paste" items. The first and
second menus would then be added as submenus of the third. In XML
format, this would look something like the following:
-
-<informalexample><programlisting><![CDATA[
+|[
<menu id='edit-menu'>
<section>
<item label='Undo'/>
@@ -45012,7 +45118,7 @@ format, this would look something like the following:
<item label='Paste'/>
</section>
</menu>
-]]></programlisting></informalexample>
+]|
The following example is exactly equivalent. It is more illustrative
of the exact relationship between the menus and items (keeping in
@@ -45020,8 +45126,7 @@ mind that the 'link' element defines a new menu that is linked to the
containing one). The style of the second example is more verbose and
difficult to read (and therefore not recommended except for the
purpose of understanding what is really going on).
-
-<informalexample><programlisting><![CDATA[
+|[
<menu id='edit-menu'>
<item>
<link name='section'>
@@ -45037,7 +45142,7 @@ purpose of understanding what is really going on).
</link>
</item>
</menu>
-]]></programlisting></informalexample>
+]|
Since: 2.32
@@ -46298,7 +46403,8 @@ g_object_unref() when no longer needed.
Tries to guess the type of content stored on @mount. Returns one or
more textual identifiers of well-known content types (typically
prefixed with "x-content/"), e.g. x-content/image-dcf for camera
-memory cards. See the <ulink
url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+memory cards. See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
specification for more on x-content types.
This is an asynchronous operation (see
@@ -46372,7 +46478,8 @@ Caller should free this array with g_strfreev() when done with it.
Tries to guess the type of content stored on @mount. Returns one or
more textual identifiers of well-known content types (typically
prefixed with "x-content/"), e.g. x-content/image-dcf for camera
-memory cards. See the <ulink
url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+memory cards. See the
+[shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
specification for more on x-content types.
This is an synchronous operation and as such may block doing IO;
@@ -46421,10 +46528,10 @@ system that is used to address several logical volumes. In this
situation, a #GVolumeMonitor implementation would create two
#GVolume objects (for example, one for the camera functionality of
the device and one for a SD card reader on the device) with
-activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal>
-and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the
+activation URIs `gphoto2://[usb:001,002]/store1/`
+and `gphoto2://[usb:001,002]/store2/`. When the
underlying mount (with root
-<literal>gphoto2://[usb:001,002]/</literal>) is mounted, said
+`gphoto2://[usb:001,002]/`) is mounted, said
#GVolumeMonitor implementation would create two #GMount objects
(each with their root matching the corresponding volume activation
root) that would shadow the original mount.
@@ -48405,10 +48512,10 @@ classes. However, if you override one you must override all.
For the synchronous, blocking version of this function, see
g_output_stream_write().
-<warning><para>No copy of @buffer will be made, so it must stay valid until
- callback is called. See g_output_stream_write_bytes_async() for a #GBytes
-version that will automatically hold a reference to the contents (without
-copying) for the duration of the call.</para></warning>
+Note that no copy of @buffer will be made, so it must stay valid
+until @callback is called. See g_output_stream_write_bytes_async()
+for a #GBytes version that will automatically hold a reference to
+the contents (without copying) for the duration of the call.
</description>
<parameters>
@@ -48451,13 +48558,12 @@ A wrapper function for g_output_stream_write() which takes a
bindings or in other cases where the refcounted nature of #GBytes
is helpful over a bare pointer interface.
-However, note that this function <emphasis>may</emphasis> still
-perform partial writes, just like g_output_stream_write(). If that
-occurs, to continue writing, you will need to create a new #GBytes
-containing just the remaining bytes, using
-g_bytes_new_from_bytes(). Passing the same #GBytes instance
-multiple times potentially can result in duplicated data in the
-output stream.
+However, note that this function may still perform partial writes,
+just like g_output_stream_write(). If that occurs, to continue
+writing, you will need to create a new #GBytes containing just the
+remaining bytes, using g_bytes_new_from_bytes(). Passing the same
+#GBytes instance multiple times potentially can result in duplicated
+data in the output stream.
</description>
@@ -48489,13 +48595,12 @@ This function is similar to g_output_stream_write_async(), but
takes a #GBytes as input. Due to the refcounted nature of #GBytes,
this allows the stream to avoid taking a copy of the data.
-However, note that this function <emphasis>may</emphasis> still
-perform partial writes, just like g_output_stream_write_async().
-If that occurs, to continue writing, you will need to create a new
-#GBytes containing just the remaining bytes, using
-g_bytes_new_from_bytes(). Passing the same #GBytes instance
-multiple times potentially can result in duplicated data in the
-output stream.
+However, note that this function may still perform partial writes,
+just like g_output_stream_write_async(). If that occurs, to continue
+writing, you will need to create a new #GBytes containing just the
+remaining bytes, using g_bytes_new_from_bytes(). Passing the same
+#GBytes instance multiple times potentially can result in duplicated
+data in the output stream.
For the synchronous, blocking version of this function, see
g_output_stream_write_bytes().
@@ -49720,18 +49825,18 @@ Since: 2.26
<function name="g_proxy_resolver_lookup">
<description>
Looks into the system proxy configuration to determine what proxy,
-if any, to use to connect to @uri. The returned proxy URIs are of the
-form <literal><protocol>://[user[:password] ]host:port</literal>
-or <literal>direct://</literal>, where <protocol> could be
-http, rtsp, socks or other proxying protocol.
+if any, to use to connect to @uri. The returned proxy URIs are of
+the form `<protocol>://[user[:password] ]host:port` or
+`direct://`, where <protocol> could be http, rtsp, socks
+or other proxying protocol.
If you don't know what network protocol is being used on the
-socket, you should use <literal>none</literal> as the URI protocol.
+socket, you should use `none` as the URI protocol.
In this case, the resolver might still return a generic proxy type
(such as SOCKS), but would not return protocol-specific proxy types
(such as http).
-<literal>direct://</literal> is used when no proxy is needed.
+`direct://` is used when no proxy is needed.
Direct connection should not be attempted unless it is part of the
returned array of proxies.
@@ -50341,9 +50446,8 @@ done with it. (You can use g_list_free_full() with g_variant_unref() to do this.
Synchronously performs a DNS SRV lookup for the given @service and
@protocol in the given @domain and returns an array of #GSrvTarget.
@domain may be an ASCII-only or UTF-8 hostname. Note also that the
- service and @protocol arguments <emphasis>do not</emphasis>
-include the leading underscore that appears in the actual DNS
-entry.
+ service and @protocol arguments do not include the leading underscore
+that appears in the actual DNS entry.
On success, g_resolver_lookup_service() will return a #GList of
#GSrvTarget, sorted in order of preference. (That is, you should
@@ -51193,8 +51297,8 @@ the location to save the values, or %NULL
<function name="g_settings_backend_get_default">
<description>
Returns the default #GSettingsBackend. It is possible to override
-the default by setting the <envar>GSETTINGS_BACKEND</envar>
-environment variable to the name of a settings backend.
+the default by setting the `GSETTINGS_BACKEND` environment variable
+to the name of a settings backend.
The user gets a reference to the backend.
@@ -51470,8 +51574,7 @@ property, not the other way.
When the @inverted argument is %TRUE, the binding inverts the
value as it passes from the setting to the object, i.e. @property
-will be set to %TRUE if the key is <emphasis>not</emphasis>
-writable.
+will be set to %TRUE if the key is not writable.
Note that the lifecycle of the binding is tied to the object,
and that you can have only one binding per object property.
@@ -51623,12 +51726,12 @@ Since: 2.26
<function name="g_settings_get_child">
<description>
-Creates a 'child' settings object which has a base path of
-<replaceable>base-path</replaceable>/@name, where
-<replaceable>base-path</replaceable> is the base path of @settings.
+Creates a child settings object which has a base path of
+`base-path/@name`, where `base-path` is the base path of
+ settings
The schema for the child settings object must have been declared
-in the schema of @settings using a <tag class="starttag">child</tag> element.
+in the schema of @settings using a <child> element.
Since: 2.26
@@ -51639,7 +51742,7 @@ Since: 2.26
</parameter_description>
</parameter>
<parameter name="name">
-<parameter_description> the name of the 'child' schema
+<parameter_description> the name of the child schema
</parameter_description>
</parameter>
</parameters>
@@ -52549,31 +52652,28 @@ Queries the range of a key.
This function will return a #GVariant that fully describes the range
of values that are valid for @key.
-The type of #GVariant returned is <literal>(sv)</literal>. The
-string describes the type of range restriction in effect. The type
-and meaning of the value contained in the variant depends on the
-string.
+The type of #GVariant returned is `(sv)`. The string describes
+the type of range restriction in effect. The type and meaning of
+the value contained in the variant depends on the string.
-If the string is <literal>'type'</literal> then the variant contains
-an empty array. The element type of that empty array is the expected
-type of value and all values of that type are valid.
+If the string is `'type'` then the variant contains an empty array.
+The element type of that empty array is the expected type of value
+and all values of that type are valid.
-If the string is <literal>'enum'</literal> then the variant contains
-an array enumerating the possible values. Each item in the array is
+If the string is `'enum'` then the variant contains an array
+enumerating the possible values. Each item in the array is
a possible valid value and no other values are valid.
-If the string is <literal>'flags'</literal> then the variant contains
-an array. Each item in the array is a value that may appear zero or
-one times in an array to be used as the value for this key. For
-example, if the variant contained the array <literal>['x',
-'y']</literal> then the valid values for the key would be
-<literal>[]</literal>, <literal>['x']</literal>,
-<literal>['y']</literal>, <literal>['x', 'y']</literal> and
-<literal>['y', 'x']</literal>.
+If the string is `'flags'` then the variant contains an array. Each
+item in the array is a value that may appear zero or one times in an
+array to be used as the value for this key. For example, if the
+variant contained the array `['x', 'y']` then the valid values for
+the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
+`['y', 'x']`.
-Finally, if the string is <literal>'range'</literal> then the variant
-contains a pair of like-typed values -- the minimum and maximum
-permissible values for this key.
+Finally, if the string is `'range'` then the variant contains a pair
+of like-typed values -- the minimum and maximum permissible values
+for this key.
This information should not be used by normal programs. It is
considered to be a hint for introspection purposes. Normal programs
@@ -52736,9 +52836,8 @@ If no schemas are installed, %NULL will be returned.
The returned source may actually consist of multiple schema sources
from different directories, depending on which directories were given
-in <envar>XDG_DATA_DIRS</envar> and
-<envar>GSETTINGS_SCHEMA_DIR</envar>. For this reason, all lookups
-performed against the default source should probably be done
+in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
+lookups performed against the default source should probably be done
recursively.
Since: 2.32
@@ -52834,16 +52933,14 @@ of the given directory.
This function is not required for normal uses of #GSettings but it
may be useful to authors of plugin management systems.
-The directory should contain a file called
-<filename>gschemas.compiled</filename> as produced by
-<command>glib-compile-schemas</command>.
+The directory should contain a file called `gschemas.compiled` as
+produced by the [glib-compile-schemas][glib-compile-schemas] tool.
-If @trusted is %TRUE then <filename>gschemas.compiled</filename> is
-trusted not to be corrupted. This assumption has a performance
-advantage, but can result in crashes or inconsistent behaviour in the
-case of a corrupted file. Generally, you should set @trusted to
-%TRUE for files installed by the system and to %FALSE for files in
-the home directory.
+If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
+corrupted. This assumption has a performance advantage, but can result
+in crashes or inconsistent behaviour in the case of a corrupted file.
+Generally, you should set @trusted to %TRUE for files installed by the
+system and to %FALSE for files in the home directory.
If @parent is non-%NULL then there are two effects.
@@ -52852,8 +52949,8 @@ First, if g_settings_schema_source_lookup() is called with the
source, the lookup will recurse to the parent.
Second, any references to other schemas specified within this
-source (ie: <literal>child</literal> or <literal>extends</literal>)
-references may be resolved from the @parent.
+source (ie: `child` or `extends`) references may be resolved
+from the @parent.
For this second reason, except in very unusual situations, the
@parent should probably be given as the default schema source, as
@@ -53662,9 +53759,9 @@ is needed to complete the call.
<function name="g_simple_async_result_complete_in_idle">
<description>
-Completes an asynchronous function in an idle handler in the <link
-linkend="g-main-context-push-thread-default">thread-default main
-loop</link> of the thread that @simple was initially created in
+Completes an asynchronous function in an idle handler in the
+[thread-default main context][g-main-context-push-thread-default]
+of the thread that @simple was initially created in
(and re-pushes that context around the invocation of the callback).
Calling this function takes a reference to @simple for as long as
@@ -53753,12 +53850,12 @@ operation is consistent. Three checks are performed.
First, @result is checked to ensure that it is really a
#GSimpleAsyncResult. Second, @source is checked to ensure that it
matches the source object of @result. Third, @source_tag is
-checked to ensure that it is either %NULL (as it is when the result was
-created by g_simple_async_report_error_in_idle() or
-g_simple_async_report_gerror_in_idle()) or equal to the
- source_tag argument given to g_simple_async_result_new() (which, by
-convention, is a pointer to the _async function corresponding to the
-_finish function from which this function is called).
+checked to ensure that it is equal to the @source_tag argument given
+to g_simple_async_result_new() (which, by convention, is a pointer
+to the _async function corresponding to the _finish function from
+which this function is called). (Alternatively, if either
+ source_tag or @result's source tag is %NULL, then the source tag
+check is skipped.)
Since: 2.20
@@ -54230,7 +54327,7 @@ to not use a proxy for.
</parameter_description>
</parameter>
</parameters>
-<return> a new #GSimpleProxyResolver
+<return> (transfer full) a new #GSimpleProxyResolver
</return>
</function>
@@ -54241,10 +54338,9 @@ Sets the default proxy on @resolver, to be used for any URIs that
don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
via g_simple_proxy_resolver_set_uri_proxy().
-If @default_proxy starts with "<literal>socks://</literal>",
+If @default_proxy starts with "socks://",
#GSimpleProxyResolver will treat it as referring to all three of
-the <literal>socks5</literal>, <literal>socks4a</literal>, and
-<literal>socks4</literal> proxy types.
+the socks5, socks4a, and socks4 proxy types.
Since: 2.36
@@ -54293,9 +54389,8 @@ matches @uri_scheme (and which don't match
#GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
-"<literal>socks://</literal>", #GSimpleProxyResolver will treat it
-as referring to all three of the <literal>socks5</literal>,
-<literal>socks4a</literal>, and <literal>socks4</literal> proxy
+"socks://", #GSimpleProxyResolver will treat it
+as referring to all three of the socks5, socks4a, and socks4 proxy
types.
Since: 2.36
@@ -54463,14 +54558,14 @@ Since: 2.22
</parameter_description>
</parameter>
</parameters>
-<return> the socket family type of @address.
+<return> the socket family type of @address
</return>
</function>
<function name="g_socket_address_get_native_size">
<description>
-Gets the size of @address's native <type>struct sockaddr</type>.
+Gets the size of @address's native struct sockaddr.
You can use this to allocate memory to pass to
g_socket_address_to_native().
@@ -54483,7 +54578,7 @@ Since: 2.22
</parameter_description>
</parameter>
</parameters>
-<return> the size of the native <type>struct sockaddr</type> that
+<return> the size of the native struct sockaddr that
@address represents
</return>
@@ -54492,14 +54587,14 @@ Since: 2.22
<function name="g_socket_address_new_from_native">
<description>
Creates a #GSocketAddress subclass corresponding to the native
-<type>struct sockaddr</type> @native.
+struct sockaddr @native.
Since: 2.22
</description>
<parameters>
<parameter name="native">
-<parameter_description> a pointer to a <type>struct sockaddr</type>
+<parameter_description> a pointer to a struct sockaddr
</parameter_description>
</parameter>
<parameter name="len">
@@ -54507,20 +54602,19 @@ Since: 2.22
</parameter_description>
</parameter>
</parameters>
-<return> a new #GSocketAddress if @native could successfully be converted,
-otherwise %NULL.
+<return> a new #GSocketAddress if @native could successfully
+be converted, otherwise %NULL
</return>
</function>
<function name="g_socket_address_to_native">
<description>
-Converts a #GSocketAddress to a native <type>struct
-sockaddr</type>, which can be passed to low-level functions like
-connect() or bind().
+Converts a #GSocketAddress to a native struct sockaddr, which can
+be passed to low-level functions like connect() or bind().
-If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
-returned. If the address type is not known on the system
+If not enough space is available, a %G_IO_ERROR_NO_SPACE error
+is returned. If the address type is not known on the system
then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
Since: 2.22
@@ -54533,16 +54627,16 @@ Since: 2.22
</parameter>
<parameter name="dest">
<parameter_description> a pointer to a memory location that will contain the native
-<type>struct sockaddr</type>.
+struct sockaddr
</parameter_description>
</parameter>
<parameter name="destlen">
<parameter_description> the size of @dest. Must be at least as large as
-g_socket_address_get_native_size().
+g_socket_address_get_native_size()
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> #GError for error reporting, or %NULL to ignore.
+<parameter_description> #GError for error reporting, or %NULL to ignore
</parameter_description>
</parameter>
</parameters>
@@ -54563,12 +54657,12 @@ In certain situations, you may also want to bind a socket that will be
used to initiate connections, though this is not normally required.
If @socket is a TCP socket, then @allow_reuse controls the setting
-of the <literal>SO_REUSEADDR</literal> socket option; normally it
-should be %TRUE for server sockets (sockets that you will
-eventually call g_socket_accept() on), and %FALSE for client
-sockets. (Failing to set this flag on a server socket may cause
-g_socket_bind() to return %G_IO_ERROR_ADDRESS_IN_USE if the server
-program is stopped and then immediately restarted.)
+of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
+server sockets (sockets that you will eventually call
+g_socket_accept() on), and %FALSE for client sockets. (Failing to
+set this flag on a server socket may cause g_socket_bind() to return
+%G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
+immediately restarted.)
If @socket is a UDP socket, then @allow_reuse determines whether or
not other UDP sockets can be bound to the same address at the same
@@ -55805,7 +55899,7 @@ Since: 2.22
<function name="g_socket_connectable_proxy_enumerate">
<description>
Creates a #GSocketAddressEnumerator for @connectable that will
-return #GProxyAddress<!-- -->es for addresses that you must connect
+return #GProxyAddresses for addresses that you must connect
to via a proxy.
If @connectable does not implement
@@ -56211,7 +56305,7 @@ Since: 2.22
<function name="g_socket_create_source">
<description>
Creates a %GSource that can be attached to a %GMainContext to monitor
-for the availibility of the specified @condition on the socket.
+for the availability of the specified @condition on the socket.
The callback on the source is of the #GSocketSourceFunc type.
@@ -56500,11 +56594,10 @@ Since: 2.32
<function name="g_socket_get_option">
<description>
Gets the value of an integer-valued option on @socket, as with
-<literal>getsockopt ()</literal>. (If you need to fetch a
-non-integer-valued option, you will need to call
-<literal>getsockopt ()</literal> directly.)
+getsockopt(). (If you need to fetch a non-integer-valued option,
+you will need to call getsockopt() directly.)
-The <link
linkend="gio-gnetworking.h"><literal><gio/gnetworking.h></literal></link>
+The [<gio/gnetworking.h>][gio-gnetworking.h]
header pulls in system headers that will define most of the
standard/portable socket options. For unusual socket protocols or
platform-dependent options, you may need to include additional
@@ -56523,11 +56616,11 @@ Since: 2.36
</parameter_description>
</parameter>
<parameter name="level">
-<parameter_description> the "API level" of the option (eg,
<literal>SOL_SOCKET</literal>)
+<parameter_description> the "API level" of the option (eg, `SOL_SOCKET`)
</parameter_description>
</parameter>
<parameter name="optname">
-<parameter_description> the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
+<parameter_description> the "name" of the option (eg, `SO_BROADCAST`)
</parameter_description>
</parameter>
<parameter name="value">
@@ -56540,9 +56633,8 @@ Since: 2.36
</parameter>
</parameters>
<return> success or failure. On failure, @error will be set, and
-the system error value (<literal>errno</literal> or
-<literal>WSAGetLastError ()</literal>) will still be set to the
-result of the <literal>getsockopt ()</literal> call.
+the system error value (`errno` or WSAGetLastError()) will still
+be set to the result of the getsockopt() call.
</return>
</function>
@@ -57620,7 +57712,7 @@ If @address is %NULL then the message is sent to the default receiver
then @vectors is assumed to be terminated by a #GOutputVector with a
%NULL buffer pointer.) The #GOutputVector structs describe the buffers
that the sent data will be gathered from. Using multiple
-#GOutputVector<!-- -->s is more memory-efficient than manually copying
+#GOutputVectors is more memory-efficient than manually copying
data from multiple sources into a single buffer, and more
network-efficient than making multiple calls to g_socket_send().
@@ -57845,6 +57937,12 @@ from the added sockets when the mainloop runs.
This call is thread-safe, so it may be called from a thread
handling an incoming client request.
+Note that this only stops accepting new connections; it does not
+close the listening sockets, and you can call
+g_socket_service_start() again later to begin listening again. To
+close the listening sockets, call g_socket_listener_close(). (This
+will happen automatically when the #GSocketService is finalized.)
+
Since: 2.22
</description>
@@ -58014,11 +58112,10 @@ Since: 2.32
<function name="g_socket_set_option">
<description>
Sets the value of an integer-valued option on @socket, as with
-<literal>setsockopt ()</literal>. (If you need to set a
-non-integer-valued option, you will need to call
-<literal>setsockopt ()</literal> directly.)
+setsockopt(). (If you need to set a non-integer-valued option,
+you will need to call setsockopt() directly.)
-The <link
linkend="gio-gnetworking.h"><literal><gio/gnetworking.h></literal></link>
+The [<gio/gnetworking.h>][gio-gnetworking.h]
header pulls in system headers that will define most of the
standard/portable socket options. For unusual socket protocols or
platform-dependent options, you may need to include additional
@@ -58033,11 +58130,11 @@ Since: 2.36
</parameter_description>
</parameter>
<parameter name="level">
-<parameter_description> the "API level" of the option (eg,
<literal>SOL_SOCKET</literal>)
+<parameter_description> the "API level" of the option (eg, `SOL_SOCKET`)
</parameter_description>
</parameter>
<parameter name="optname">
-<parameter_description> the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
+<parameter_description> the "name" of the option (eg, `SO_BROADCAST`)
</parameter_description>
</parameter>
<parameter name="value">
@@ -58050,9 +58147,8 @@ Since: 2.36
</parameter>
</parameters>
<return> success or failure. On failure, @error will be set, and
-the system error value (<literal>errno</literal> or
-<literal>WSAGetLastError ()</literal>) will still be set to the
-result of the <literal>setsockopt ()</literal> call.
+the system error value (`errno` or WSAGetLastError()) will still
+be set to the result of the setsockopt() call.
</return>
</function>
@@ -58320,7 +58416,7 @@ Since: 2.22
<description>
Creates a new #GSrvTarget with the given parameters.
-You should not need to use this; normally #GSrvTarget<!-- -->s are
+You should not need to use this; normally #GSrvTargets are
created by #GResolver.
Since: 2.22
@@ -58354,7 +58450,7 @@ Since: 2.22
Finalized a GResource initialized by g_static_resource_init().
This is normally used by code generated by
-<link linkend="glib-compile-resources">glib-compile-resources</link>
+[glib-compile-resources][glib-compile-resources]
and is not typically used by other code.
Since: 2.32
@@ -58374,7 +58470,7 @@ Since: 2.32
Gets the GResource that was registered by a call to g_static_resource_init().
This is normally used by code generated by
-<link linkend="glib-compile-resources">glib-compile-resources</link>
+[glib-compile-resources][glib-compile-resources]
and is not typically used by other code.
Since: 2.32
@@ -58397,7 +58493,7 @@ Initializes a GResource from static data using a
GStaticResource.
This is normally used by code generated by
-<link linkend="glib-compile-resources">glib-compile-resources</link>
+[glib-compile-resources][glib-compile-resources]
and is not typically used by other code.
Since: 2.32
@@ -59686,10 +59782,8 @@ Since: 2.40
<description>
A utility function for dealing with async operations where you need
to wait for a #GSource to trigger. Attaches @source to @task's
-#GMainContext with @task's <link
-linkend="io-priority">priority</link>, and sets @source's callback
-to @callback, with @task as the callback's
-<literal>user_data</literal>.
+#GMainContext with @task's [priority][io-priority], and sets @source's
+callback to @callback, with @task as the callback's `user_data`.
This takes a reference on @task until @source is destroyed.
@@ -59751,9 +59845,9 @@ Since: 2.36
<function name="g_task_get_context">
<description>
Gets the #GMainContext that @task will return its result in (that
-is, the context that was the <link
-linkend="g-main-context-push-thread-default">thread-default main
-context</link> at the point when @task was created).
+is, the context that was the
+[thread-default main context][g-main-context-push-thread-default]
+at the point when @task was created).
This will always return a non-%NULL value, even if the task's
context is the default #GMainContext.
@@ -59846,7 +59940,7 @@ Since: 2.36
<function name="g_task_get_task_data">
<description>
-Gets @task's <literal>task_data</literal>.
+Gets @task's `task_data`.
Since: 2.36
@@ -59857,7 +59951,7 @@ Since: 2.36
</parameter_description>
</parameter>
</parameters>
-<return> @task's <literal>task_data</literal>.
+<return> @task's `task_data`.
</return>
</function>
@@ -59909,9 +60003,8 @@ if not
<function name="g_task_new">
<description>
Creates a #GTask acting on @source_object, which will eventually be
-used to invoke @callback in the current <link
-linkend="g-main-context-push-thread-default">thread-default main
-context</link>.
+used to invoke @callback in the current
+[thread-default main context][g-main-context-push-thread-default].
Call this in the "start" method of your asynchronous method, and
pass the #GTask around throughout the asynchronous operation. You
@@ -60339,7 +60432,7 @@ to get the result of @task_func.
See #GTaskThreadFunc for more details about how @task_func is handled.
Normally this is used with tasks created with a %NULL
-<literal>callback</literal>, but note that even if the task does
+`callback`, but note that even if the task does
have a callback, it will not be invoked when @task_func returns.
Since: 2.36
@@ -60411,8 +60504,7 @@ Since: 2.36
</parameter_description>
</parameter>
<parameter name="priority">
-<parameter_description> the <link linkend="io-priority">priority</link>
-of the request.
+<parameter_description> the [priority][io-priority] of the request
</parameter_description>
</parameter>
</parameters>
@@ -60751,10 +60843,8 @@ must be called after g_test_run().
<description>
Append a name to the list of icons from within @icon.
-<note><para>
Note that doing so invalidates the hash computed by prior calls
to g_icon_hash().
-</para></note>
</description>
<parameters>
@@ -60829,7 +60919,7 @@ Creates a new themed icon for @iconname, and all the names
that can be created by shortening @iconname at '-' characters.
In the following example, @icon1 and @icon2 are equivalent:
-|[
+|[<!-- language="C" -->
const char *names[] = {
"gnome-dev-cdrom-audio",
"gnome-dev-cdrom",
@@ -60857,10 +60947,8 @@ icon2 = g_themed_icon_new_with_default_fallbacks ("gnome-dev-cdrom-audio&qu
<description>
Prepend a name to the list of icons from within @icon.
-<note><para>
Note that doing so invalidates the hash computed by prior calls
to g_icon_hash().
-</para></note>
Since: 2.18
@@ -61073,7 +61161,7 @@ Since: 2.34
<function name="g_tls_certificate_list_new_from_file">
<description>
-Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
+Creates one or more #GTlsCertificates from the PEM-encoded
data in @file. If @file cannot be read or parsed, the function will
return %NULL and set @error. If @file does not contain any
PEM-encoded certificates, this will return an empty list and not
@@ -61658,8 +61746,7 @@ Since: 2.28
</parameter_description>
</parameter>
<parameter name="io_priority">
-<parameter_description> the <link linkend="io-priority">I/O priority</link>
-of the request.
+<parameter_description> the [I/O priority][io-priority] of the request
</parameter_description>
</parameter>
<parameter name="cancellable">
@@ -61807,16 +61894,16 @@ if the client attempts to rehandshake.)
%G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
rehandshake only if the other end of the connection supports the
-TLS <literal>renegotiation_info</literal> extension. This is the
-default behavior, but means that rehandshaking will not work
-against older implementations that do not support that extension.
+TLS `renegotiation_info` extension. This is the default behavior,
+but means that rehandshaking will not work against older
+implementations that do not support that extension.
%G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
-rehandshaking even without the
-<literal>renegotiation_info</literal> extension. On the server side
-in particular, this is not recommended, since it leaves the server
-open to certain attacks. However, this mode is necessary if you
-need to allow renegotiation with older client software.
+rehandshaking even without the `renegotiation_info` extension. On
+the server side in particular, this is not recommended, since it
+leaves the server open to certain attacks. However, this mode is
+necessary if you need to allow renegotiation with older client
+software.
Since: 2.28
@@ -63840,8 +63927,7 @@ casual user.
</description>
<parameters>
<parameter name="mount_path">
-<parameter_description> a mount path, e.g. <filename>/media/disk</filename>
-or <filename>/usr</filename>
+<parameter_description> a mount path, e.g. `/media/disk` or `/usr`
</parameter_description>
</parameter>
</parameters>
@@ -64638,7 +64724,7 @@ rest of the path will be padded with 0 bytes, and the entire
zero-padded buffer will be considered the name. (As above, if
@path_len is -1, then @path is assumed to be NUL-terminated.) In
this case, g_socket_address_get_native_size() will always return
-the full size of a <literal>struct sockaddr_un</literal>, although
+the full size of a `struct sockaddr_un`, although
g_unix_socket_address_get_path_len() will still return just the
length of @path.
@@ -64806,11 +64892,11 @@ Checks if a volume can be ejected.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the @volume can be ejected. %FALSE otherwise.
+<return> %TRUE if the @volume can be ejected. %FALSE otherwise
</return>
</function>
@@ -64822,11 +64908,11 @@ Checks if a volume can be mounted.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the @volume can be mounted. %FALSE otherwise.
+<return> %TRUE if the @volume can be mounted. %FALSE otherwise
</return>
</function>
@@ -64841,7 +64927,7 @@ Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
<parameter name="flags">
@@ -64849,11 +64935,11 @@ Deprecated: 2.22: Use g_volume_eject_with_operation() instead.
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> optional #GCancellable object, %NULL to ignore.
+<parameter_description> optional #GCancellable object, %NULL to ignore
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> a #GAsyncReadyCallback, or %NULL.
+<parameter_description> a #GAsyncReadyCallback, or %NULL
</parameter_description>
</parameter>
<parameter name="user_data">
@@ -64874,11 +64960,11 @@ Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> pointer to a #GVolume.
+<parameter_description> pointer to a #GVolume
</parameter_description>
</parameter>
<parameter name="result">
-<parameter_description> a #GAsyncResult.
+<parameter_description> a #GAsyncResult
</parameter_description>
</parameter>
<parameter name="error">
@@ -64886,7 +64972,7 @@ Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE, %FALSE if operation failed.
+<return> %TRUE, %FALSE if operation failed
</return>
</function>
@@ -64902,7 +64988,7 @@ Since: 2.22
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
<parameter name="flags">
@@ -64911,19 +64997,19 @@ Since: 2.22
</parameter>
<parameter name="mount_operation">
<parameter_description> a #GMountOperation or %NULL to
-avoid user interaction.
+avoid user interaction
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> optional #GCancellable object, %NULL to ignore.
+<parameter_description> optional #GCancellable object, %NULL to ignore
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> a #GAsyncReadyCallback, or %NULL.
+<parameter_description> a #GAsyncReadyCallback, or %NULL
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> user data passed to @callback.
+<parameter_description> user data passed to @callback
</parameter_description>
</parameter>
</parameters>
@@ -64940,29 +65026,27 @@ Since: 2.22
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
<parameter name="result">
-<parameter_description> a #GAsyncResult.
+<parameter_description> a #GAsyncResult
</parameter_description>
</parameter>
<parameter name="error">
-<parameter_description> a #GError location to store the error occurring, or %NULL to
-ignore.
+<parameter_description> a #GError location to store the error occurring, or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the volume was successfully ejected. %FALSE otherwise.
+<return> %TRUE if the volume was successfully ejected. %FALSE otherwise
</return>
</function>
<function name="g_volume_enumerate_identifiers">
<description>
-Gets the kinds of <link linkend="volume-identifier">identifiers</link>
-that @volume has. Use g_volume_get_identifier() to obtain
-the identifiers themselves.
+Gets the kinds of [identifiers][volume-identifier] that @volume has.
+Use g_volume_get_identifier() to obtain the identifiers themselves.
</description>
@@ -64986,23 +65070,20 @@ is mounted, then the result of g_mount_get_root() on the
either be equal or a prefix of what this function returns. In
other words, in code
-<programlisting>
+|[<!-- language="C" -->
GMount *mount;
GFile *mount_root
GFile *volume_activation_root;
-mount = g_volume_get_mount (volume); / * mounted, so never NULL * /
+mount = g_volume_get_mount (volume); // mounted, so never NULL
mount_root = g_mount_get_root (mount);
-volume_activation_root = g_volume_get_activation_root(volume); / * assume not NULL * /
-</programlisting>
-
+volume_activation_root = g_volume_get_activation_root (volume); // assume not NULL
+]|
then the expression
-
-<programlisting>
+|[<!-- language="C" -->
(g_file_has_prefix (volume_activation_root, mount_root) ||
g_file_equal (volume_activation_root, mount_root))
-</programlisting>
-
+]|
will always be %TRUE.
Activation roots are typically used in #GVolumeMonitor
@@ -65032,13 +65113,13 @@ Gets the drive for the @volume.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
-<return> a #GDrive or %NULL if @volume is not associated with a drive.
-The returned object should be unreffed with g_object_unref()
-when no longer needed.
+<return> a #GDrive or %NULL if @volume is not
+associated with a drive. The returned object should be unreffed
+with g_object_unref() when no longer needed.
</return>
</function>
@@ -65050,7 +65131,7 @@ Gets the icon for @volume.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
@@ -65063,8 +65144,8 @@ when no longer needed.
<function name="g_volume_get_identifier">
<description>
Gets the identifier of the given kind for @volume.
-See the <link linkend="volume-identifier">introduction</link>
-for more information about volume identifiers.
+See the [introduction][volume-identifier] for more
+information about volume identifiers.
</description>
@@ -65092,7 +65173,7 @@ Gets the mount for the @volume.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
@@ -65110,7 +65191,7 @@ Gets the name of @volume.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
@@ -65128,11 +65209,11 @@ Since: 2.32
</description>
<parameters>
<parameter name="volume">
-<parameter_description> A #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
-<return> Sorting key for @volume or %NULL if no such key is available.
+<return> Sorting key for @volume or %NULL if no such key is available
</return>
</function>
@@ -65146,7 +65227,7 @@ Since: 2.34
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
@@ -65168,7 +65249,7 @@ available.
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
</parameters>
@@ -65351,7 +65432,7 @@ Virtual: mount_fn
</description>
<parameters>
<parameter name="volume">
-<parameter_description> a #GVolume.
+<parameter_description> a #GVolume
</parameter_description>
</parameter>
<parameter name="flags">
@@ -65359,15 +65440,15 @@ Virtual: mount_fn
</parameter_description>
</parameter>
<parameter name="mount_operation">
-<parameter_description> a #GMountOperation or %NULL to avoid user interaction.
+<parameter_description> a #GMountOperation or %NULL to avoid user interaction
</parameter_description>
</parameter>
<parameter name="cancellable">
-<parameter_description> optional #GCancellable object, %NULL to ignore.
+<parameter_description> optional #GCancellable object, %NULL to ignore
</parameter_description>
</parameter>
<parameter name="callback">
-<parameter_description> a #GAsyncReadyCallback, or %NULL.
+<parameter_description> a #GAsyncReadyCallback, or %NULL
</parameter_description>
</parameter>
<parameter name="user_data">
@@ -65404,7 +65485,7 @@ function; there's no need to listen for the 'mount-added' signal on
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE, %FALSE if operation failed.
+<return> %TRUE, %FALSE if operation failed
</return>
</function>
@@ -65420,7 +65501,7 @@ Returns whether the volume should be automatically mounted.
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the volume should be automatically mounted.
+<return> %TRUE if the volume should be automatically mounted
</return>
</function>
diff --git a/glib/src/glib_docs.xml b/glib/src/glib_docs.xml
index b3ea739..2c949a0 100644
--- a/glib/src/glib_docs.xml
+++ b/glib/src/glib_docs.xml
@@ -694,15 +694,14 @@ g_io_channel_set_flags().
</description>
<parameters>
<parameter name="G_IO_FLAG_APPEND">
-<parameter_description> turns on append mode, corresponds to <literal>O_APPEND</literal>
-(see the documentation of the UNIX open()
-syscall).
+<parameter_description> turns on append mode, corresponds to %O_APPEND
+(see the documentation of the UNIX open() syscall)
</parameter_description>
</parameter>
<parameter name="G_IO_FLAG_NONBLOCK">
<parameter_description> turns on nonblocking mode, corresponds to
-<literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal>
-(see the documentation of the UNIX open() syscall).
+%O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
+syscall)
</parameter_description>
</parameter>
<parameter name="G_IO_FLAG_IS_READABLE">
@@ -713,12 +712,15 @@ This flag cannot be changed.
<parameter name="G_IO_FLAG_IS_WRITABLE">
<parameter_description> indicates that the io channel is writable.
This flag cannot be changed.
+G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
+that existed before the spelling was fixed in GLib 2.30. It is kept
+here for compatibility reasons. Deprecated since 2.30
</parameter_description>
</parameter>
<parameter name="G_IO_FLAG_IS_SEEKABLE">
<parameter_description> indicates that the io channel is seekable,
-i.e. that g_io_channel_seek_position() can
-be used on it. This flag cannot be changed.
+i.e. that g_io_channel_seek_position() can be used on it.
+This flag cannot be changed.
</parameter_description>
</parameter>
<parameter name="G_IO_FLAG_MASK">
@@ -727,12 +729,12 @@ be used on it. This flag cannot be changed.
</parameter>
<parameter name="G_IO_FLAG_GET_MASK">
<parameter_description> the mask of the flags that are returned from
-g_io_channel_get_flags().
+g_io_channel_get_flags()
</parameter_description>
</parameter>
<parameter name="G_IO_FLAG_SET_MASK">
<parameter_description> the mask of the flags that the user can modify
-with g_io_channel_set_flags().
+with g_io_channel_set_flags()
</parameter_description>
</parameter>
</parameters>
@@ -1095,13 +1097,13 @@ is called to reinstate the previous value.
This signal is typically used to obtain change notification for a
single property, by specifying the property name as a detail in the
g_signal_connect() call, like this:
-|[
+|[<!-- language="C" -->
g_signal_connect (text_view->buffer, "notify::paste-target-list",
G_CALLBACK (gtk_text_view_target_list_notify),
text_view)
]|
It is important to note that you must use
-<link linkend="canonical-parameter-name">canonical</link> parameter names as
+[canonical][canonical-parameter-name] parameter names as
detail strings for the notify signal.
</description>
@@ -2169,9 +2171,9 @@ These two options correspond rather directly to the 'dist' and
'built' terminology that automake uses and are explicitly used to
distinguish between the 'srcdir' and 'builddir' being separate. All
files in your project should either be dist (in the
-<literal>DIST_EXTRA</literal> or <literal>dist_schema_DATA</literal>
+`DIST_EXTRA` or `dist_schema_DATA`
sense, in which case they will always be in the srcdir) or built (in
-the <literal>BUILT_SOURCES</literal> sense, in which case they will
+the `BUILT_SOURCES` sense, in which case they will
always be in the builddir).
Note: as a general rule of automake, files that are generated only as
@@ -2206,7 +2208,7 @@ not show stdout and stderr.
<parameter name="G_TEST_SUBPROCESS_INHERIT_STDIN">
<parameter_description> If this flag is given, the child
process will inherit the parent's stdin. Otherwise, the child's
-stdin is redirected to <filename>/dev/null</filename>.
+stdin is redirected to `/dev/null`.
</parameter_description>
</parameter>
<parameter name="G_TEST_SUBPROCESS_INHERIT_STDOUT">
@@ -2239,22 +2241,22 @@ which is deprecated. g_test_trap_subprocess() uses
<parameters>
<parameter name="G_TEST_TRAP_SILENCE_STDOUT">
<parameter_description> Redirect stdout of the test child to
-<filename>/dev/null</filename> so it cannot be observed on the
-console during test runs. The actual output is still captured
-though to allow later tests with g_test_trap_assert_stdout().
+`/dev/null` so it cannot be observed on the console during test
+runs. The actual output is still captured though to allow later
+tests with g_test_trap_assert_stdout().
</parameter_description>
</parameter>
<parameter name="G_TEST_TRAP_SILENCE_STDERR">
<parameter_description> Redirect stderr of the test child to
-<filename>/dev/null</filename> so it cannot be observed on the
-console during test runs. The actual output is still captured
-though to allow later tests with g_test_trap_assert_stderr().
+`/dev/null` so it cannot be observed on the console during test
+runs. The actual output is still captured though to allow later
+tests with g_test_trap_assert_stderr().
</parameter_description>
</parameter>
<parameter name="G_TEST_TRAP_INHERIT_STDIN">
<parameter_description> If this flag is given, stdin of the
child process is shared with stdin of its parent process.
-It is redirected to <filename>/dev/null</filename> otherwise.
+It is redirected to `/dev/null` otherwise.
</parameter_description>
</parameter>
</parameters>
@@ -2470,7 +2472,16 @@ version use %G_TRAVERSE_NON_LEAFS.
<enum name="GTraverseType">
<description>
Specifies the type of traveral performed by g_tree_traverse(),
-g_node_traverse() and g_node_find().
+g_node_traverse() and g_node_find(). The different orders are
+illustrated here:
+- In order: A, B, C, D, E, F, G, H, I
+
+- Pre order: F, B, A, D, C, E, G, I, H
+
+- Post order: A, C, E, D, B, H, I, G, F
+
+- Level order: F, B, G, A, D, I, C, E, H
+
</description>
<parameters>
@@ -2490,10 +2501,9 @@ function.
</parameter_description>
</parameter>
<parameter name="G_LEVEL_ORDER">
-<parameter_description> is not implemented for <link
-linkend="glib-Balanced-Binary-Trees">Balanced Binary
-Trees</link>. For <link
-linkend="glib-N-ary-Trees">N-ary Trees</link>, it
+<parameter_description> is not implemented for
+[balanced binary trees][glib-Balanced-Binary-Trees].
+For [n-ary trees][glib-N-ary-Trees], it
vists the root node first, then its children, then
its grandchildren, and so on. Note that this is less
efficient than the other orders.
@@ -3578,8 +3588,8 @@ Since: 2.8
</parameter>
</parameters>
<return> zero if the pathname refers to an existing file system
-object that has all the tested permissions, or -1 otherwise or on
-error.
+object that has all the tested permissions, or -1 otherwise
+or on error.
</return>
</function>
@@ -3635,23 +3645,23 @@ not upon exit of the enclosing function scope.
Adds the value on to the end of the array. The array will grow in
size automatically if necessary.
-<note><para>g_array_append_val() is a macro which uses a reference
-to the value parameter @v. This means that you cannot use it with
-literal values such as "27". You must use variables.</para></note>
+g_array_append_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
</description>
<parameters>
<parameter name="a">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="v">
-<parameter_description> the value to append to the #GArray.
+<parameter_description> the value to append to the #GArray
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3663,19 +3673,19 @@ Adds @len elements onto the end of the array.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> a pointer to the elements to append to the end of the array.
+<parameter_description> a pointer to the elements to append to the end of the array
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the number of elements to append.
+<parameter_description> the number of elements to append
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3689,23 +3699,23 @@ underlying array for use elsewhere. If the reference count of @array
is greater than one, the #GArray wrapper is preserved but the size
of @array will be set to zero.
-<note><para>If array elements contain dynamically-allocated memory,
-they should be freed separately.</para></note>
+If array elements contain dynamically-allocated memory, they should
+be freed separately.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="free_segment">
-<parameter_description> if %TRUE the actual element data is freed as well.
+<parameter_description> if %TRUE the actual element data is freed as well
</parameter_description>
</parameter>
</parameters>
<return> the element data if @free_segment is %FALSE, otherwise
-%NULL. The element data should be freed using g_free().
+%NULL. The element data should be freed using g_free().
</return>
</function>
@@ -3718,11 +3728,11 @@ Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GArray.
+<parameter_description> A #GArray
</parameter_description>
</parameter>
</parameters>
-<return> Size of each element, in bytes.
+<return> Size of each element, in bytes
</return>
</function>
@@ -3732,33 +3742,31 @@ Since: 2.22
Returns the element of a #GArray at the given index. The return
value is cast to the given type.
-<example>
-<title>Getting a pointer to an element in a #GArray</title>
-<programlisting>
+This example gets a pointer to an element in a #GArray:
+|[<!-- language="C" -->
EDayViewEvent *event;
-/<!-- -->* This gets a pointer to the 4th element
-in the array of EDayViewEvent structs. *<!-- -->/
+// This gets a pointer to the 4th element in the array of
+// EDayViewEvent structs.
event = &g_array_index (events, EDayViewEvent, 3);
-</programlisting>
-</example>
+]|
</description>
<parameters>
<parameter name="a">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="t">
-<parameter_description> the type of the elements.
+<parameter_description> the type of the elements
</parameter_description>
</parameter>
<parameter name="i">
-<parameter_description> the index of the element to return.
+<parameter_description> the index of the element to return
</parameter_description>
</parameter>
</parameters>
-<return> the element of the #GArray at the index given by @i.
+<return> the element of the #GArray at the index given by @i
</return>
</function>
@@ -3766,27 +3774,27 @@ event = &g_array_index (events, EDayViewEvent, 3);
<description>
Inserts an element into an array at the given index.
-<note><para>g_array_insert_val() is a macro which uses a reference
-to the value parameter @v. This means that you cannot use it with
-literal values such as "27". You must use variables.</para></note>
+g_array_insert_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
</description>
<parameters>
<parameter name="a">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="i">
-<parameter_description> the index to place the element at.
+<parameter_description> the index to place the element at
</parameter_description>
</parameter>
<parameter name="v">
-<parameter_description> the value to insert into the array.
+<parameter_description> the value to insert into the array
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3798,23 +3806,23 @@ Inserts @len elements into a #GArray at the given index.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index to place the elements at.
+<parameter_description> the index to place the elements at
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> a pointer to the elements to insert.
+<parameter_description> a pointer to the elements to insert
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the number of elements to insert.
+<parameter_description> the number of elements to insert
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3827,20 +3835,20 @@ Creates a new #GArray with a reference count of 1.
<parameters>
<parameter name="zero_terminated">
<parameter_description> %TRUE if the array should have an extra element at
-the end which is set to 0.
+the end which is set to 0
</parameter_description>
</parameter>
<parameter name="clear_">
<parameter_description> %TRUE if #GArray elements should be automatically cleared
-to 0 when they are allocated.
+to 0 when they are allocated
</parameter_description>
</parameter>
<parameter name="element_size">
-<parameter_description> the size of each element in bytes.
+<parameter_description> the size of each element in bytes
</parameter_description>
</parameter>
</parameters>
-<return> the new #GArray.
+<return> the new #GArray
</return>
</function>
@@ -3853,23 +3861,23 @@ This operation is slower than g_array_append_val() since the
existing elements in the array have to be moved to make space for
the new element.
-<note><para>g_array_prepend_val() is a macro which uses a reference
-to the value parameter @v. This means that you cannot use it with
-literal values such as "27". You must use variables.</para></note>
+g_array_prepend_val() is a macro which uses a reference to the value
+parameter @v. This means that you cannot use it with literal values
+such as "27". You must use variables.
</description>
<parameters>
<parameter name="a">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="v">
-<parameter_description> the value to prepend to the #GArray.
+<parameter_description> the value to prepend to the #GArray
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3885,38 +3893,37 @@ the new elements.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> a pointer to the elements to prepend to the start of the
-array.
+<parameter_description> a pointer to the elements to prepend to the start of the array
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the number of elements to prepend.
+<parameter_description> the number of elements to prepend
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
<function name="g_array_ref">
<description>
-Atomically increments the reference count of @array by one. This
-function is MT-safe and may be called from any thread.
+Atomically increments the reference count of @array by one.
+This function is MT-safe and may be called from any thread.
Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GArray.
+<parameter_description> A #GArray
</parameter_description>
</parameter>
</parameters>
-<return> The passed in #GArray.
+<return> The passed in #GArray
</return>
</function>
@@ -3930,15 +3937,15 @@ elements are moved down one place.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the element to remove.
+<parameter_description> the index of the element to remove
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3953,15 +3960,15 @@ g_array_remove_index().
</description>
<parameters>
<parameter name="array">
-<parameter_description> a @GArray.
+<parameter_description> a @GArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the element to remove.
+<parameter_description> the index of the element to remove
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -3975,19 +3982,19 @@ Since: 2.4
</description>
<parameters>
<parameter name="array">
-<parameter_description> a @GArray.
+<parameter_description> a @GArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the first element to remove.
+<parameter_description> the index of the first element to remove
</parameter_description>
</parameter>
<parameter name="length">
-<parameter_description> the number of elements to remove.
+<parameter_description> the number of elements to remove
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -4029,15 +4036,15 @@ was created with @clear_ set to %TRUE, the new elements are set to 0.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="length">
-<parameter_description> the new size of the #GArray.
+<parameter_description> the new size of the #GArray
</parameter_description>
</parameter>
</parameters>
-<return> the #GArray.
+<return> the #GArray
</return>
</function>
@@ -4053,24 +4060,24 @@ size of the array is still 0.
<parameters>
<parameter name="zero_terminated">
<parameter_description> %TRUE if the array should have an extra element at
-the end with all bits cleared.
+the end with all bits cleared
</parameter_description>
</parameter>
<parameter name="clear_">
<parameter_description> %TRUE if all bits in the array should be cleared to 0 on
-allocation.
+allocation
</parameter_description>
</parameter>
<parameter name="element_size">
-<parameter_description> size of each element in the array.
+<parameter_description> size of each element in the array
</parameter_description>
</parameter>
<parameter name="reserved_size">
-<parameter_description> number of elements preallocated.
+<parameter_description> number of elements preallocated
</parameter_description>
</parameter>
</parameters>
-<return> the new #GArray.
+<return> the new #GArray
</return>
</function>
@@ -4086,11 +4093,11 @@ This is guaranteed to be a stable sort since version 2.32.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="compare_func">
-<parameter_description> comparison function.
+<parameter_description> comparison function
</parameter_description>
</parameter>
</parameters>
@@ -4111,15 +4118,15 @@ This did not actually work, so any such code should be removed.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GArray.
+<parameter_description> a #GArray
</parameter_description>
</parameter>
<parameter name="compare_func">
-<parameter_description> comparison function.
+<parameter_description> comparison function
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> data to pass to @compare_func.
+<parameter_description> data to pass to @compare_func
</parameter_description>
</parameter>
</parameters>
@@ -4138,7 +4145,7 @@ Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GArray.
+<parameter_description> A #GArray
</parameter_description>
</parameter>
</parameters>
@@ -4147,21 +4154,20 @@ Since: 2.22
<function name="g_ascii_digit_value">
<description>
-Determines the numeric value of a character as a decimal
-digit. Differs from g_unichar_digit_value() because it takes
-a char, so there's no worry about sign extension if characters
-are signed.
+Determines the numeric value of a character as a decimal digit.
+Differs from g_unichar_digit_value() because it takes a char, so
+there's no worry about sign extension if characters are signed.
</description>
<parameters>
<parameter name="c">
-<parameter_description> an ASCII character.
+<parameter_description> an ASCII character
</parameter_description>
</parameter>
</parameters>
-<return> If @c is a decimal digit (according to
-g_ascii_isdigit()), its numeric value. Otherwise, -1.
+<return> If @c is a decimal digit (according to g_ascii_isdigit()),
+its numeric value. Otherwise, -1.
</return>
</function>
@@ -4238,9 +4244,9 @@ Determines whether a character is alphanumeric.
Unlike the standard C library isalnum() function, this only
recognizes standard ASCII letters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
-cast to #guchar before passing a possibly non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
</description>
@@ -4261,9 +4267,9 @@ Determines whether a character is alphabetic (i.e. a letter).
Unlike the standard C library isalpha() function, this only
recognizes standard ASCII letters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
-cast to #guchar before passing a possibly non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
</description>
@@ -4284,9 +4290,9 @@ Determines whether a character is a control character.
Unlike the standard C library iscntrl() function, this only
recognizes standard ASCII control characters and ignores the
locale, returning %FALSE for all non-ASCII characters. Also,
-unlike the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
-cast to #guchar before passing a possibly non-ASCII character in.
+unlike the standard library function, this takes a char, not
+an int, so don't call it on %EOF, but no need to cast to #guchar
+before passing a possibly non-ASCII character in.
</description>
@@ -4305,9 +4311,8 @@ cast to #guchar before passing a possibly non-ASCII character in.
Determines whether a character is digit (0-9).
Unlike the standard C library isdigit() function, this takes
-a <type>char</type>, not an <type>int</type>, so don't call it
-on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
-non-ASCII character in.
+a char, not an int, so don't call it on %EOF, but no need to
+cast to #guchar before passing a possibly non-ASCII character in.
</description>
@@ -4328,9 +4333,9 @@ Determines whether a character is a printing character and not a space.
Unlike the standard C library isgraph() function, this only
recognizes standard ASCII characters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
-to cast to #guchar before passing a possibly non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
</description>
@@ -4351,10 +4356,9 @@ Determines whether a character is an ASCII lower case letter.
Unlike the standard C library islower() function, this only
recognizes standard ASCII letters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
-to worry about casting to #guchar before passing a possibly
-non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to worry about casting
+to #guchar before passing a possibly non-ASCII character in.
</description>
@@ -4375,9 +4379,9 @@ Determines whether a character is a printing character.
Unlike the standard C library isprint() function, this only
recognizes standard ASCII characters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
-to cast to #guchar before passing a possibly non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
</description>
@@ -4398,9 +4402,9 @@ Determines whether a character is a punctuation character.
Unlike the standard C library ispunct() function, this only
recognizes standard ASCII letters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
-cast to #guchar before passing a possibly non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
</description>
@@ -4421,9 +4425,9 @@ Determines whether a character is a white-space character.
Unlike the standard C library isspace() function, this only
recognizes standard ASCII white-space and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
-cast to #guchar before passing a possibly non-ASCII character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to cast to #guchar before
+passing a possibly non-ASCII character in.
</description>
@@ -4444,10 +4448,9 @@ Determines whether a character is an ASCII upper case letter.
Unlike the standard C library isupper() function, this only
recognizes standard ASCII letters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also, unlike
-the standard library function, this takes a <type>char</type>,
-not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
-worry about casting to #guchar before passing a possibly non-ASCII
-character in.
+the standard library function, this takes a char, not an int,
+so don't call it on %EOF, but no need to worry about casting
+to #guchar before passing a possibly non-ASCII character in.
</description>
@@ -4466,9 +4469,8 @@ character in.
Determines whether a character is a hexadecimal-digit character.
Unlike the standard C library isxdigit() function, this takes
-a <type>char</type>, not an <type>int</type>, so don't call it
-on <literal>EOF</literal>, but no need to cast to #guchar before passing a
-possibly non-ASCII character in.
+a char, not an int, so don't call it on %EOF, but no need to
+cast to #guchar before passing a possibly non-ASCII character in.
</description>
@@ -4504,11 +4506,11 @@ Both @s1 and @s2 must be non-%NULL.
</description>
<parameters>
<parameter name="s1">
-<parameter_description> string to compare with @s2.
+<parameter_description> string to compare with @s2
</parameter_description>
</parameter>
<parameter name="s2">
-<parameter_description> string to compare with @s1.
+<parameter_description> string to compare with @s1
</parameter_description>
</parameter>
</parameters>
@@ -4525,19 +4527,18 @@ Converts all upper case ASCII letters to lower case ASCII letters.
</description>
<parameters>
<parameter name="str">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> length of @str in bytes, or -1 if @str is nul-terminated.
+<parameter_description> length of @str in bytes, or -1 if @str is nul-terminated
</parameter_description>
</parameter>
</parameters>
<return> a newly-allocated string, with all the upper case
-characters in @str converted to lower case, with
-semantics that exactly match g_ascii_tolower(). (Note
-that this is unlike the old g_strdown(), which modified
-the string in place.)
+characters in @str converted to lower case, with semantics that
+exactly match g_ascii_tolower(). (Note that this is unlike the
+old g_strdown(), which modified the string in place.)
</return>
</function>
@@ -4558,15 +4559,15 @@ corresponding to ASCII letters always represent themselves.
</description>
<parameters>
<parameter name="s1">
-<parameter_description> string to compare with @s2.
+<parameter_description> string to compare with @s2
</parameter_description>
</parameter>
<parameter name="s2">
-<parameter_description> string to compare with @s1.
+<parameter_description> string to compare with @s1
</parameter_description>
</parameter>
<parameter name="n">
-<parameter_description> number of characters to compare.
+<parameter_description> number of characters to compare
</parameter_description>
</parameter>
</parameters>
@@ -4593,12 +4594,12 @@ locale-sensitive system strtod() function.
To convert from a #gdouble to a string in a locale-insensitive
way, use g_ascii_dtostr().
-If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
-is returned (according to the sign of the value), and <literal>ERANGE</literal> is
-stored in <literal>errno</literal>. If the correct value would cause underflow,
-zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+If the correct value would cause overflow, plus or minus %HUGE_VAL
+is returned (according to the sign of the value), and %ERANGE is
+stored in %errno. If the correct value would cause underflow,
+zero is returned and %ERANGE is stored in %errno.
-This function resets <literal>errno</literal> before calling strtod() so that
+This function resets %errno before calling strtod() so that
you can reliably detect overflow and underflow.
@@ -4632,9 +4633,9 @@ To handle input from the user you should normally use the
locale-sensitive system strtoll() function.
If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
-is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+is returned, and `ERANGE` is stored in `errno`.
If the base is outside the valid range, zero is returned, and
-<literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
+`EINVAL` is stored in `errno`. If the
string conversion fails, zero is returned, and @endptr returns @nptr
(if @endptr is non-%NULL).
@@ -4675,9 +4676,9 @@ To handle input from the user you should normally use the
locale-sensitive system strtoull() function.
If the correct value would cause overflow, %G_MAXUINT64
-is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+is returned, and `ERANGE` is stored in `errno`.
If the base is outside the valid range, zero is returned, and
-<literal>EINVAL</literal> is stored in <literal>errno</literal>.
+`EINVAL` is stored in `errno`.
If the string conversion fails, zero is returned, and @endptr returns
@nptr (if @endptr is non-%NULL).
@@ -4712,19 +4713,18 @@ Converts all lower case ASCII letters to upper case ASCII letters.
</description>
<parameters>
<parameter name="str">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> length of @str in bytes, or -1 if @str is nul-terminated.
+<parameter_description> length of @str in bytes, or -1 if @str is nul-terminated
</parameter_description>
</parameter>
</parameters>
<return> a newly allocated string, with all the lower case
-characters in @str converted to upper case, with
-semantics that exactly match g_ascii_toupper(). (Note
-that this is unlike the old g_strup(), which modified
-the string in place.)
+characters in @str converted to upper case, with semantics that
+exactly match g_ascii_toupper(). (Note that this is unlike the
+old g_strup(), which modified the string in place.)
</return>
</function>
@@ -4737,20 +4737,19 @@ recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
-don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
+don't call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.
</description>
<parameters>
<parameter name="c">
-<parameter_description> any character.
+<parameter_description> any character
</parameter_description>
</parameter>
</parameters>
-<return> the result of converting @c to lower case.
-If @c is not an ASCII upper case letter,
- c is returned unchanged.
+<return> the result of converting @c to lower case. If @c is
+not an ASCII upper case letter, @c is returned unchanged.
</return>
</function>
@@ -4763,20 +4762,19 @@ recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns a char, not an int, so
-don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
+don't call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.
</description>
<parameters>
<parameter name="c">
-<parameter_description> any character.
+<parameter_description> any character
</parameter_description>
</parameter>
</parameters>
-<return> the result of converting @c to upper case.
-If @c is not an ASCII lower case letter,
- c is returned unchanged.
+<return> the result of converting @c to upper case. If @c is not
+an ASCII lower case letter, @c is returned unchanged.
</return>
</function>
@@ -4795,8 +4793,8 @@ are signed.
</parameter_description>
</parameter>
</parameters>
-<return> If @c is a hex digit (according to
-g_ascii_isxdigit()), its numeric value. Otherwise, -1.
+<return> If @c is a hex digit (according to g_ascii_isxdigit()),
+its numeric value. Otherwise, -1.
</return>
</function>
@@ -4807,7 +4805,7 @@ fails. If the assertion fails (i.e. the expression is not true),
an error message is logged and the application is terminated.
The macro can be turned off in final releases of code by defining
-<envar>G_DISABLE_ASSERT</envar> when compiling the application.
+`G_DISABLE_ASSERT` when compiling the application.
</description>
<parameters>
@@ -4823,8 +4821,8 @@ The macro can be turned off in final releases of code by defining
<description>
Debugging macro to compare two floating point numbers.
-The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is
-the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage
+The effect of `g_assert_cmpfloat (n1, op, n2)` is
+the same as `g_assert_true (n1 op n2)`. The advantage
of this macro is that it can produce a message that includes the
actual values of @n1 and @n2.
@@ -4881,8 +4879,8 @@ One of ==, !=, <, >, <=, >=.
<description>
Debugging macro to compare two integers.
-The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is
-the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage
+The effect of `g_assert_cmpint (n1, op, n2)` is
+the same as `g_assert_true (n1 op n2)`. The advantage
of this macro is that it can produce a message that includes the
actual values of @n1 and @n2.
@@ -4914,12 +4912,12 @@ an error message is logged and the application is either terminated
or the testcase marked as failed.
The strings are compared using g_strcmp0().
-The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is
-the same as <literal>g_assert_true (g_strcmp0 (s1, s2) op 0)</literal>.
+The effect of `g_assert_cmpstr (s1, op, s2)` is
+the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`.
The advantage of this macro is that it can produce a message that
includes the actual values of @s1 and @s2.
-|[
+|[<!-- language="C" -->
g_assert_cmpstr (mystring, ==, "fubar");
]|
@@ -4948,8 +4946,8 @@ One of ==, !=, <, >, <=, >=.
<description>
Debugging macro to compare two unsigned integers.
-The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is
-the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage
+The effect of `g_assert_cmpuint (n1, op, n2)` is
+the same as `g_assert_true (n1 op n2)`. The advantage
of this macro is that it can produce a message that includes the
actual values of @n1 and @n2.
@@ -4979,15 +4977,15 @@ One of ==, !=, <, >, <=, >=.
Debugging macro to check that a method has returned
the correct #GError.
-The effect of <literal>g_assert_error (err, dom, c)</literal> is
-the same as <literal>g_assert_true (err != NULL && err->domain
-== dom && err->code == c)</literal>. The advantage of this
+The effect of `g_assert_error (err, dom, c)` is
+the same as `g_assert_true (err != NULL && err->domain
+== dom && err->code == c)`. The advantage of this
macro is that it can produce a message that includes the incorrect
error message and code.
This can only be used to test for a specific error. If you want to
test that @err is set, but don't care what it's set to, just use
-<literal>g_assert (err != NULL)</literal>
+`g_assert (err != NULL)`
Since: 2.20
@@ -5035,8 +5033,8 @@ Since: 2.38
<description>
Debugging macro to check that a #GError is not set.
-The effect of <literal>g_assert_no_error (err)</literal> is
-the same as <literal>g_assert_true (err == NULL)</literal>. The advantage
+The effect of `g_assert_no_error (err)` is
+the same as `g_assert_true (err == NULL)`. The advantage
of this macro is that it can produce a message that includes
the error message and code.
@@ -5081,7 +5079,7 @@ reached. If it is reached, an error message is logged and the
application is terminated.
The macro can be turned off in final releases of code by defining
-<envar>G_DISABLE_ASSERT</envar> when compiling the application.
+`G_DISABLE_ASSERT` when compiling the application.
</description>
<parameters>
@@ -5190,8 +5188,8 @@ becomes available.
Call g_async_queue_unlock() to drop the lock again.
While holding the lock, you can only call the
-<function>g_async_queue_*_unlocked()</function> functions
-on @queue. Otherwise, deadlock may occur.
+g_async_queue_*_unlocked() functions on @queue. Otherwise,
+deadlock may occur.
</description>
<parameters>
@@ -5438,7 +5436,7 @@ it when it is finished.
If you were sorting a list of priority numbers to make sure the
lowest priority would be at the top of the queue, you could use:
-|[
+|[<!-- language="C" -->
gint32 id1;
gint32 id2;
@@ -5756,7 +5754,7 @@ Deprecated:2.32: It is best to avoid g_atexit().
Atomically adds @val to the value of @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic += @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic += val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -5789,7 +5787,7 @@ storing the result back in @atomic.
This call acts as a full compiler and hardware memory barrier.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic &= @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic &= val; return tmp; }`.
Since: 2.30
@@ -5817,7 +5815,7 @@ If @atomic was not equal to @oldval then no change occurs.
This compare and exchange is done atomically.
Think of this operation as an atomic version of
-<literal>{ if (* atomic == @oldval) { * atomic = @newval; return TRUE; } else return FALSE;
}</literal>
+`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -5848,7 +5846,7 @@ Since: 2.4
Decrements the value of @atomic by 1.
Think of this operation as an atomic version of
-<literal>{ * atomic -= 1; return (* atomic == 0); }</literal>
+`{ *atomic -= 1; return (*atomic == 0); }`.
This call acts as a full compiler and hardware memory barrier.
@@ -5915,8 +5913,7 @@ Since: 2.4
<description>
Increments the value of @atomic by 1.
-Think of this operation as an atomic version of
-<literal>{ * atomic += 1; }</literal>
+Think of this operation as an atomic version of `{ *atomic += 1; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -5938,7 +5935,7 @@ Performs an atomic bitwise 'or' of the value of @atomic and @val,
storing the result back in @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic |= @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic |= val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -5989,7 +5986,7 @@ Performs an atomic bitwise 'xor' of the value of @atomic and @val,
storing the result back in @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic ^= @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic ^= val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -6016,7 +6013,7 @@ Since: 2.30
Atomically adds @val to the value of @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic += @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic += val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -6044,7 +6041,7 @@ Performs an atomic bitwise 'and' of the value of @atomic and @val,
storing the result back in @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic &= @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic &= val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -6074,7 +6071,7 @@ If @atomic was not equal to @oldval then no change occurs.
This compare and exchange is done atomically.
Think of this operation as an atomic version of
-<literal>{ if (* atomic == @oldval) { * atomic = @newval; return TRUE; } else return FALSE;
}</literal>
+`{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -6127,7 +6124,7 @@ Performs an atomic bitwise 'or' of the value of @atomic and @val,
storing the result back in @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic |= @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic |= val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -6178,7 +6175,7 @@ Performs an atomic bitwise 'xor' of the value of @atomic and @val,
storing the result back in @atomic.
Think of this operation as an atomic version of
-<literal>{ tmp = *atomic; * atomic ^= @val; return tmp; }</literal>
+`{ tmp = *atomic; *atomic ^= val; return tmp; }`.
This call acts as a full compiler and hardware memory barrier.
@@ -6370,9 +6367,9 @@ non-zero state). If you enable line-breaking you will need at least:
@break_lines is typically used when putting base64-encoded data in emails.
It breaks the lines at 72 columns instead of putting all of the text on
the same line. This avoids problems with long lines in the email system.
-Note however that it breaks the lines with <literal>LF</literal>
-characters, not <literal>CR LF</literal> sequences, so the result cannot
-be passed directly to SMTP or certain other protocols.
+Note however that it breaks the lines with `LF` characters, not
+`CR LF` sequences, so the result cannot be passed directly to SMTP
+or certain other protocols.
Since: 2.12
@@ -6434,7 +6431,7 @@ directory components
<function name="g_binding_get_flags">
<description>
-Retrieves the flags passed when constructing the #GBinding
+Retrieves the flags passed when constructing the #GBinding.
Since: 2.26
@@ -6452,7 +6449,7 @@ Since: 2.26
<function name="g_binding_get_source">
<description>
-Retrieves the #GObject instance used as the source of the binding
+Retrieves the #GObject instance used as the source of the binding.
Since: 2.26
@@ -6471,7 +6468,7 @@ Since: 2.26
<function name="g_binding_get_source_property">
<description>
Retrieves the name of the property of #GBinding:source used as the source
-of the binding
+of the binding.
Since: 2.26
@@ -6489,7 +6486,7 @@ Since: 2.26
<function name="g_binding_get_target">
<description>
-Retrieves the #GObject instance used as the target of the binding
+Retrieves the #GObject instance used as the target of the binding.
Since: 2.26
@@ -6508,7 +6505,7 @@ Since: 2.26
<function name="g_binding_get_target_property">
<description>
Retrieves the name of the property of #GBinding:target used as the target
-of the binding
+of the binding.
Since: 2.26
@@ -6529,10 +6526,10 @@ Since: 2.26
Explicitly releases the binding between the source and the target
property expressed by @binding.
-<note>This function will release the reference that is being held on
+This function will release the reference that is being held on
the @binding instance; if you want to hold on to the #GBinding instance
after calling g_binding_unbind(), you will need to hold a reference
-to it.</note>
+to it.
Since: 2.38
@@ -8004,15 +8001,14 @@ provided to copy and free opaque boxed structures of this type.
Creates a filename from a series of elements using the correct
separator for filenames.
-On Unix, this function behaves identically to <literal>g_build_path
-(G_DIR_SEPARATOR_S, first_element, ....)</literal>.
+On Unix, this function behaves identically to `g_build_path
+(G_DIR_SEPARATOR_S, first_element, ....)`.
On Windows, it takes into account that either the backslash
-(<literal>\</literal> or slash (<literal>/</literal>) can be used
-as separator in filenames, but otherwise behaves as on Unix. When
-file pathname separators need to be inserted, the one that last
-previously occurred in the parameters (reading from left to right)
-is used.
+(`\` or slash (`/`) can be used as separator in filenames, but
+otherwise behaves as on UNIX. When file pathname separators need
+to be inserted, the one that last previously occurred in the
+parameters (reading from left to right) is used.
No attempt is made to force the resulting filename to be an absolute
path. If the first element is a relative path, the result will
@@ -8072,8 +8068,7 @@ The number of trailing copies of the separator on the result is
the same as the number of trailing copies of the separator on
the last non-empty element. (Determination of the number of
trailing copies is done without stripping leading copies, so
-if the separator is <literal>ABA</literal>, <literal>ABABA</literal>
-has 1 trailing copy.)
+if the separator is `ABA`, then `ABABA` has 1 trailing copy.)
However, if there is only a single non-empty element, and there
are no characters in that element not part of the leading or
@@ -8130,26 +8125,26 @@ Since: 2.8
<function name="g_byte_array_append">
<description>
-Adds the given bytes to the end of the #GByteArray. The array will
-grow in size automatically if necessary.
+Adds the given bytes to the end of the #GByteArray.
+The array will grow in size automatically if necessary.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the byte data to be added.
+<parameter_description> the byte data to be added
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the number of bytes to add.
+<parameter_description> the number of bytes to add
</parameter_description>
</parameter>
</parameters>
-<return> the #GByteArray.
+<return> the #GByteArray
</return>
</function>
@@ -8164,11 +8159,11 @@ the size of @array will be set to zero.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="free_segment">
-<parameter_description> if %TRUE the actual byte data is freed as well.
+<parameter_description> if %TRUE the actual byte data is freed as well
</parameter_description>
</parameter>
</parameters>
@@ -8198,8 +8193,8 @@ Since: 2.32
</parameter_description>
</parameter>
</parameters>
-<return> a new immutable #GBytes representing same byte
-data that was in the array
+<return> a new immutable #GBytes representing same
+byte data that was in the array
</return>
</function>
@@ -8211,7 +8206,7 @@ Creates a new #GByteArray with a reference count of 1.
</description>
<parameters>
</parameters>
-<return> the new #GByteArray.
+<return> the new #GByteArray
</return>
</function>
@@ -8240,66 +8235,66 @@ Since: 2.32
<function name="g_byte_array_prepend">
<description>
-Adds the given data to the start of the #GByteArray. The array will
-grow in size automatically if necessary.
+Adds the given data to the start of the #GByteArray.
+The array will grow in size automatically if necessary.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the byte data to be added.
+<parameter_description> the byte data to be added
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the number of bytes to add.
+<parameter_description> the number of bytes to add
</parameter_description>
</parameter>
</parameters>
-<return> the #GByteArray.
+<return> the #GByteArray
</return>
</function>
<function name="g_byte_array_ref">
<description>
-Atomically increments the reference count of @array by one. This
-function is MT-safe and may be called from any thread.
+Atomically increments the reference count of @array by one.
+This function is thread-safe and may be called from any thread.
Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GByteArray.
+<parameter_description> A #GByteArray
</parameter_description>
</parameter>
</parameters>
-<return> The passed in #GByteArray.
+<return> The passed in #GByteArray
</return>
</function>
<function name="g_byte_array_remove_index">
<description>
-Removes the byte at the given index from a #GByteArray. The
-following bytes are moved down one place.
+Removes the byte at the given index from a #GByteArray.
+The following bytes are moved down one place.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the byte to remove.
+<parameter_description> the index of the byte to remove
</parameter_description>
</parameter>
</parameters>
-<return> the #GByteArray.
+<return> the #GByteArray
</return>
</function>
@@ -8314,15 +8309,15 @@ than g_byte_array_remove_index().
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the byte to remove.
+<parameter_description> the index of the byte to remove
</parameter_description>
</parameter>
</parameters>
-<return> the #GByteArray.
+<return> the #GByteArray
</return>
</function>
@@ -8336,19 +8331,19 @@ Since: 2.4
</description>
<parameters>
<parameter name="array">
-<parameter_description> a @GByteArray.
+<parameter_description> a @GByteArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the first byte to remove.
+<parameter_description> the index of the first byte to remove
</parameter_description>
</parameter>
<parameter name="length">
-<parameter_description> the number of bytes to remove.
+<parameter_description> the number of bytes to remove
</parameter_description>
</parameter>
</parameters>
-<return> the #GByteArray.
+<return> the #GByteArray
</return>
</function>
@@ -8361,15 +8356,15 @@ Sets the size of the #GByteArray, expanding it if necessary.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="length">
-<parameter_description> the new size of the #GByteArray.
+<parameter_description> the new size of the #GByteArray
</parameter_description>
</parameter>
</parameters>
-<return> the #GByteArray.
+<return> the #GByteArray
</return>
</function>
@@ -8384,11 +8379,11 @@ bytes to the array. Note however that the size of the array is still
</description>
<parameters>
<parameter name="reserved_size">
-<parameter_description> number of bytes preallocated.
+<parameter_description> number of bytes preallocated
</parameter_description>
</parameter>
</parameters>
-<return> the new #GByteArray.
+<return> the new #GByteArray
</return>
</function>
@@ -8408,11 +8403,11 @@ their addresses.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="compare_func">
-<parameter_description> comparison function.
+<parameter_description> comparison function
</parameter_description>
</parameter>
</parameters>
@@ -8427,15 +8422,15 @@ user data argument.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GByteArray.
+<parameter_description> a #GByteArray
</parameter_description>
</parameter>
<parameter name="compare_func">
-<parameter_description> comparison function.
+<parameter_description> comparison function
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> data to pass to @compare_func.
+<parameter_description> data to pass to @compare_func
</parameter_description>
</parameter>
</parameters>
@@ -8446,7 +8441,7 @@ user data argument.
<description>
Atomically decrements the reference count of @array by one. If the
reference count drops to 0, all memory allocated by the array is
-released. This function is MT-safe and may be called from any
+released. This function is thread-safe and may be called from any
thread.
Since: 2.22
@@ -8454,7 +8449,7 @@ Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GByteArray.
+<parameter_description> A #GByteArray
</parameter_description>
</parameter>
</parameters>
@@ -9002,7 +8997,7 @@ data structures to @func; use g_cache_key_foreach() instead
<function name="g_cclosure_marshal_BOOLEAN__FLAGS">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where
the #gint parameter
+`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
denotes a flags type.
</description>
@@ -9039,7 +9034,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer
user_data)</literal>.
+`gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)`.
Since: 2.26
@@ -9087,7 +9082,7 @@ Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
<function name="g_cclosure_marshal_STRING__OBJECT_POINTER">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer
user_data)</literal>.
+`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
</description>
<parameters>
@@ -9123,7 +9118,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__BOOLEAN">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9159,7 +9154,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__BOXED">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9195,7 +9190,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__CHAR">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9231,7 +9226,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__DOUBLE">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9267,7 +9262,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__ENUM">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the
#gint parameter denotes an enumeration type..
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an
enumeration type..
</description>
<parameters>
@@ -9303,7 +9298,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__FLAGS">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the
#gint parameter denotes a flags type.
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a
flags type.
</description>
<parameters>
@@ -9339,7 +9334,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__FLOAT">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9375,7 +9370,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__INT">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9411,7 +9406,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__LONG">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9447,7 +9442,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__OBJECT">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9483,7 +9478,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__PARAM">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9519,7 +9514,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__POINTER">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9555,7 +9550,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__STRING">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9591,7 +9586,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__UCHAR">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9627,7 +9622,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__UINT">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9663,7 +9658,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__UINT_POINTER">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer
user_data)</literal>.
+`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
</description>
<parameters>
@@ -9699,7 +9694,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__ULONG">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
</description>
<parameters>
@@ -9735,7 +9730,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__VARIANT">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
Since: 2.26
@@ -9773,7 +9768,7 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_VOID__VOID">
<description>
A marshaller for a #GCClosure with a callback of type
-<literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
+`void (*callback) (gpointer instance, gpointer user_data)`.
</description>
<parameters>
@@ -9808,8 +9803,8 @@ to g_closure_invoke()
<function name="g_cclosure_marshal_generic">
<description>
-A generic marshaller function implemented via <ulink
-url="http://sourceware.org/libffi/">libffi</ulink>.
+A generic marshaller function implemented via
+[libffi](http://sourceware.org/libffi/).
Since: 2.30
@@ -9829,7 +9824,7 @@ if the callback of closure doesn't return a value.
</parameter_description>
</parameter>
<parameter name="param_values">
-<parameter_description> An array of #GValue<!-- -->s holding the arguments
+<parameter_description> An array of #GValues holding the arguments
on which to invoke the callback of closure.
</parameter_description>
</parameter>
@@ -10176,8 +10171,9 @@ Since: 2.4
</description>
<parameters>
<parameter name="pid">
-<parameter_description> process id to watch. On POSIX the pid of a child process. On
-Windows a handle for a process (which doesn't have to be a child).
+<parameter_description> process id to watch. On POSIX the positive pid of a child
+process. On Windows a handle for a process (which doesn't have to be
+a child).
</parameter_description>
</parameter>
<parameter name="function">
@@ -10229,7 +10225,7 @@ range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
</parameter_description>
</parameter>
<parameter name="pid">
-<parameter_description> process to watch. On POSIX the pid of a child process. On
+<parameter_description> process to watch. On POSIX the positive pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).
</parameter_description>
</parameter>
@@ -10260,8 +10256,7 @@ and must be added to one with g_source_attach() before it will be
executed.
Note that child watch sources can only be used in conjunction with
-<literal>g_spawn...</literal> when the %G_SPAWN_DO_NOT_REAP_CHILD
-flag is used.
+`g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
Note that on platforms where #GPid must be explicitly closed
(see g_spawn_close_pid()) @pid must not be closed while the
@@ -10269,16 +10264,20 @@ source is still active. Typically, you will want to call
g_spawn_close_pid() in the callback function for the source.
Note further that using g_child_watch_source_new() is not
-compatible with calling <literal>waitpid</literal> with a
-nonpositive first argument in the application. Calling waitpid()
-for individual pids will still work fine.
+compatible with calling `waitpid` with a nonpositive first
+argument in the application. Calling waitpid() for individual
+pids will still work fine.
+
+Similarly, on POSIX platforms, the @pid passed to this function must
+be greater than 0 (i.e. this function must wait for a specific child,
+and cannot wait for one of many children by using a nonpositive argument).
Since: 2.4
</description>
<parameters>
<parameter name="pid">
-<parameter_description> process to watch. On POSIX the pid of a child process. On
+<parameter_description> process to watch. On POSIX the positive pid of a child process. On
Windows a handle for a process (which doesn't have to be a child).
</parameter_description>
</parameter>
@@ -10314,7 +10313,7 @@ Since: 2.8
</parameter_description>
</parameter>
</parameters>
-<return> zero if the operation succeeded, -1 on error.
+<return> 0 if the operation succeeded, -1 on error
</return>
</function>
@@ -10553,7 +10552,7 @@ doesn't return a value.
</parameter>
<parameter name="param_values">
<parameter_description> an array of
-#GValue<!-- -->s holding the arguments on which to
+#GValues holding the arguments on which to
invoke the callback of @closure
</parameter_description>
</parameter>
@@ -10577,7 +10576,7 @@ when implementing new types of closures.
<parameters>
<parameter name="sizeof_closure">
<parameter_description> the size of the structure to allocate, must be at least
-<literal>sizeof (GClosure)</literal>
+`sizeof (GClosure)`
</parameter_description>
</parameter>
<parameter name="object">
@@ -10596,7 +10595,7 @@ Allocates a struct of the given size and initializes the initial
part as a #GClosure. This function is mainly useful when
implementing new types of closures.
-|[
+|[<!-- language="C" -->
typedef struct _MyClosure MyClosure;
struct _MyClosure
{
@@ -10634,7 +10633,7 @@ return my_closure;
<parameters>
<parameter name="sizeof_closure">
<parameter_description> the size of the structure to allocate, must be at least
-<literal>sizeof (GClosure)</literal>
+`sizeof (GClosure)`
</parameter_description>
</parameter>
<parameter name="data">
@@ -10715,7 +10714,7 @@ when registering @notify_func
<function name="g_closure_set_marshal">
<description>
-Sets the marshaller of @closure. The <literal>marshal_data</literal>
+Sets the marshaller of @closure. The `marshal_data`
of @marshal provides a way for a meta marshaller to provide additional
information to the marshaller. (See g_closure_set_meta_marshal().) For
GObject's C predefined marshallers (the g_cclosure_marshal_*()
@@ -10741,9 +10740,8 @@ functions), what it provides is a callback function to use instead of
Sets the meta marshaller of @closure. A meta marshaller wraps
@closure->marshal and modifies the way it is called in some
fashion. The most common use of this facility is for C callbacks.
-The same marshallers (generated by <link
-linkend="glib-genmarshal">glib-genmarshal</link>) are used
-everywhere, but the way that we get the callback function
+The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
+are used everywhere, but the way that we get the callback function
differs. In most cases we want to use @closure->callback, but in
other cases we want to use some different technique to retrieve the
callback function.
@@ -10775,27 +10773,27 @@ the right callback and passes it to the marshaller as the
<function name="g_closure_sink">
<description>
Takes over the initial ownership of a closure. Each closure is
-initially created in a <firstterm>floating</firstterm> state, which
-means that the initial reference count is not owned by any caller.
-g_closure_sink() checks to see if the object is still floating, and
-if so, unsets the floating state and decreases the reference
-count. If the closure is not floating, g_closure_sink() does
-nothing. The reason for the existence of the floating state is to
-prevent cumbersome code sequences like:
-|[
+initially created in a "floating" state, which means that the initial
+reference count is not owned by any caller. g_closure_sink() checks
+to see if the object is still floating, and if so, unsets the
+floating state and decreases the reference count. If the closure
+is not floating, g_closure_sink() does nothing. The reason for the
+existence of the floating state is to prevent cumbersome code
+sequences like:
+|[<!-- language="C" -->
closure = g_cclosure_new (cb_func, cb_data);
g_source_set_closure (source, closure);
-g_closure_unref (closure); // XXX GObject doesn't really need this
+g_closure_unref (closure); // GObject doesn't really need this
]|
Because g_source_set_closure() (and similar functions) take ownership of the
initial reference count, if it is unowned, we instead can write:
-|[
+|[<!-- language="C" -->
g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
]|
Generally, this function is used together with g_closure_ref(). Ane example
of storing a closure for later notification looks like:
-|[
+|[<!-- language="C" -->
static GClosure *notify_closure = NULL;
void
foo_notify_set_closure (GClosure *closure)
@@ -11342,6 +11340,7 @@ Deprecated:2.32: Use g_cond_wait_until() instead.
</parameter>
</parameters>
<return> %TRUE if @cond was signalled, or %FALSE on timeout
+
</return>
</function>
@@ -11389,10 +11388,10 @@ case of a spurious wakeup). %FALSE is returned if @end_time has
passed.
The following code shows how to correctly perform a timed wait on a
-condition variable (extended the example presented in the
+condition variable (extending the example presented in the
documentation for #GCond):
-|[
+|[<!-- language="C" -->
gpointer
pop_data_timed (void)
{
@@ -11452,8 +11451,18 @@ Since: 2.32
<description>
Converts a string from one character set to another.
-Note that you should use g_iconv() for streaming
-conversions<footnoteref linkend="streaming-state"/>.
+Note that you should use g_iconv() for streaming conversions.
+Despite the fact that @byes_read can return information about partial
+characters, the g_convert_... functions are not generally suitable
+for streaming. If the underlying converter maintains internal state,
+then this won't be preserved across successive calls to g_convert(),
+g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+this is the GNU C converter for CP1255 which does not emit a base
+character until it knows that the next character is not a mark that
+could combine with the base character.)
+
+Using extensions such as "//TRANSLIT" may not work (or may not work
+well) on many platforms. Consider using g_str_to_ascii() instead.
</description>
@@ -11464,13 +11473,9 @@ conversions<footnoteref linkend="streaming-state"/>.
</parameter>
<parameter name="len">
<parameter_description> the length of the string, or -1 if the string is
-nul-terminated<footnote id="nul-unsafe">
- <para>
- Note that some encodings may allow nul bytes to
- occur inside strings. In that case, using -1 for
- the @len parameter is unsafe.
- </para>
- </footnote>.
+nul-terminated (Note that some encodings may allow nul
+bytes to occur inside strings. In that case, using -1
+for the @len parameter is unsafe)
</parameter_description>
</parameter>
<parameter name="to_codeset">
@@ -11519,8 +11524,15 @@ systems may do an approximate conversion from @from_codeset
to @to_codeset in their iconv() functions,
in which case GLib will simply return that approximate conversion.
-Note that you should use g_iconv() for streaming
-conversions<footnoteref linkend="streaming-state"/>.
+Note that you should use g_iconv() for streaming conversions.
+Despite the fact that @byes_read can return information about partial
+characters, the g_convert_... functions are not generally suitable
+for streaming. If the underlying converter maintains internal state,
+then this won't be preserved across successive calls to g_convert(),
+g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+this is the GNU C converter for CP1255 which does not emit a base
+character until it knows that the next character is not a mark that
+could combine with the base character.)
</description>
@@ -11531,7 +11543,9 @@ conversions<footnoteref linkend="streaming-state"/>.
</parameter>
<parameter name="len">
<parameter_description> the length of the string, or -1 if the string is
-nul-terminated<footnoteref linkend="nul-unsafe"/>.
+nul-terminated (Note that some encodings may allow nul
+bytes to occur inside strings. In that case, using -1
+for the @len parameter is unsafe)
</parameter_description>
</parameter>
<parameter name="to_codeset">
@@ -11579,20 +11593,15 @@ g_free(). Otherwise %NULL and @error will be set.
<description>
Converts a string from one character set to another.
-Note that you should use g_iconv() for streaming
-conversions<footnote id="streaming-state">
-<para>
+Note that you should use g_iconv() for streaming conversions.
Despite the fact that @byes_read can return information about partial
-characters, the <literal>g_convert_...</literal> functions
-are not generally suitable for streaming. If the underlying converter
-being used maintains internal state, then this won't be preserved
-across successive calls to g_convert(), g_convert_with_iconv() or
-g_convert_with_fallback(). (An example of this is the GNU C converter
-for CP1255 which does not emit a base character until it knows that
-the next character is not a mark that could combine with the base
-character.)
-</para>
-</footnote>.
+characters, the g_convert_... functions are not generally suitable
+for streaming. If the underlying converter maintains internal state,
+then this won't be preserved across successive calls to g_convert(),
+g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+this is the GNU C converter for CP1255 which does not emit a base
+character until it knows that the next character is not a mark that
+could combine with the base character.)
</description>
@@ -11603,7 +11612,9 @@ character.)
</parameter>
<parameter name="len">
<parameter_description> the length of the string, or -1 if the string is
-nul-terminated<footnoteref linkend="nul-unsafe"/>.
+nul-terminated (Note that some encodings may allow nul
+bytes to occur inside strings. In that case, using -1
+for the @len parameter is unsafe)
</parameter_description>
</parameter>
<parameter name="converter">
@@ -11673,8 +11684,9 @@ Since: 2.8
</parameter_description>
</parameter>
</parameters>
-<return> a new file descriptor, or -1 if an error occurred. The
-return value can be used exactly like the return value from creat().
+<return> a new file descriptor, or -1 if an error occurred.
+The return value can be used exactly like the return value
+from creat().
</return>
</function>
@@ -11689,8 +11701,8 @@ the program, then use g_critical() for fatal errors, for
example.
You can also make critical warnings fatal at runtime by
-setting the <envar>G_DEBUG</envar> environment variable (see
-<ulink url="glib-running.html">Running GLib Applications</ulink>).
+setting the `G_DEBUG` environment variable (see
+[Running GLib Applications](glib-running.html)).
If g_log_default_handler() is used as the log handler function, a new-line
character will automatically be appended to @..., and need not be entered
@@ -12853,11 +12865,11 @@ The date must be valid.
<function name="g_date_is_leap_year">
<description>
Returns %TRUE if the year is a leap year.
-<footnote><para>For the purposes of this function,
-leap year is every year divisible by 4 unless that year
-is divisible by 100. If it is divisible by 100 it would
-be a leap year only if that year is also divisible
-by 400.</para></footnote>
+
+For the purposes of this function, leap year is every year
+divisible by 4 unless that year is divisible by 100. If it
+is divisible by 100 it would be a leap year only if that year
+is also divisible by 400.
</description>
@@ -13037,10 +13049,10 @@ day-month-year triplet is invalid, the date will be invalid.
<function name="g_date_set_parse">
<description>
Parses a user-inputted string @str, and try to figure out what date it
-represents, taking the <link linkend="setlocale">current locale</link>
-into account. If the string is successfully parsed, the date will be
-valid after the call. Otherwise, it will be invalid. You should check
-using g_date_valid() to see whether the parsing succeeded.
+represents, taking the [current locale][setlocale] into account. If the
+string is successfully parsed, the date will be valid after the call.
+Otherwise, it will be invalid. You should check using g_date_valid()
+to see whether the parsing succeeded.
This function is not appropriate for file formats and the like; it
isn't very precise, and its exact behavior varies with the locale.
@@ -13090,7 +13102,7 @@ specified as a time_t. The time to date conversion is done using
the user's current timezone.
To set the value of a date to the current day, you could write:
-|[
+|[<!-- language="C" -->
g_date_set_time_t (date, time (NULL));
]|
@@ -13103,7 +13115,7 @@ Since: 2.10
</parameter_description>
</parameter>
<parameter name="timet">
-<parameter_description> <type>time_t</type> value to set
+<parameter_description> time_t value to set
</parameter_description>
</parameter>
</parameters>
@@ -13156,7 +13168,7 @@ triplet is invalid, the date will be invalid.
<function name="g_date_strftime">
<description>
Generates a printed representation of the date, in a
-<link linkend="setlocale">locale</link>-specific way.
+[locale][setlocale]-specific way.
Works just like the platform's C library strftime() function,
but only accepts date-related formats; time-related formats
give undefined results. Date must be valid. Unlike strftime()
@@ -13582,262 +13594,77 @@ output exactly.
The following format specifiers are supported:
-<variablelist>
-<varlistentry><term>
-<literal>\%a</literal>:
-</term><listitem><simpara>
-the abbreviated weekday name according to the current locale
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%A</literal>:
-</term><listitem><simpara>
-the full weekday name according to the current locale
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%b</literal>:
-</term><listitem><simpara>
-the abbreviated month name according to the current locale
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%B</literal>:
-</term><listitem><simpara>
-the full month name according to the current locale
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%c</literal>:
-</term><listitem><simpara>
-the preferred date and time representation for the current locale
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%C</literal>:
-</term><listitem><simpara>
-The century number (year/100) as a 2-digit integer (00-99)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%d</literal>:
-</term><listitem><simpara>
-the day of the month as a decimal number (range 01 to 31)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%e</literal>:
-</term><listitem><simpara>
-the day of the month as a decimal number (range 1 to 31)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%F</literal>:
-</term><listitem><simpara>
-equivalent to <literal>\%Y-\%m-\%d</literal> (the ISO 8601 date
-format)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%g</literal>:
-</term><listitem><simpara>
-the last two digits of the ISO 8601 week-based year as a decimal
-number (00-99). This works well with \%V and \%u.
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%G</literal>:
-</term><listitem><simpara>
-the ISO 8601 week-based year as a decimal number. This works well
-with \%V and \%u.
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%h</literal>:
-</term><listitem><simpara>
-equivalent to <literal>\%b</literal>
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%H</literal>:
-</term><listitem><simpara>
-the hour as a decimal number using a 24-hour clock (range 00 to
-23)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%I</literal>:
-</term><listitem><simpara>
-the hour as a decimal number using a 12-hour clock (range 01 to
-12)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%j</literal>:
-</term><listitem><simpara>
-the day of the year as a decimal number (range 001 to 366)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%k</literal>:
-</term><listitem><simpara>
-the hour (24-hour clock) as a decimal number (range 0 to 23);
+- \%a: the abbreviated weekday name according to the current locale
+- \%A: the full weekday name according to the current locale
+- \%b: the abbreviated month name according to the current locale
+- \%B: the full month name according to the current locale
+- \%c: the preferred date and time rpresentation for the current locale
+- \%C: the century number (year/100) as a 2-digit integer (00-99)
+- \%d: the day of the month as a decimal number (range 01 to 31)
+- \%e: the day of the month as a decimal number (range 1 to 31)
+- \%F: equivalent to `\%Y-\%m-\%d` (the ISO 8601 date format)
+- \%g: the last two digits of the ISO 8601 week-based year as a
+decimal number (00-99). This works well with \%V and \%u.
+- \%G: the ISO 8601 week-based year as a decimal number. This works
+well with \%V and \%u.
+- \%h: equivalent to \%b
+- \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
+- \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
+- \%j: the day of the year as a decimal number (range 001 to 366)
+- \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
single digits are preceded by a blank
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%l</literal>:
-</term><listitem><simpara>
-the hour (12-hour clock) as a decimal number (range 1 to 12);
+- \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
single digits are preceded by a blank
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%m</literal>:
-</term><listitem><simpara>
-the month as a decimal number (range 01 to 12)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%M</literal>:
-</term><listitem><simpara>
-the minute as a decimal number (range 00 to 59)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%p</literal>:
-</term><listitem><simpara>
-either "AM" or "PM" according to the given time value, or the
+- \%m: the month as a decimal number (range 01 to 12)
+- \%M: the minute as a decimal number (range 00 to 59)
+- \%p: either "AM" or "PM" according to the given time value, or the
corresponding strings for the current locale. Noon is treated as
"PM" and midnight as "AM".
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%P</literal>:
-</term><listitem><simpara>
-like \%p but lowercase: "am" or "pm" or a corresponding string for
+- \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
the current locale
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%r</literal>:
-</term><listitem><simpara>
-the time in a.m. or p.m. notation
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%R</literal>:
-</term><listitem><simpara>
-the time in 24-hour notation (<literal>\%H:\%M</literal>)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%s</literal>:
-</term><listitem><simpara>
-the number of seconds since the Epoch, that is, since 1970-01-01
+- \%r: the time in a.m. or p.m. notation
+- \%R: the time in 24-hour notation (\%H:\%M)
+- \%s: the number of seconds since the Epoch, that is, since 1970-01-01
00:00:00 UTC
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%S</literal>:
-</term><listitem><simpara>
-the second as a decimal number (range 00 to 60)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%t</literal>:
-</term><listitem><simpara>
-a tab character
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%T</literal>:
-</term><listitem><simpara>
-the time in 24-hour notation with seconds (<literal>\%H:\%M:\%S</literal>)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%u</literal>:
-</term><listitem><simpara>
-the ISO 8601 standard day of the week as a decimal, range 1 to 7,
-Monday being 1. This works well with \%G and \%V.
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%V</literal>:
-</term><listitem><simpara>
-the ISO 8601 standard week number of the current year as a decimal
+- \%S: the second as a decimal number (range 00 to 60)
+- \%t: a tab character
+- \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
+- \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
+Monday being 1. This works well with \%G and \%V.
+- \%V: the ISO 8601 standard week number of the current year as a decimal
number, range 01 to 53, where week 1 is the first week that has at
least 4 days in the new year. See g_date_time_get_week_of_year().
This works well with \%G and \%u.
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%w</literal>:
-</term><listitem><simpara>
-the day of the week as a decimal, range 0 to 6, Sunday being 0.
+- \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
This is not the ISO 8601 standard format -- use \%u instead.
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%x</literal>:
-</term><listitem><simpara>
-the preferred date representation for the current locale without
+- \%x: the preferred date representation for the current locale without
the time
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%X</literal>:
-</term><listitem><simpara>
-the preferred time representation for the current locale without
+- \%X: the preferred time representation for the current locale without
the date
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%y</literal>:
-</term><listitem><simpara>
-the year as a decimal number without the century
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%Y</literal>:
-</term><listitem><simpara>
-the year as a decimal number including the century
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%z</literal>:
-</term><listitem><simpara>
-the time zone as an offset from UTC (+hhmm)
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%:z</literal>:
-</term><listitem><simpara>
-the time zone as an offset from UTC (+hh:mm). This is a gnulib strftime extension. Since: 2.38
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%::z</literal>:
-</term><listitem><simpara>
-the time zone as an offset from UTC (+hh:mm:ss). This is a gnulib strftime extension. Since: 2.38
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%:::z</literal>:
-</term><listitem><simpara>
-the time zone as an offset from UTC, with : to necessary precision
-(e.g., -04, +05:30). This is a gnulib strftime extension. Since: 2.38
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%Z</literal>:
-</term><listitem><simpara>
-the time zone or name or abbreviation
-</simpara></listitem></varlistentry>
-<varlistentry><term>
-<literal>\%\%</literal>:
-</term><listitem><simpara>
-a literal <literal>\%</literal> character
-</simpara></listitem></varlistentry>
-</variablelist>
+- \%y: the year as a decimal number without the century
+- \%Y: the year as a decimal number including the century
+- \%z: the time zone as an offset from UTC (+hhmm)
+- \%:z: the time zone as an offset from UTC (+hh:mm).
+This is a gnulib strftime() extension. Since: 2.38
+- \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
+gnulib strftime() extension. Since: 2.38
+- \%:::z: the time zone as an offset from UTC, with : to necessary
+precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
+- \%Z: the time zone or name or abbreviation
+- \%\%: a literal \% character
Some conversion specifications can be modified by preceding the
conversion specifier by one or more modifier characters. The
following modifiers are supported for many of the numeric
conversions:
-<variablelist>
-<varlistentry>
-<term>O</term>
-<listitem>
-Use alternative numeric symbols, if the current locale
-supports those.
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>_</term>
-<listitem>
-Pad a numeric result with spaces.
-This overrides the default padding for the specifier.
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>-</term>
-<listitem>
-Do not pad a numeric result.
-This overrides the default padding for the specifier.
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>0</term>
-<listitem>
-Pad a numeric result with zeros.
-This overrides the default padding for the specifier.
-</listitem>
-</varlistentry>
-</variablelist>
+
+- O: Use alternative numeric symbols, if the current locale supports those.
+- _: Pad a numeric result with spaces. This overrides the default padding
+for the specifier.
+- -: Do not pad a numeric result. This overrides the default padding
+for the specifier.
+- 0: Pad a numeric result with zeros. This overrides the default padding
+for the specifier.
Since: 2.26
@@ -13854,7 +13681,7 @@ Since: 2.26
</parameter>
</parameters>
<return> a newly allocated string formatted to the requested format
-or %NULL in the case that there was an error. The string
+or %NULL in the case that there was an error. The string
should be freed with g_free().
</return>
@@ -14736,18 +14563,17 @@ Since: 2.26
<function name="g_date_to_struct_tm">
<description>
-Fills in the date-related bits of a <structname>struct tm</structname>
-using the @date value. Initializes the non-date parts with something
-sane but meaningless.
+Fills in the date-related bits of a struct tm using the @date value.
+Initializes the non-date parts with something sane but meaningless.
</description>
<parameters>
<parameter name="date">
-<parameter_description> a #GDate to set the <structname>struct tm</structname> from
+<parameter_description> a #GDate to set the struct tm from
</parameter_description>
</parameter>
<parameter name="tm">
-<parameter_description> <structname>struct tm</structname> to fill
+<parameter_description> struct tm to fill
</parameter_description>
</parameter>
</parameters>
@@ -14886,7 +14712,7 @@ though there is a 16-bit limit to what #GDate will understand.
<function name="g_dcgettext">
<description>
This is a variant of g_dgettext() that allows specifying a locale
-category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for
+category instead of always using `LC_MESSAGES`. See g_dgettext() for
more information about how this functions differs from calling
dcgettext() directly.
@@ -14954,17 +14780,19 @@ textdomain() before gtk_init or its variants.
This function disables translations if and only if upon its first
call all the following conditions hold:
-<itemizedlist>
-<listitem>@domain is not %NULL</listitem>
-<listitem>textdomain() has been called to set a default text domain</listitem>
-<listitem>there is no translations available for the default text domain
-and the current locale</listitem>
-<listitem>current locale is not "C" or any English locales (those
-starting with "en_")</listitem>
-</itemizedlist>
+
+- @domain is not %NULL
+
+- textdomain() has been called to set a default text domain
+
+- there is no translations available for the default text domain
+and the current locale
+
+- current locale is not "C" or any English locales (those
+starting with "en_")
Note that this behavior may not be desired for example if an application
-has its untranslated messages in a language other than English. In those
+has its untranslated messages in a language other than English. In those
cases the application should call textdomain() after initializing GTK+.
Applications should normally not use this function directly,
@@ -15078,8 +14906,7 @@ and may vary by file system or other operating-system dependent
factors.
%NULL may also be returned in case of errors. On Unix, you can
-check <literal>errno</literal> to find out if %NULL was returned
-because of an error.
+check `errno` to find out if %NULL was returned because of an error.
On Unix, the '.' and '..' entries are omitted, and the returned
name is in the on-disk encoding.
@@ -15120,11 +14947,11 @@ will return the first entry again.
<description>
Compares two #gpointer arguments and returns %TRUE if they are equal.
It can be passed to g_hash_table_new() as the @key_equal_func
-parameter, when using opaque pointers compared by pointer value as keys
-in a #GHashTable.
+parameter, when using opaque pointers compared by pointer value as
+keys in a #GHashTable.
-This equality function is also appropriate for keys that are integers stored
-in pointers, such as <literal>GINT_TO_POINTER (n)</literal>.
+This equality function is also appropriate for keys that are integers
+stored in pointers, such as `GINT_TO_POINTER (n)`.
</description>
@@ -15149,8 +14976,8 @@ It can be passed to g_hash_table_new() as the @hash_func parameter,
when using opaque pointers compared by pointer value as keys in a
#GHashTable.
-This hash function is also appropriate for keys that are integers stored
-in pointers, such as <literal>GINT_TO_POINTER (n)</literal>.
+This hash function is also appropriate for keys that are integers
+stored in pointers, such as `GINT_TO_POINTER (n)`.
</description>
@@ -15346,11 +15173,11 @@ the domain set with textdomain()
<function name="g_enum_complete_type_info">
<description>
-This function is meant to be called from the <literal>complete_type_info</literal>
+This function is meant to be called from the `complete_type_info`
function of a #GTypePlugin implementation, as in the following
example:
-|[
+|[<!-- language="C" -->
static void
my_enum_complete_type_info (GTypePlugin *plugin,
GType g_type,
@@ -15456,10 +15283,9 @@ with that nickname
<description>
Registers a new static enumeration type with the name @name.
-It is normally more convenient to let <link
-linkend="glib-mkenums">glib-mkenums</link> generate a
-my_enum_get_type() function from a usual C enumeration definition
-than to write one yourself using g_enum_register_static().
+It is normally more convenient to let [glib-mkenums][glib-mkenums],
+generate a my_enum_get_type() function from a usual C enumeration
+definition than to write one yourself using g_enum_register_static().
</description>
@@ -15742,8 +15568,8 @@ Since: 2.22
<function name="g_file_error_from_errno">
<description>
Gets a #GFileError constant based on the passed-in @err_no.
-For example, if you pass in <literal>EEXIST</literal> this function returns
-#G_FILE_ERROR_EXIST. Unlike <literal>errno</literal> values, you can portably
+For example, if you pass in `EEXIST` this function returns
+#G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
assume that all #GFileError values will exist.
Normally a #GFileError value goes into a #GError returned
@@ -15876,24 +15702,19 @@ If a file called @filename already exists it will be overwritten.
This write is atomic in the sense that it is first written to a temporary
file which is then renamed to the final name. Notes:
-<itemizedlist>
-<listitem>
-On Unix, if @filename already exists hard links to @filename will break.
+
+- On UNIX, if @filename already exists hard links to @filename will break.
Also since the file is recreated, existing permissions, access control
lists, metadata etc. may be lost. If @filename is a symbolic link,
the link itself will be replaced, not the linked file.
-</listitem>
-<listitem>
-On Windows renaming a file will not remove an existing file with the
+
+- On Windows renaming a file will not remove an existing file with the
new name, so on Windows there is a race condition between the existing
file being removed and the temporary file being renamed.
-</listitem>
-<listitem>
-On Windows there is no way to remove a file that is open to some
+
+- On Windows there is no way to remove a file that is open to some
process, or mapped into memory. Thus, this function will fail if
@filename already exists and is open.
-</listitem>
-</itemizedlist>
If the call was successful, it returns %TRUE. If the call was not successful,
it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
@@ -15932,11 +15753,11 @@ encoding
<function name="g_file_test">
<description>
Returns %TRUE if any of the tests in the bitfield @test are
-%TRUE. For example, <literal>(G_FILE_TEST_EXISTS |
-G_FILE_TEST_IS_DIR)</literal> will return %TRUE if the file exists;
-the check whether it's a directory doesn't matter since the existence
-test is %TRUE. With the current set of available tests, there's no point
-passing in more than one test at a time.
+%TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
+will return %TRUE if the file exists; the check whether it's a
+directory doesn't matter since the existence test is %TRUE. With
+the current set of available tests, there's no point passing in
+more than one test at a time.
Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
so for a symbolic link to a regular file g_file_test() will return
@@ -15951,12 +15772,12 @@ of the condition changing before you actually perform the operation.
For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
to know whether it is safe to write to a file without being
tricked into writing into a different location. It doesn't work!
-|[
-/ * DON'T DO THIS * /
+|[<!-- language="C" -->
+// DON'T DO THIS
if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
{
fd = g_open (filename, O_WRONLY);
-/ * write to fd * /
+// write to fd
}
]|
@@ -15971,7 +15792,7 @@ On Windows, there are no symlinks, so testing for
%G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
%G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
its name indicates that it is executable, checking for well-known
-extensions and those listed in the <envar>PATHEXT</envar> environment variable.
+extensions and those listed in the `PATHEXT` environment variable.
</description>
@@ -16090,7 +15911,7 @@ the resulting filename, or %NULL on an error.
Converts a string from UTF-8 to the encoding GLib uses for
filenames. Note that on Windows GLib uses UTF-8 for filenames;
on other platforms, this function indirectly depends on the
-<link linkend="setlocale">current locale</link>.
+[current locale][setlocale].
</description>
@@ -16165,7 +15986,7 @@ URI, or %NULL on an error.
Converts a string which is in the encoding used by GLib for
filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
for filenames; on other platforms, this function indirectly depends on
-the <link linkend="setlocale">current locale</link>.
+the [current locale][setlocale].
</description>
@@ -16176,7 +15997,9 @@ the <link linkend="setlocale">current locale</link>.
</parameter>
<parameter name="len">
<parameter_description> the length of the string, or -1 if the string is
-nul-terminated<footnoteref linkend="nul-unsafe"/>.
+nul-terminated (Note that some encodings may allow nul
+bytes to occur inside strings. In that case, using -1
+for the @len parameter is unsafe)
</parameter_description>
</parameter>
<parameter name="bytes_read">
@@ -16215,15 +16038,15 @@ the path. If @program is already an absolute path, returns a copy of
On Windows, if @program does not have a file type suffix, tries
with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
-the <envar>PATHEXT</envar> environment variable.
+the `PATHEXT` environment variable.
On Windows, it looks for the file in the same way as CreateProcess()
would. This means first in the directory where the executing
program was loaded from, then in the current directory, then in the
Windows 32-bit system directory, then in the Windows directory, and
-finally in the directories in the <envar>PATH</envar> environment
-variable. If the program is found, the return value contains the
-full name including the type suffix.
+finally in the directories in the `PATH` environment variable. If
+the program is found, the return value contains the full name
+including the type suffix.
</description>
@@ -16330,10 +16153,9 @@ or %NULL if there is no flag with that nickname
<description>
Registers a new static flags type with the name @name.
-It is normally more convenient to let <link
-linkend="glib-mkenums">glib-mkenums</link> generate a
-my_flags_get_type() function from a usual C enumeration definition
-than to write one yourself using g_flags_register_static().
+It is normally more convenient to let [glib-mkenums][glib-mkenums]
+generate a my_flags_get_type() function from a usual C enumeration
+definition than to write one yourself using g_flags_register_static().
</description>
@@ -16359,12 +16181,11 @@ A wrapper for the stdio fopen() function. The fopen() function
opens a file and associates a new stream with it.
Because file descriptors are specific to the C library on Windows,
-and a file descriptor is partof the <type>FILE</type> struct, the
-<type>FILE</type> pointer returned by this function makes sense
-only to functions in the same C library. Thus if the GLib-using
-code uses a different C library than GLib does, the
-<type>FILE</type> pointer returned by this function cannot be
-passed to C library functions like fprintf() or fread().
+and a file descriptor is part of the FILE struct, the FILE* returned
+by this function makes sense only to functions in the same C library.
+Thus if the GLib-using code uses a different C library than GLib does,
+the FILE* returned by this function cannot be passed to C library
+functions like fprintf() or fread().
See your C library manual for more details about fopen().
@@ -16377,13 +16198,12 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="mode">
-<parameter_description> a string describing the mode in which the file should be
-opened
+<parameter_description> a string describing the mode in which the file should be opened
</parameter_description>
</parameter>
</parameters>
-<return> A <type>FILE</type> pointer if the file was successfully
-opened, or %NULL if an error occurred
+<return> A FILE* if the file was successfully opened, or %NULL if
+an error occurred
</return>
</function>
@@ -16488,7 +16308,7 @@ Since: 2.2
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="Varargs">
@@ -16532,8 +16352,7 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="mode">
-<parameter_description> a string describing the mode in which the file should be
-opened
+<parameter_description> a string describing the mode in which the file should be opened
</parameter_description>
</parameter>
<parameter name="stream">
@@ -16541,8 +16360,8 @@ opened
</parameter_description>
</parameter>
</parameters>
-<return> A <literal>FILE</literal> pointer if the file was successfully
-opened, or %NULL if an error occurred.
+<return> A FILE* if the file was successfully opened, or %NULL if
+an error occurred.
</return>
</function>
@@ -16569,11 +16388,10 @@ Since: 2.2
<function name="g_get_charset">
<description>
-Obtains the character set for the <link linkend="setlocale">current
-locale</link>; you might use this character set as an argument to
-g_convert(), to convert from the current locale's encoding to some
-other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8()
-are nice shortcuts, though.)
+Obtains the character set for the [current locale][setlocale]; you
+might use this character set as an argument to g_convert(), to convert
+from the current locale's encoding to some other encoding. (Frequently
+g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.)
On Windows the character set returned by this function is the
so-called system default ANSI code-page. That is the character set
@@ -16681,24 +16499,23 @@ subsequent character sets are used when trying to generate a displayable
representation of a filename, see g_filename_display_name().
On Unix, the character sets are determined by consulting the
-environment variables <envar>G_FILENAME_ENCODING</envar> and
-<envar>G_BROKEN_FILENAMES</envar>. On Windows, the character set
-used in the GLib API is always UTF-8 and said environment variables
-have no effect.
-
-<envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list
-of character set names. The special token "@locale" is taken to
-mean the character set for the <link linkend="setlocale">current
-locale</link>. If <envar>G_FILENAME_ENCODING</envar> is not set, but
-<envar>G_BROKEN_FILENAMES</envar> is, the character set of the current
-locale is taken as the filename encoding. If neither environment variable
-is set, UTF-8 is taken as the filename encoding, but the character
-set of the current locale is also put in the list of encodings.
+environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
+On Windows, the character set used in the GLib API is always UTF-8
+and said environment variables have no effect.
+
+`G_FILENAME_ENCODING` may be set to a comma-separated list of
+character set names. The special token "@locale" is taken
+to mean the character set for the [current locale][setlocale].
+If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
+the character set of the current locale is taken as the filename
+encoding. If neither environment variable is set, UTF-8 is taken
+as the filename encoding, but the character set of the current locale
+is also put in the list of encodings.
The returned @charsets belong to GLib and must not be freed.
Note that on Unix, regardless of the locale character set or
-<envar>G_FILENAME_ENCODING</envar> value, the actual file names present
+`G_FILENAME_ENCODING` value, the actual file names present
on a system might be in any random encoding or just gibberish.
Since: 2.6
@@ -16720,28 +16537,23 @@ Since: 2.6
Gets the current user's home directory.
As with most UNIX tools, this function will return the value of the
-<envar>HOME</envar> environment variable if it is set to an existing
-absolute path name, falling back to the <filename>passwd</filename>
-file in the case that it is unset.
-
-If the path given in <envar>HOME</envar> is non-absolute, does not
-exist, or is not a directory, the result is undefined.
-
-<note><para>
-Before version 2.36 this function would ignore the
-<envar>HOME</envar> environment variable, taking the value from the
-<filename>passwd</filename> database instead. This was changed to
-increase the compatibility of GLib with other programs (and the XDG
-basedir specification) and to increase testability of programs
-based on GLib (by making it easier to run them from test
-frameworks).
-</para><para>
+`HOME` environment variable if it is set to an existing absolute path
+name, falling back to the `passwd` file in the case that it is unset.
+
+If the path given in `HOME` is non-absolute, does not exist, or is
+not a directory, the result is undefined.
+
+Before version 2.36 this function would ignore the `HOME` environment
+variable, taking the value from the `passwd` database instead. This was
+changed to increase the compatibility of GLib with other programs (and
+the XDG basedir specification) and to increase testability of programs
+based on GLib (by making it easier to run them from test frameworks).
+
If your program has a strong requirement for either the new or the
old behaviour (and if you don't wish to increase your GLib
dependency to ensure that the new behaviour is in effect) then you
-should either directly check the <envar>HOME</envar> environment
-variable yourself or unset it before calling any functions in GLib.
-</para></note>
+should either directly check the `HOME` environment variable yourself
+or unset it before calling any functions in GLib.
</description>
@@ -16786,9 +16598,9 @@ the default locale "C".
For example, if LANGUAGE=de:en_US, then the returned list is
"de", "en_US", "en", "C".
-This function consults the environment variables <envar>LANGUAGE</envar>,
-<envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar>
-to find the list of locales specified by the user.
+This function consults the environment variables `LANGUAGE`, `LC_ALL`,
+`LC_MESSAGES` and `LANG` to find the list of locales specified by the
+user.
Since: 2.6
@@ -16811,7 +16623,7 @@ This function handles territory, charset and extra locale modifiers.
For example, if @locale is "fr_BE", then the returned list
is "fr_BE", "fr".
-If you need the list of variants for the <emphasis>current locale</emphasis>,
+If you need the list of variants for the current locale,
use g_get_language_names().
Since: 2.28
@@ -16832,22 +16644,16 @@ g_strfreev().
<function name="g_get_monotonic_time">
<description>
-Queries the system monotonic time, if available.
+Queries the system monotonic time.
-On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call
-is a very shallow wrapper for that. Otherwise, we make a best effort
-that probably involves returning the wall clock time (with at least
-microsecond accuracy, subject to the limitations of the OS kernel).
+The monotonic clock will always increase and doesn't suffer
+discontinuities when the user (or NTP) changes the system time. It
+may or may not continue to tick during times where the machine is
+suspended.
-It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does
-not count time spent while the machine is suspended.
-
-On Windows, "limitations of the OS kernel" is a rather substantial
-statement. Depending on the configuration of the system, the wall
-clock time is updated as infrequently as 64 times a second (which
-is approximately every 16ms). Also, on XP (but not on Vista or later)
-the monotonic clock is locally monotonic, but may differ in exact
-value between processes due to timer wrap handling.
+We try to use the clock that corresponds as closely as possible to
+the passage of time as measured by system calls such as poll() but it
+may not always be possible to do this.
Since: 2.28
@@ -16878,11 +16684,12 @@ Since: 2.36
<function name="g_get_prgname">
<description>
-Gets the name of the program. This name should <emphasis>not</emphasis>
-be localized, contrast with g_get_application_name().
-(If you are using GDK or GTK+ the program name is set in gdk_init(),
+Gets the name of the program. This name should not be localized,
+in contrast to g_get_application_name().
+
+If you are using GDK or GTK+ the program name is set in gdk_init(),
which is called by gtk_init(). The program name is found by taking
-the last component of <literal>argv[0]</literal>.)
+the last component of @argv[0].
</description>
@@ -16895,10 +16702,10 @@ to GLib and must not be modified or freed.
<function name="g_get_real_name">
<description>
-Gets the real name of the user. This usually comes from the user's entry
-in the <filename>passwd</filename> file. The encoding of the returned
-string is system-defined. (On Windows, it is, however, always UTF-8.)
-If the real user name cannot be determined, the string "Unknown" is
+Gets the real name of the user. This usually comes from the user's
+entry in the `passwd` file. The encoding of the returned string is
+system-defined. (On Windows, it is, however, always UTF-8.) If the
+real user name cannot be determined, the string "Unknown" is
returned.
@@ -16936,10 +16743,10 @@ Since: 2.28
Returns an ordered list of base directories in which to access
system-wide configuration information.
-On UNIX platforms this is determined using the mechanisms described in
-the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
-XDG Base Directory Specification</ulink>.
-In this case the list of directories retrieved will be XDG_CONFIG_DIRS.
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
On Windows is the directory that contains application data for all users.
A typical path is C:\Documents and Settings\All Users\Application Data.
@@ -16963,9 +16770,9 @@ not be modified or freed.
Returns an ordered list of base directories in which to access
system-wide application data.
-On UNIX platforms this is determined using the mechanisms described in
-the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
-XDG Base Directory Specification</ulink>
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
In this case the list of directories retrieved will be XDG_DATA_DIRS.
On Windows the first elements in the list are the Application Data
@@ -17004,17 +16811,18 @@ not be modified or freed.
<description>
Gets the directory to use for temporary files.
-On UNIX, this is taken from the <envar>TMPDIR</envar> environment
-variable. If the variable is not set, <literal>P_tmpdir</literal> is
-used, as defined by the system C library. Failing that, a hard-coded
-default of "/tmp" is returned.
+On UNIX, this is taken from the `TMPDIR` environment variable.
+If the variable is not set, `P_tmpdir` is
+used, as defined by the system C library. Failing that, a
+hard-coded default of "/tmp" is returned.
-On Windows, the <envar>TEMP</envar> environment variable is used,
-with the root directory of the Windows installation (eg: "C:\") used
+On Windows, the `TEMP` environment variable is used, with the
+root directory of the Windows installation (eg: "C:\") used
as a default.
-The encoding of the returned string is system-defined. On Windows, it
-is always UTF-8. The return value is never %NULL or the empty string.
+The encoding of the returned string is system-defined. On Windows,
+it is always UTF-8. The return value is never %NULL or the empty
+string.
</description>
@@ -17029,9 +16837,9 @@ is always UTF-8. The return value is never %NULL or the empty string.
Returns a base directory in which to store non-essential, cached
data specific to particular user.
-On UNIX platforms this is determined using the mechanisms described in
-the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
-XDG Base Directory Specification</ulink>.
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
In this case the directory retrieved will be XDG_CACHE_HOME.
On Windows is the directory that serves as a common repository for
@@ -17054,10 +16862,10 @@ or freed.
Returns a base directory in which to store user-specific application
configuration information such as user preferences and settings.
-On UNIX platforms this is determined using the mechanisms described in
-the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
-XDG Base Directory Specification</ulink>.
-In this case the directory retrieved will be XDG_CONFIG_HOME.
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the directory retrieved will be `XDG_CONFIG_HOME`.
On Windows this is the folder to use for local (as opposed to
roaming) application data. See documentation for
@@ -17079,10 +16887,10 @@ or freed.
Returns a base directory in which to access application data such
as icons that is customized for a particular user.
-On UNIX platforms this is determined using the mechanisms described in
-the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
-XDG Base Directory Specification</ulink>.
-In this case the directory retrieved will be XDG_DATA_HOME.
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+In this case the directory retrieved will be `XDG_DATA_HOME`.
On Windows this is the folder to use for local (as opposed to
roaming) application data. See documentation for
@@ -17119,10 +16927,11 @@ consistent on a machine. On Windows, it is always UTF-8.
Returns a directory that is unique to the current user on the local
system.
-On UNIX platforms this is determined using the mechanisms described in
-the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
-XDG Base Directory Specification</ulink>. This is the directory
-specified in the <envar>XDG_RUNTIME_DIR</envar> environment variable.
+On UNIX platforms this is determined using the mechanisms described
+in the
+[XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+This is the directory
+specified in the `XDG_RUNTIME_DIR` environment variable.
In the case that this variable is not set, GLib will issue a warning
message to stderr and return the value of g_get_user_cache_dir().
@@ -17145,10 +16954,10 @@ Since: 2.28
<description>
Returns the full path of a special directory using its logical id.
-On Unix this is done using the XDG special user directories.
+On UNIX this is done using the XDG special user directories.
For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
-falls back to <filename>$HOME/Desktop</filename> when XDG special
-user directories have not been set up.
+falls back to `$HOME/Desktop` when XDG special user directories have
+not been set up.
Depending on the platform, the user might be able to change the path
of the special directory without requiring the session to restart; GLib
@@ -17542,14 +17351,14 @@ Since: 2.16
Initializes a key/value pair iterator and associates it with
@hash_table. Modifying the hash table after calling this function
invalidates the returned iterator.
-|[
+|[<!-- language="C" -->
GHashTableIter iter;
gpointer key, value;
g_hash_table_iter_init (&iter, hash_table);
while (g_hash_table_iter_next (&iter, &key, &value))
{
-/ * do something with key and value * /
+// do something with key and value
}
]|
@@ -17609,6 +17418,15 @@ the key and value are freed using the supplied destroy functions,
otherwise you have to make sure that any dynamically allocated
values are freed yourself.
+It is safe to continue iterating the #GHashTable afterward:
+|[
+while (g_hash_table_iter_next (&iter, &key, &value))
+{
+if (condition)
+g_hash_table_iter_remove (&iter);
+}
+]|
+
Since: 2.16
</description>
@@ -18499,7 +18317,7 @@ This must be called before the #GHookList is used.
</parameter>
<parameter name="hook_size">
<parameter_description> the size of each element in the #GHookList,
-typically <literal>sizeof (GHook)</literal>
+typically `sizeof (GHook)`.
</parameter_description>
</parameter>
</parameters>
@@ -19101,9 +18919,9 @@ It can be passed to g_hash_table_new() as the @key_equal_func
parameter, when using non-%NULL pointers to integers as keys in a
#GHashTable.
-Note that this function acts on pointers to #gint, not on #gint directly:
-if your hash table's keys are of the form
-<literal>GINT_TO_POINTER (n)</literal>, use g_direct_equal() instead.
+Note that this function acts on pointers to #gint, not on #gint
+directly: if your hash table's keys are of the form
+`GINT_TO_POINTER (n)`, use g_direct_equal() instead.
</description>
@@ -19127,9 +18945,9 @@ Converts a pointer to a #gint to a hash value.
It can be passed to g_hash_table_new() as the @hash_func parameter,
when using non-%NULL pointers to integer values as keys in a #GHashTable.
-Note that this function acts on pointers to #gint, not on #gint directly:
-if your hash table's keys are of the form
-<literal>GINT_TO_POINTER (n)</literal>, use g_direct_hash() instead.
+Note that this function acts on pointers to #gint, not on #gint
+directly: if your hash table's keys are of the form
+`GINT_TO_POINTER (n)`, use g_direct_hash() instead.
</description>
@@ -19274,13 +19092,13 @@ Deprecated:2.2: Use g_io_channel_shutdown() instead.
<function name="g_io_channel_error_from_errno">
<description>
-Converts an <literal>errno</literal> error number to a #GIOChannelError.
+Converts an `errno` error number to a #GIOChannelError.
</description>
<parameters>
<parameter name="en">
-<parameter_description> an <literal>errno</literal> error number, e.g.
<literal>EINVAL</literal>
+<parameter_description> an `errno` error number, e.g. `EINVAL`
</parameter_description>
</parameter>
</parameters>
@@ -19867,37 +19685,28 @@ The encoding %NULL is safe to use with binary data.
The encoding can only be set if one of the following conditions
is true:
-<itemizedlist>
-<listitem><para>
-The channel was just created, and has not been written to or read
-from yet.
-</para></listitem>
-<listitem><para>
-The channel is write-only.
-</para></listitem>
-<listitem><para>
-The channel is a file, and the file pointer was just
-repositioned by a call to g_io_channel_seek_position().
-(This flushes all the internal buffers.)
-</para></listitem>
-<listitem><para>
-The current encoding is %NULL or UTF-8.
-</para></listitem>
-<listitem><para>
-One of the (new API) read functions has just returned %G_IO_STATUS_EOF
+
+- The channel was just created, and has not been written to or read from yet.
+
+- The channel is write-only.
+
+- The channel is a file, and the file pointer was just repositioned
+by a call to g_io_channel_seek_position(). (This flushes all the
+internal buffers.)
+
+- The current encoding is %NULL or UTF-8.
+
+- One of the (new API) read functions has just returned %G_IO_STATUS_EOF
(or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
-</para></listitem>
-<listitem><para>
-One of the functions g_io_channel_read_chars() or
+
+- One of the functions g_io_channel_read_chars() or
g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
%G_IO_STATUS_ERROR. This may be useful in the case of
%G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
Returning one of these statuses from g_io_channel_read_line(),
g_io_channel_read_line_string(), or g_io_channel_read_to_end()
-does <emphasis>not</emphasis> guarantee that the encoding can
-be changed.
-</para></listitem>
-</itemizedlist>
+does not guarantee that the encoding can be changed.
+
Channels which do not meet one of the above conditions cannot call
g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
they are "seekable", cannot call g_io_channel_write_chars() after
@@ -19919,7 +19728,7 @@ calling one of the API "read" functions.
</parameter_description>
</parameter>
</parameters>
-<return> %G_IO_STATUS_NORMAL if the encoding was successfully set.
+<return> %G_IO_STATUS_NORMAL if the encoding was successfully set
</return>
</function>
@@ -20946,10 +20755,10 @@ otherwise.
Looks whether the key file has the key @key in the group
@group_name.
-<note>This function does not follow the rules for #GError strictly;
+Note that this function does not follow the rules for #GError strictly;
the return value both carries meaning and signals an error. To use
this function, you must pass a #GError pointer in @error, and check
-whether it is not %NULL to see if an error occurred.</note>
+whether it is not %NULL to see if an error occurred.
Language bindings should use g_key_file_get_value() to test whether
or not a key exists.
@@ -20975,8 +20784,7 @@ Since: 2.6
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if @key is a part of @group_name, %FALSE
-otherwise.
+<return> %TRUE if @key is a part of @group_name, %FALSE otherwise
</return>
</function>
@@ -21816,7 +21624,7 @@ g_list_insert_sorted() and so is rarely used on its own.
</description>
<parameters>
</parameters>
-<return> a pointer to the newly-allocated #GList element.
+<return> a pointer to the newly-allocated #GList element
</return>
</function>
@@ -21824,27 +21632,23 @@ g_list_insert_sorted() and so is rarely used on its own.
<description>
Adds a new element on to the end of the list.
-<note><para>
-The return value is the new start of the list, which
-may have changed, so make sure you store the new value.
-</para></note>
+Note that the return value is the new start of the list,
+if @list was empty; make sure you store the new value.
-<note><para>
-Note that g_list_append() has to traverse the entire list
-to find the end, which is inefficient when adding multiple
-elements. A common idiom to avoid the inefficiency is to prepend
-the elements and reverse the list when all elements have been added.
-</para></note>
+g_list_append() has to traverse the entire list to find the end,
+which is inefficient when adding multiple elements. A common idiom
+to avoid the inefficiency is to use g_list_prepend() and reverse
+the list with g_list_reverse() when all elements have been added.
-|[
-/ * Notice that these are initialized to the empty list. * /
-GList *list = NULL, *number_list = NULL;
+|[<!-- language="C" -->
+// Notice that these are initialized to the empty list.
+GList *string_list = NULL, *number_list = NULL;
-/ * This is a list of strings. * /
-list = g_list_append (list, "first");
-list = g_list_append (list, "second");
+// This is a list of strings.
+string_list = g_list_append (string_list, "first");
+string_list = g_list_append (string_list, "second");
-/ * This is a list of integers. * /
+// This is a list of integers.
number_list = g_list_append (number_list, GINT_TO_POINTER (27));
number_list = g_list_append (number_list, GINT_TO_POINTER (14));
]|
@@ -21861,7 +21665,7 @@ number_list = g_list_append (number_list, GINT_TO_POINTER (14));
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> either @list or the new start of the #GList if @list was %NULL
</return>
</function>
@@ -21871,19 +21675,27 @@ Adds the second #GList onto the end of the first #GList.
Note that the elements of the second #GList are not copied.
They are used directly.
+This function is for example used to move an element in the list.
+The following example moves an element to the top of the list:
+|[<!-- language="C" -->
+list = g_list_remove_link (list, llink);
+list = g_list_concat (llink, list);
+]|
+
</description>
<parameters>
<parameter name="list1">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="list2">
-<parameter_description> the #GList to add to the end of the first #GList
+<parameter_description> the #GList to add to the end of the first #GList,
+this must point to the top of the list
</parameter_description>
</parameter>
</parameters>
-<return> the start of the new #GList
+<return> the start of the new #GList, which equals @list1 if not %NULL
</return>
</function>
@@ -21891,22 +21703,20 @@ They are used directly.
<description>
Copies a #GList.
-<note><para>
Note that this is a "shallow" copy. If the list elements
consist of pointers to data, the pointers are copied but
the actual data is not. See g_list_copy_deep() if you need
to copy the data as well.
-</para></note>
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
</parameters>
-<return> a copy of @list
+<return> the start of the new list that holds the same data as @list
</return>
</function>
@@ -21914,20 +21724,21 @@ to copy the data as well.
<description>
Makes a full (deep) copy of a #GList.
-In contrast with g_list_copy(), this function uses @func to make a copy of
-each list element, in addition to copying the list container itself.
+In contrast with g_list_copy(), this function uses @func to make
+a copy of each list element, in addition to copying the list
+container itself.
- func, as a #GCopyFunc, takes two arguments, the data to be copied and a user
-pointer. It's safe to pass #NULL as user_data, if the copy function takes only
-one argument.
+ func, as a #GCopyFunc, takes two arguments, the data to be copied
+and a @user_data pointer. It's safe to pass %NULL as user_data,
+if the copy function takes only one argument.
For instance, if @list holds a list of GObjects, you can do:
-|[
+|[<!-- language="C" -->
another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
]|
And, to entirely free the new list, you could do:
-|[
+|[<!-- language="C" -->
g_list_free_full (another_list, g_object_unref);
]|
@@ -21936,7 +21747,7 @@ Since: 2.34
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="func">
@@ -21944,11 +21755,12 @@ Since: 2.34
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> user data passed to the copy function @func, or #NULL
+<parameter_description> user data passed to the copy function @func, or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> a full copy of @list, use #g_list_free_full to free it
+<return> the start of the new list that holds a full copy of @list,
+use g_list_free_full() to free it
</return>
</function>
@@ -21963,7 +21775,7 @@ without freeing it.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="link_">
@@ -21971,20 +21783,19 @@ without freeing it.
</parameter_description>
</parameter>
</parameters>
-<return> the new head of @list
+<return> the (possibly changed) start of the #GList
</return>
</function>
<function name="g_list_find">
<description>
-Finds the element in a #GList which
-contains the given data.
+Finds the element in a #GList which contains the given data.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -21992,8 +21803,7 @@ contains the given data.
</parameter_description>
</parameter>
</parameters>
-<return> the found #GList element,
-or %NULL if it is not found
+<return> the found #GList element, or %NULL if it is not found
</return>
</function>
@@ -22010,7 +21820,7 @@ given user data.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22035,7 +21845,7 @@ Gets the first element in a #GList.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> any #GList element
</parameter_description>
</parameter>
</parameters>
@@ -22051,7 +21861,7 @@ Calls a function for each element of a #GList.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="func">
@@ -22071,11 +21881,8 @@ Calls a function for each element of a #GList.
Frees all of the memory used by a #GList.
The freed elements are returned to the slice allocator.
-<note><para>
-If list elements contain dynamically-allocated memory,
-you should either use g_list_free_full() or free them manually
-first.
-</para></note>
+If list elements contain dynamically-allocated memory, you should
+either use g_list_free_full() or free them manually first.
</description>
<parameters>
@@ -22114,8 +21921,8 @@ It is usually used after g_list_remove_link().
<function name="g_list_free_full">
<description>
-Convenience method, which frees all the memory used by a #GList, and
-calls the specified destroy function on every element's data.
+Convenience method, which frees all the memory used by a #GList,
+and calls @free_func on every element's data.
Since: 2.28
@@ -22142,7 +21949,7 @@ the given data (starting from 0).
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22163,7 +21970,7 @@ Inserts a new element into the list at the given position.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a pointer to a #GList
+<parameter_description> a pointer to a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22177,7 +21984,7 @@ list, the new element is added on to the end of the list.
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22189,7 +21996,7 @@ Inserts a new element into the list before the given position.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a pointer to a #GList
+<parameter_description> a pointer to a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="sibling">
@@ -22202,7 +22009,7 @@ is inserted or %NULL to insert at the end of the list
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22211,11 +22018,17 @@ is inserted or %NULL to insert at the end of the list
Inserts a new element into the list, using the given comparison
function to determine its position.
+If you are adding many new elements to a list, and the number of
+new elements is much larger than the length of the list, use
+g_list_prepend() to add the new items and sort the list afterwards
+with g_list_sort().
+
</description>
<parameters>
<parameter name="list">
-<parameter_description> a pointer to a #GList
+<parameter_description> a pointer to a #GList, this must point to the top of the
+already sorted list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22229,7 +22042,7 @@ second parameter in the sort order.
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22238,12 +22051,18 @@ second parameter in the sort order.
Inserts a new element into the list, using the given comparison
function to determine its position.
+If you are adding many new elements to a list, and the number of
+new elements is much larger than the length of the list, use
+g_list_prepend() to add the new items and sort the list afterwards
+with g_list_sort().
+
Since: 2.10
</description>
<parameters>
<parameter name="list">
-<parameter_description> a pointer to a #GList
+<parameter_description> a pointer to a #GList, this must point to the top of the
+already sorted list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22251,17 +22070,17 @@ Since: 2.10
</parameter_description>
</parameter>
<parameter name="func">
-<parameter_description> the function to compare elements in the list.
-It should return a number > 0 if the first parameter
-comes after the second parameter in the sort order.
+<parameter_description> the function to compare elements in the list. It should
+return a number > 0 if the first parameter comes after the
+second parameter in the sort order.
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> user data to pass to comparison function.
+<parameter_description> user data to pass to comparison function
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22274,11 +22093,11 @@ Gets the last element in a #GList.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> any #GList element
</parameter_description>
</parameter>
</parameters>
-<return> the last element in the #GList,
+<return> the last element in the #GList,
or %NULL if the #GList has no elements
</return>
</function>
@@ -22287,16 +22106,15 @@ or %NULL if the #GList has no elements
<description>
Gets the number of elements in a #GList.
-<note><para>
-This function iterates over the whole list to
-count its elements.
-</para></note>
+This function iterates over the whole list to count its elements.
+Use a #GQueue instead of a GList if you regularly need the number
+of items.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
</parameters>
@@ -22307,16 +22125,18 @@ count its elements.
<function name="g_list_next">
<description>
A convenience macro to get the next element in a #GList.
+Note that it is considered perfectly acceptable to access
+ list->next directly.
</description>
<parameters>
<parameter name="list">
-<parameter_description> an element in a #GList.
+<parameter_description> an element in a #GList
</parameter_description>
</parameter>
</parameters>
-<return> the next element, or %NULL if there are no more elements.
+<return> the next element, or %NULL if there are no more elements
</return>
</function>
@@ -22328,7 +22148,7 @@ Gets the element at the given position in a #GList.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="n">
@@ -22349,7 +22169,7 @@ Gets the data of the element at the given position.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="n">
@@ -22392,7 +22212,7 @@ in the #GList (starting from 0).
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="llink">
@@ -22407,25 +22227,27 @@ or -1 if the element is not found
<function name="g_list_prepend">
<description>
-Adds a new element on to the start of the list.
+Prepends a new element on to the start of the list.
-<note><para>
-The return value is the new start of the list, which
-may have changed, so make sure you store the new value.
-</para></note>
+Note that the return value is the new start of the list,
+which will have changed, so make sure you store the new value.
-|[
-/ * Notice that it is initialized to the empty list. * /
+|[<!-- language="C" -->
+// Notice that it is initialized to the empty list.
GList *list = NULL;
+
list = g_list_prepend (list, "last");
list = g_list_prepend (list, "first");
]|
+Do not use this function to prepend a new element to a different
+element than the start of the list. Use g_list_insert_before() instead.
+
</description>
<parameters>
<parameter name="list">
-<parameter_description> a pointer to a #GList
+<parameter_description> a pointer to a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22433,24 +22255,27 @@ list = g_list_prepend (list, "first");
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> a pointer to the newly prepended element, which is the new
+start of the #GList
</return>
</function>
<function name="g_list_previous">
<description>
A convenience macro to get the previous element in a #GList.
+Note that it is considered perfectly acceptable to access
+ list->previous directly.
</description>
<parameters>
<parameter name="list">
-<parameter_description> an element in a #GList.
+<parameter_description> an element in a #GList
</parameter_description>
</parameter>
</parameters>
<return> the previous element, or %NULL if there are no previous
-elements.
+elements
</return>
</function>
@@ -22464,7 +22289,7 @@ If none of the elements contain the data, the #GList is unchanged.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22472,7 +22297,7 @@ If none of the elements contain the data, the #GList is unchanged.
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22487,7 +22312,7 @@ matching the given data.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="data">
@@ -22495,7 +22320,7 @@ matching the given data.
</parameter_description>
</parameter>
</parameters>
-<return> new head of @list
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22505,11 +22330,20 @@ Removes an element from a #GList, without freeing the element.
The removed element's prev and next links are set to %NULL, so
that it becomes a self-contained list with one element.
+This function is for example used to move an element in the list
+(see the example for g_list_concat()) or to remove an element in
+the list before freeing its data:
+|[<!-- language="C" -->
+list = g_list_remove_link (list, llink);
+free_some_data_that_may_access_the_list_again (llink->data);
+g_list_free (llink);
+]|
+
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="llink">
@@ -22517,7 +22351,7 @@ that it becomes a self-contained list with one element.
</parameter_description>
</parameter>
</parameters>
-<return> the new start of the #GList, without the element
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22530,7 +22364,7 @@ It simply switches the next and prev pointers of each element.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
</parameters>
@@ -22547,7 +22381,7 @@ used is a stable sort.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="compare_func">
@@ -22559,7 +22393,7 @@ the first element comes after the second.
</parameter_description>
</parameter>
</parameters>
-<return> the start of the sorted #GList
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22572,7 +22406,7 @@ a user data argument.
</description>
<parameters>
<parameter name="list">
-<parameter_description> a #GList
+<parameter_description> a #GList, this must point to the top of the list
</parameter_description>
</parameter>
<parameter name="compare_func">
@@ -22584,7 +22418,7 @@ a user data argument.
</parameter_description>
</parameter>
</parameters>
-<return> the new head of @list
+<return> the (possibly changed) start of the #GList
</return>
</function>
@@ -22614,8 +22448,8 @@ list of strings which must be freed with g_strfreev().
<description>
Converts a string from UTF-8 to the encoding used for strings by
the C runtime (usually the same as that used by the operating
-system) in the <link linkend="setlocale">current locale</link>. On
-Windows this means the system codepage.
+system) in the [current locale][setlocale]. On Windows this means
+the system codepage.
</description>
@@ -22626,7 +22460,9 @@ Windows this means the system codepage.
</parameter>
<parameter name="len">
<parameter_description> the length of the string, or -1 if the string is
-nul-terminated<footnoteref linkend="nul-unsafe"/>.
+nul-terminated (Note that some encodings may allow nul
+bytes to occur inside strings. In that case, using -1
+for the @len parameter is unsafe)
</parameter_description>
</parameter>
<parameter name="bytes_read">
@@ -22660,8 +22496,7 @@ or %NULL on an error, and error will be set.
<description>
Converts a string which is in the encoding used for strings by
the C runtime (usually the same as that used by the operating
-system) in the <link linkend="setlocale">current locale</link> into a
-UTF-8 string.
+system) in the [current locale][setlocale] into a UTF-8 string.
</description>
@@ -22673,7 +22508,9 @@ this means the system codepage.
</parameter>
<parameter name="len">
<parameter_description> the length of the string, or -1 if the string is
-nul-terminated<footnoteref linkend="nul-unsafe"/>.
+nul-terminated (Note that some encodings may allow nul
+bytes to occur inside strings. In that case, using -1
+for the @len parameter is unsafe)
</parameter_description>
</parameter>
<parameter name="bytes_read">
@@ -22749,23 +22586,14 @@ manually included in @message.
The behavior of this log handler can be influenced by a number of
environment variables:
-<variablelist>
-<varlistentry>
-<term><envar>G_MESSAGES_PREFIXED</envar></term>
-<listitem>
-A :-separated list of log levels for which messages should
-be prefixed by the program name and PID of the aplication.
-</listitem>
-</varlistentry>
-<varlistentry>
-<term><envar>G_MESSAGES_DEBUG</envar></term>
-<listitem>
-A space-separated list of log domains for which debug and
-informational messages are printed. By default these
-messages are not printed.
-</listitem>
-</varlistentry>
-</variablelist>
+
+- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which
+messages should be prefixed by the program name and PID of the
+aplication.
+
+- `G_MESSAGES_DEBUG`: A space-separated list of log domains for
+which debug and informational messages are printed. By default
+these messages are not printed.
stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
@@ -22820,8 +22648,8 @@ You can only set the levels defined by GLib to be fatal.
%G_LOG_LEVEL_ERROR is always fatal.
You can also make some message levels fatal at runtime by setting
-the <envar>G_DEBUG</envar> environment variable (see
-<ulink url="glib-running.html">Running GLib Applications</ulink>).
+the `G_DEBUG` environment variable (see
+[Running GLib Applications](glib-running.html)).
</description>
@@ -22893,31 +22721,24 @@ Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
you want to set a handler for this log level you must combine it with
#G_LOG_FLAG_FATAL.
-<example>
-<title>Adding a log handler for all warning messages in the default
-(application) domain</title>
-<programlisting>
+Here is an example for adding a log handler for all warning messages
+in the default domain:
+|[<!-- language="C" -->
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
-</programlisting>
-</example>
+]|
-<example>
-<title>Adding a log handler for all critical messages from GTK+</title>
-<programlisting>
+This example adds a log handler for all critical messages from GTK+:
+|[<!-- language="C" -->
g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
-</programlisting>
-</example>
+]|
-<example>
-<title>Adding a log handler for <emphasis>all</emphasis> messages from
-GLib</title>
-<programlisting>
+This example adds a log handler for all messages from GLib:
+|[<!-- language="C" -->
g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
| G_LOG_FLAG_RECURSION, my_log_handler, NULL);
-</programlisting>
-</example>
+]|
</description>
@@ -22999,13 +22820,13 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="buf">
-<parameter_description> a pointer to a <structname>stat</structname> struct, which
-will be filled with the file information
+<parameter_description> a pointer to a stat struct, which will be filled with the file
+information
</parameter_description>
</parameter>
</parameters>
-<return> 0 if the information was successfully retrieved, -1 if an error
-occurred
+<return> 0 if the information was successfully retrieved,
+-1 if an error occurred
</return>
</function>
@@ -23067,6 +22888,9 @@ file descriptor is polled whenever the results may be needed.
<description>
Passes the results of polling back to the main loop.
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
</description>
<parameters>
@@ -23111,6 +22935,9 @@ g_main_context_get_thread_default().
<description>
Dispatches all pending sources.
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
</description>
<parameters>
<parameter name="context">
@@ -23159,7 +22986,7 @@ Finds a #GSource given a pair of context and ID.
</parameter_description>
</parameter>
<parameter name="source_id">
-<parameter_description> the source ID, as returned by g_source_get_id().
+<parameter_description> the source ID, as returned by g_source_get_id().
</parameter_description>
</parameter>
</parameters>
@@ -23211,7 +23038,7 @@ Gets the thread-default #GMainContext for this thread. Asynchronous
operations that want to be able to be run in contexts other than
the default one should call this method or
g_main_context_ref_thread_default() to get a #GMainContext to add
-their #GSource<!-- -->s to. (Note that even in single-threaded
+their #GSources to. (Note that even in single-threaded
programs applications may sometimes want to temporarily push a
non-default context, so it is not safe to assume that this will
always return %NULL if you are running in the default thread.)
@@ -23416,6 +23243,9 @@ Since: 2.22
Prepares to poll sources within a main loop. The resulting information
for polling is determined by calling g_main_context_query ().
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
</description>
<parameters>
@@ -23438,14 +23268,13 @@ prior to polling.
<description>
Acquires @context and sets it as the thread-default context for the
current thread. This will cause certain asynchronous operations
-(such as most <link linkend="gio">gio</link>-based I/O) which are
+(such as most [gio][gio]-based I/O) which are
started in this thread to run under @context and deliver their
results to its main loop, rather than running under the global
default context in the main thread. Note that calling this function
-changes the context returned by
-g_main_context_get_thread_default(), <emphasis>not</emphasis> the
-one returned by g_main_context_default(), so it does not affect the
-context used by functions like g_idle_add().
+changes the context returned by g_main_context_get_thread_default(),
+not the one returned by g_main_context_default(), so it does not affect
+the context used by functions like g_idle_add().
Normally you would call this function shortly after creating a new
thread, passing it a #GMainContext which will be run by a
@@ -23481,6 +23310,9 @@ Since: 2.22
<description>
Determines information necessary to poll this main loop.
+You must have successfully acquired the context with
+g_main_context_acquire() before you may call this function.
+
</description>
<parameters>
@@ -23666,7 +23498,7 @@ example, integrating it with main loop implementations such as
Another related use for this function is when implementing a main
loop with a termination condition, computed from multiple threads:
-|[
+|[<!-- language="C" -->
#define NUM_TASKS 10
static volatile gint tasks_remaining = NUM_TASKS;
...
@@ -23676,7 +23508,7 @@ g_main_context_iteration (NULL, TRUE);
]|
Then in a thread:
-|[
+|[<!-- language="C" -->
perform_work();
if (g_atomic_int_dec_and_test (&tasks_remaining))
@@ -23720,7 +23552,7 @@ it returns 2. And so forth.
This function is useful in a situation like the following:
Imagine an extremely simple "garbage collected" system.
-|[
+|[<!-- language="C" -->
static GList *free_list;
gpointer
@@ -23757,7 +23589,7 @@ function to make the call to free_allocated_memory(), but that
doesn't work, since the idle function could be called from a
recursive callback. This can be fixed by using g_main_depth()
-|[
+|[<!-- language="C" -->
gpointer
allocate_memory (gsize size)
{
@@ -23802,23 +23634,14 @@ these checks all over your code, since there are doubtless many,
many things that the user could do. Instead, you can use the
following techniques:
-<orderedlist>
-<listitem>
-<para>
-Use gtk_widget_set_sensitive() or modal dialogs to prevent
+1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
the user from interacting with elements while the main
loop is recursing.
-</para>
-</listitem>
-<listitem>
-<para>
-Avoid main loop recursion in situations where you can't handle
+
+2. Avoid main loop recursion in situations where you can't handle
arbitrary callbacks. Instead, structure your code so that you
simply return to the main loop and then get called again when
there is more work to do.
-</para>
-</listitem>
-</orderedlist>
</description>
@@ -24743,7 +24566,7 @@ interface.
As an example, see the following implementation of a simple
parser that counts the number of tags encountered.
-|[
+|[<!-- language="C" -->
typedef struct
{
gint tag_count;
@@ -24785,7 +24608,7 @@ counter_error
In order to allow this parser to be easily used as a subparser, the
following interface is provided:
-|[
+|[<!-- language="C" -->
void
start_counting (GMarkupParseContext *context)
{
@@ -24810,13 +24633,13 @@ return result;
The subparser would then be used as follows:
-|[
+|[<!-- language="C" -->
static void start_element (context, element_name, ...)
{
if (strcmp (element_name, "count-these") == 0)
start_counting (context);
-/ * else, handle other tags... * /
+// else, handle other tags...
}
static void end_element (context, element_name, ...)
@@ -24824,7 +24647,7 @@ static void end_element (context, element_name, ...)
if (strcmp (element_name, "count-these") == 0)
g_print ("Counted %d tags\n", end_counting (context));
-/ * else, handle other tags... * /
+// else, handle other tags...
}
]|
@@ -24892,11 +24715,11 @@ want to insert literal strings into XML-style markup
output, without having to worry that the strings
might themselves contain markup.
-|[
+|[<!-- language="C" -->
const char *store = "Fortnum & Mason";
const char *item = "Tea";
char *output;
- 
+
output = g_markup_printf_escaped ("<purchase>"
"<store>%s</store>"
"<item>%s</item>"
@@ -24992,7 +24815,7 @@ Since: 2.14
<function name="g_match_info_fetch">
<description>
-Retrieves the text matching the @match_num<!-- -->'th capturing
+Retrieves the text matching the @match_num'th capturing
parentheses. 0 is the full text of the match, 1 is the first paren
set, 2 the second, and so on.
@@ -25133,7 +24956,7 @@ are left unchanged.
<function name="g_match_info_fetch_pos">
<description>
-Retrieves the position in bytes of the @match_num<!-- -->'th capturing
+Retrieves the position in bytes of the @match_num'th capturing
parentheses. 0 is the full text of the match, 1 is the first
paren set, 2 the second, and so on.
@@ -25293,7 +25116,7 @@ are set, the latter takes precedence.
There were formerly some restrictions on the pattern for partial matching.
The restrictions no longer apply.
-See <ulink>man:pcrepartial</ulink> for more information on partial matching.
+See pcrepartial(3) for more information on partial matching.
Since: 2.14
@@ -25392,8 +25215,8 @@ Since: 2.30
<function name="g_mem_gc_friendly">
<description>
-This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
-includes the key <literal>gc-friendly</literal>.
+This variable is %TRUE if the `G_DEBUG` environment variable
+includes the key `gc-friendly`.
</description>
<parameters>
@@ -25440,13 +25263,17 @@ previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
<function name="g_mem_set_vtable">
<description>
-Sets the #GMemVTable to use for memory allocation. You can use this to provide
-custom memory allocation routines. <emphasis>This function must be called
-before using any other GLib functions.</emphasis> The @vtable only needs to
-provide malloc(), realloc(), and free() functions; GLib can provide default
-implementations of the others. The malloc() and realloc() implementations
-should return %NULL on failure, GLib will handle error-checking for you.
- vtable is copied, so need not persist after this function has been called.
+Sets the #GMemVTable to use for memory allocation. You can use this
+to provide custom memory allocation routines.
+
+The @vtable only needs to provide malloc(), realloc(), and free()
+functions; GLib can provide default implementations of the others.
+The malloc() and realloc() implementations should return %NULL on
+failure, GLib will handle error-checking for you. @vtable is copied,
+so need not persist after this function has been called.
+
+Note that this function must be called before using any other GLib
+functions.
</description>
<parameters>
@@ -25720,17 +25547,16 @@ standard platform-specific directory, though this is not recommended
since the wrong module may be found.
For example, calling g_module_build_path() on a Linux system with a
- directory of <filename>/lib</filename> and a @module_name of "mylibrary"
-will return <filename>/lib/libmylibrary.so</filename>. On a Windows system,
-using <filename>\Windows</filename> as the directory it will return
-<filename>\Windows\mylibrary.dll</filename>.
+ directory of `/lib` and a @module_name of "mylibrary" will return
+`/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+directory it will return `\Windows\mylibrary.dll`.
</description>
<parameters>
<parameter name="directory">
-<parameter_description> the directory where the module is. This can be %NULL
-or the empty string to indicate that the standard platform-specific
+<parameter_description> the directory where the module is. This can be
+%NULL or the empty string to indicate that the standard platform-specific
directories will be used, though that is not recommended
</parameter_description>
</parameter>
@@ -25926,7 +25752,7 @@ allocated on the stack, or as part of a larger structure.
It is not necessary to initialize a mutex that has been
statically allocated.
-|[
+|[<!-- language="C" -->
typedef struct {
GMutex m;
...
@@ -25962,10 +25788,10 @@ Locks @mutex. If @mutex is already locked by another thread, the
current thread will block until @mutex is unlocked by the other
thread.
-<note>#GMutex is neither guaranteed to be recursive nor to be
+#GMutex is neither guaranteed to be recursive nor to be
non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
already been locked by the same thread results in undefined behaviour
-(including but not limited to deadlocks).</note>
+(including but not limited to deadlocks).
</description>
<parameters>
@@ -25998,11 +25824,10 @@ Tries to lock @mutex. If @mutex is already locked by another thread,
it immediately returns %FALSE. Otherwise it locks @mutex and returns
%TRUE.
-<note>#GMutex is neither guaranteed to be recursive nor to be
+#GMutex is neither guaranteed to be recursive nor to be
non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
already been locked by the same thread results in undefined behaviour
(including but not limited to deadlocks or arbitrary return values).
-</note>
</description>
@@ -26910,8 +26735,8 @@ only a weak reference is held in the reverse direction from @object
to the proxy object, but when there are other references held to
@object, a strong reference is held. The @notify callback is called
when the reference from @object to the proxy object should be
-<firstterm>toggled</firstterm> from strong to weak (@is_last_ref
-true) or weak to strong (@is_last_ref false).
+"toggled" from strong to weak (@is_last_ref true) or weak to strong
+(@is_last_ref false).
Since a (normal) reference must be held to the object before
calling g_object_add_toggle_ref(), the initial state of the reverse
@@ -27048,11 +26873,11 @@ The binding will automatically be removed when either the @source or the
A #GObject can have multiple bindings.
-<note>The same @user_data parameter will be used for both @transform_to
+The same @user_data parameter will be used for both @transform_to
and @transform_from transformation functions; the @notify function will
be called once, when the binding is removed. If you need different data
for each transformation function, please use
-g_object_bind_property_with_closures() instead.</note>
+g_object_bind_property_with_closures() instead.
Since: 2.26
@@ -27113,7 +26938,7 @@ on @target, allowing you to set the transformation functions to be used by
the binding.
This function is the language bindings friendly version of
-g_object_bind_property_full(), using #GClosure<!-- -->s instead of
+g_object_bind_property_full(), using #GClosures instead of
function pointers.
Since: 2.26
@@ -27181,7 +27006,7 @@ Looks up the #GParamSpec for a property of a class.
<function name="g_object_class_install_properties">
<description>
-Installs new properties from an array of #GParamSpec<!-- -->s. This is
+Installs new properties from an array of #GParamSpecs. This is
usually done in the class initializer.
The property id of each property is the index of each #GParamSpec in
@@ -27191,10 +27016,10 @@ The property id of 0 is treated specially by #GObject and it should not
be used to store a #GParamSpec.
This function should be used if you plan to use a static array of
-#GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this
+#GParamSpecs and g_object_notify_by_pspec(). For instance, this
class initialization:
-|[
+|[<!-- language="C" -->
enum {
PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
};
@@ -27227,7 +27052,7 @@ obj_properties);
allows calling g_object_notify_by_pspec() to notify of property changes:
-|[
+|[<!-- language="C" -->
void
my_object_set_foo (MyObject *self, gint foo)
{
@@ -27248,11 +27073,11 @@ Since: 2.26
</parameter_description>
</parameter>
<parameter name="n_pspecs">
-<parameter_description> the length of the #GParamSpec<!-- -->s array
+<parameter_description> the length of the #GParamSpecs array
</parameter_description>
</parameter>
<parameter name="pspecs">
-<parameter_description> the #GParamSpec<!-- -->s array
+<parameter_description> the #GParamSpecs array
defining the new properties
</parameter_description>
</parameter>
@@ -27309,13 +27134,12 @@ Get an array of #GParamSpec* for all properties of a class.
<function name="g_object_class_override_property">
<description>
-Registers @property_id as referring to a property with the
-name @name in a parent class or in an interface implemented
-by @oclass. This allows this class to <firstterm>override</firstterm>
-a property implementation in a parent class or to provide
-the implementation of a property from an interface.
+Registers @property_id as referring to a property with the name
+ name in a parent class or in an interface implemented by @oclass.
+This allows this class to "override" a property implementation in
+a parent class or to provide the implementation of a property from
+an interface.
-<note>
Internally, overriding is implemented by creating a property of type
#GParamSpecOverride; generally operations that query the properties of
the object class, such as g_object_class_find_property() or
@@ -27326,7 +27150,6 @@ instead, so that the @param_id field of the #GParamSpec will be
correct. For virtually all uses, this makes no difference. If you
need to get the overridden property, you can call
g_param_spec_get_redirect_target().
-</note>
Since: 2.4
@@ -27355,65 +27178,16 @@ A convenience function to connect multiple signals at once.
The signal specs expected by this function have the form
"modifier::signal_name", where modifier can be one of the following:
-<variablelist>
-<varlistentry>
-<term>signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, 0)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>object_signal</term>
-<term>object-signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., 0)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_signal</term>
-<term>swapped-signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_object_signal</term>
-<term>swapped-object-signal</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>signal_after</term>
-<term>signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>object_signal_after</term>
-<term>object-signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_signal_after</term>
-<term>swapped-signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED |
G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>swapped_object_signal_after</term>
-<term>swapped-object-signal-after</term>
-<listitem><para>
-equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED |
G_CONNECT_AFTER)</literal>
-</para></listitem>
-</varlistentry>
-</variablelist>
-
-|[
+* - signal: equivalent to g_signal_connect_data (..., NULL, 0)
+- object-signal, object_signal: equivalent to g_signal_connect_object (..., 0)
+- swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)
+- swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (...,
G_CONNECT_SWAPPED)
+- signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER)
+- object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER)
+- swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL,
G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+- swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (...,
G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+
+|[<!-- language="C" -->
menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
"type", GTK_WINDOW_POPUP,
"child", menu,
@@ -27569,11 +27343,10 @@ unmodified.
<function name="g_object_force_floating">
<description>
-This function is intended for #GObject implementations to re-enforce a
-<link linkend="floating-ref">floating</link> object reference.
-Doing this is seldom required: all
-#GInitiallyUnowned<!-- -->s are created with a floating reference which
-usually just needs to be sunken by calling g_object_ref_sink().
+This function is intended for #GObject implementations to re-enforce
+a [floating][floating-ref] object reference. Doing this is seldom
+required: all #GInitiallyUnowneds are created with a floating reference
+which usually just needs to be sunken by calling g_object_ref_sink().
Since: 2.10
@@ -27617,12 +27390,9 @@ In general, a copy is made of the property contents and the caller
is responsible for freeing the memory in the appropriate manner for
the type, for instance by calling g_free() or g_object_unref().
-<example>
-<title>Using g_object_get(<!-- -->)</title>
-An example of using g_object_get() to get the contents
-of three properties - one of type #G_TYPE_INT,
-one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
-<programlisting>
+Here is an example of using g_object_get() to get the contents
+of three properties: an integer, a string and an object:
+|[<!-- language="C" -->
gint intval;
gchar *strval;
GObject *objval;
@@ -27637,8 +27407,7 @@ NULL);
g_free (strval);
g_object_unref (objval);
-</programlisting>
-</example>
+]|
</description>
<parameters>
@@ -27854,8 +27623,7 @@ it.
<function name="g_object_is_floating">
<description>
-Checks whether @object has a <link linkend="floating-ref">floating</link>
-reference.
+Checks whether @object has a [floating][floating-ref] reference.
Since: 2.10
@@ -27994,7 +27762,7 @@ class that registered the properties, and using g_object_notify_by_pspec()
instead, is to store the GParamSpec used with
g_object_class_install_property() inside a static array, e.g.:
-|[
+|[<!-- language="C" -->
enum
{
PROP_0,
@@ -28019,7 +27787,7 @@ properties[PROP_FOO]);
and then notify a change on the "foo" property with:
-|[
+|[<!-- language="C" -->
g_object_notify_by_pspec (self, properties[PROP_FOO]);
]|
@@ -28058,8 +27826,7 @@ Increases the reference count of @object.
<function name="g_object_ref_sink">
<description>
Increase the reference count of @object, and possibly remove the
-<link linkend="floating-ref">floating</link> reference, if @object
-has a floating reference.
+[floating][floating-ref] reference, if @object has a floating reference.
In other words, if the object is floating, then this call "assumes
ownership" of the floating reference, converting it to a normal
@@ -28464,7 +28231,7 @@ without invoking its destroy() function (if any was
set).
Usually, calling this function is only required to update
user data pointers with a destroy notifier, for example:
-|[
+|[<!-- language="C" -->
void
object_add_to_user_list (GObject *object,
const gchar *new_string)
@@ -28629,13 +28396,13 @@ Removes a weak reference callback to an object.
<function name="g_on_error_query">
<description>
Prompts the user with
-<computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
+`[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
This function is intended to be used for debugging use only.
The following example shows how it can be used together with
the g_log() functions.
-|[
-#include <glib.h>
+|[<!-- language="C" -->
+#include <glib.h>
static void
log_handler (const gchar *log_domain,
@@ -28657,27 +28424,27 @@ G_LOG_LEVEL_ERROR |
G_LOG_LEVEL_CRITICAL,
log_handler,
NULL);
-/ * ... * /
+...
]|
-If [E]xit is selected, the application terminates with a call
-to <literal>_exit(0)</literal>.
+If "[E]xit" is selected, the application terminates with a call
+to _exit(0).
-If [S]tack trace is selected, g_on_error_stack_trace() is called.
-This invokes <command>gdb</command>, which attaches to the current
-process and shows a stack trace. The prompt is then shown again.
+If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
+This invokes gdb, which attaches to the current process and shows
+a stack trace. The prompt is then shown again.
-If [P]roceed is selected, the function returns.
+If "[P]roceed" is selected, the function returns.
This function may cause different actions on non-UNIX platforms.
</description>
<parameters>
<parameter name="prg_name">
-<parameter_description> the program name, needed by <command>gdb</command>
-for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname()
-is called to get the program name (which will work correctly if
-gdk_init() or gtk_init() has been called)
+<parameter_description> the program name, needed by gdb for the "[S]tack trace"
+option. If @prg_name is %NULL, g_get_prgname() is called to get
+the program name (which will work correctly if gdk_init() or
+gtk_init() has been called)
</parameter_description>
</parameter>
</parameters>
@@ -28686,19 +28453,19 @@ gdk_init() or gtk_init() has been called)
<function name="g_on_error_stack_trace">
<description>
-Invokes <command>gdb</command>, which attaches to the current
-process and shows a stack trace. Called by g_on_error_query()
-when the [S]tack trace option is selected. You can get the current
-process's "program name" with g_get_prgname(), assuming that you
-have called gtk_init() or gdk_init().
+Invokes gdb, which attaches to the current process and shows a
+stack trace. Called by g_on_error_query() when the "[S]tack trace"
+option is selected. You can get the current process's program name
+with g_get_prgname(), assuming that you have called gtk_init() or
+gdk_init().
This function may cause different actions on non-UNIX platforms.
</description>
<parameters>
<parameter name="prg_name">
-<parameter_description> the program name, needed by <command>gdb</command>
-for the [S]tack trace option.
+<parameter_description> the program name, needed by gdb for the "[S]tack trace"
+option
</parameter_description>
</parameter>
</parameters>
@@ -28720,7 +28487,7 @@ that the initialization is serialized across multiple threads.
Calling g_once() recursively on the same #GOnce struct in
@func will lead to a deadlock.
-|[
+|[<!-- language="C" -->
gpointer
get_debug_flags (void)
{
@@ -28766,17 +28533,17 @@ during a program's life time, and that concurrent threads are
blocked until initialization completed. To be used in constructs
like this:
-|[
+|[<!-- language="C" -->
static gsize initialization_value = 0;
if (g_once_init_enter (&initialization_value))
{
-gsize setup_value = 42; / ** initialization code here ** /
+gsize setup_value = 42; // initialization code here
g_once_init_leave (&initialization_value, setup_value);
}
-/ ** use initialization_value here ** /
+// use initialization_value here
]|
Since: 2.14
@@ -28856,8 +28623,9 @@ Since: 2.6
</parameter_description>
</parameter>
</parameters>
-<return> a new file descriptor, or -1 if an error occurred. The
-return value can be used exactly like the return value from open().
+<return> a new file descriptor, or -1 if an error occurred.
+The return value can be used exactly like the return value
+from open().
</return>
</function>
@@ -28900,12 +28668,12 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="entries">
-<parameter_description> a %NULL-terminated array of #GOptionEntry<!-- -->s
+<parameter_description> a %NULL-terminated array of #GOptionEntrys
</parameter_description>
</parameter>
<parameter name="translation_domain">
<parameter_description> a translation domain to use for translating
-the <option>--help</option> output for the options in @entries
+the `--help` output for the options in @entries
with gettext(), or %NULL
</parameter_description>
</parameter>
@@ -28954,12 +28722,12 @@ Since: 2.12
<function name="g_option_context_get_help">
<description>
Returns a formatted, translated help text for the given context.
-To obtain the text produced by <option>--help</option>, call
-<literal>g_option_context_get_help (context, TRUE, NULL)</literal>.
-To obtain the text produced by <option>--help-all</option>, call
-<literal>g_option_context_get_help (context, FALSE, NULL)</literal>.
+To obtain the text produced by `--help`, call
+`g_option_context_get_help (context, TRUE, NULL)`.
+To obtain the text produced by `--help-all`, call
+`g_option_context_get_help (context, FALSE, NULL)`.
To obtain the help text for an option group, call
-<literal>g_option_context_get_help (context, FALSE, group)</literal>.
+`g_option_context_get_help (context, FALSE, group)`.
Since: 2.14
@@ -28985,7 +28753,7 @@ Since: 2.14
<function name="g_option_context_get_help_enabled">
<description>
-Returns whether automatic <option>--help</option> generation
+Returns whether automatic `--help` generation
is turned on for @context. See g_option_context_set_help_enabled().
Since: 2.6
@@ -29087,9 +28855,8 @@ Since: 2.6
<parameters>
<parameter name="parameter_string">
<parameter_description> a string which is displayed in
-the first line of <option>--help</option> output, after the
-usage summary
-<literal><replaceable>programname</replaceable> [OPTION...]</literal>
+the first line of `--help` output, after the usage summary
+`programname [OPTION...]`
</parameter_description>
</parameter>
</parameters>
@@ -29113,14 +28880,13 @@ unless there are unparsed options before and after it,
or some of the options after it start with '-'. In case
of an error, @argc and @argv are left unmodified.
-If automatic <option>--help</option> support is enabled
+If automatic `--help` support is enabled
(see g_option_context_set_help_enabled()), and the
@argv array contains one of the recognized help options,
this function will produce help output to stdout and
-call <literal>exit (0)</literal>.
+call `exit (0)`.
-Note that function depends on the
-<link linkend="setlocale">current locale</link> for
+Note that function depends on the [current locale][setlocale] for
automatic character set conversion of string and filename
arguments.
@@ -29162,6 +28928,11 @@ assuming that the passed-in array is the argv of the main function.
In particular, strings that are removed from the arguments list will
be freed using g_free().
+On Windows, the strings are expected to be in UTF-8. This is in
+contrast to g_option_context_parse() which expects them to be in the
+system codepage, which is how they are passed as @argv to main().
+See g_win32_get_command_line() for a solution.
+
This function is useful if you are trying to use #GOptionContext with
#GApplication.
@@ -29174,7 +28945,8 @@ Since: 2.40
</parameter_description>
</parameter>
<parameter name="arguments">
-<parameter_description> a pointer to the command line arguments
+<parameter_description> a pointer to the
+command line arguments (which must be in UTF-8 on Windows)
</parameter_description>
</parameter>
<parameter name="error">
@@ -29190,9 +28962,8 @@ Since: 2.40
<function name="g_option_context_set_description">
<description>
-Adds a string to be displayed in <option>--help</option> output
-after the list of options. This text often includes a bug reporting
-address.
+Adds a string to be displayed in `--help` output after the list
+of options. This text often includes a bug reporting address.
Note that the summary is translated (see
g_option_context_set_translate_func()).
@@ -29206,7 +28977,7 @@ Since: 2.12
</parameter_description>
</parameter>
<parameter name="description">
-<parameter_description> a string to be shown in <option>--help</option> output
+<parameter_description> a string to be shown in `--help` output
after the list of options, or %NULL
</parameter_description>
</parameter>
@@ -29216,12 +28987,10 @@ after the list of options, or %NULL
<function name="g_option_context_set_help_enabled">
<description>
-Enables or disables automatic generation of <option>--help</option>
-output. By default, g_option_context_parse() recognizes
-<option>--help</option>, <option>-h</option>,
-<option>-?</option>, <option>--help-all</option>
-and <option>--help-</option><replaceable>groupname</replaceable> and creates
-suitable output to stdout.
+Enables or disables automatic generation of `--help` output.
+By default, g_option_context_parse() recognizes `--help`, `-h`,
+`-?`, `--help-all` and `--help-groupname` and creates suitable
+output to stdout.
Since: 2.6
@@ -29232,7 +29001,7 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="help_enabled">
-<parameter_description> %TRUE to enable <option>--help</option>, %FALSE to disable it
+<parameter_description> %TRUE to enable `--help`, %FALSE to disable it
</parameter_description>
</parameter>
</parameters>
@@ -29271,7 +29040,7 @@ an error when unknown options are met
Sets a #GOptionGroup as main group of the @context.
This has the same effect as calling g_option_context_add_group(),
the only difference is that the options in the main group are
-treated differently when generating <option>--help</option> output.
+treated differently when generating `--help` output.
Since: 2.6
@@ -29291,9 +29060,8 @@ Since: 2.6
<function name="g_option_context_set_summary">
<description>
-Adds a string to be displayed in <option>--help</option> output
-before the list of options. This is typically a summary of the
-program functionality.
+Adds a string to be displayed in `--help` output before the list
+of options. This is typically a summary of the program functionality.
Note that the summary is translated (see
g_option_context_set_translate_func() and
@@ -29308,7 +29076,7 @@ Since: 2.12
</parameter_description>
</parameter>
<parameter name="summary">
-<parameter_description> a string to be shown in <option>--help</option> output
+<parameter_description> a string to be shown in `--help` output
before the list of options, or %NULL
</parameter_description>
</parameter>
@@ -29319,8 +29087,8 @@ before the list of options, or %NULL
<function name="g_option_context_set_translate_func">
<description>
Sets the function which is used to translate the contexts
-user-visible strings, for <option>--help</option> output.
-If @func is %NULL, strings are not translated.
+user-visible strings, for `--help` output. If @func is %NULL,
+strings are not translated.
Note that option groups have their own translation functions,
this function only affects the @parameter_string (see g_option_context_new()),
@@ -29388,7 +29156,7 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="entries">
-<parameter_description> a %NULL-terminated array of #GOptionEntry<!-- -->s
+<parameter_description> a %NULL-terminated array of #GOptionEntrys
</parameter_description>
</parameter>
</parameters>
@@ -29397,8 +29165,8 @@ Since: 2.6
<function name="g_option_group_free">
<description>
-Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis>
-free groups which have been added to a #GOptionContext.
+Frees a #GOptionGroup. Note that you must not free groups
+which have been added to a #GOptionContext.
Since: 2.6
@@ -29422,17 +29190,17 @@ Since: 2.6
<parameters>
<parameter name="name">
<parameter_description> the name for the option group, this is used to provide
-help for the options in this group with <option>--help-</option>@name
+help for the options in this group with `--help-` name
</parameter_description>
</parameter>
<parameter name="description">
<parameter_description> a description for this group to be shown in
-<option>--help</option>. This string is translated using the translation
+`--help`. This string is translated using the translation
domain or translation function of the group
</parameter_description>
</parameter>
<parameter name="help_description">
-<parameter_description> a description for the <option>--help-</option>@name option.
+<parameter_description> a description for the `--help-` name option.
This string is translated using the translation domain or translation function
of the group
</parameter_description>
@@ -29509,10 +29277,9 @@ Since: 2.6
<function name="g_option_group_set_translate_func">
<description>
-Sets the function which is used to translate user-visible
-strings, for <option>--help</option> output. Different
-groups can use different #GTranslateFunc<!-- -->s. If @func
-is %NULL, strings are not translated.
+Sets the function which is used to translate user-visible strings,
+for `--help` output. Different groups can use different
+#GTranslateFuncs. If @func is %NULL, strings are not translated.
If you are using gettext(), you only need to set the translation
domain, see g_option_group_set_translation_domain().
@@ -30087,7 +29854,7 @@ used, but they cannot be mixed. Using '-' is considerably more
efficient and in fact required when using property names as detail
strings for signals.
-Beyond the name, #GParamSpec<!-- -->s have two more descriptive
+Beyond the name, #GParamSpecs have two more descriptive
strings associated with them, the @nick, which should be suitable
for use as a label for the property in a property editor, and the
@blurb, which should be a somewhat longer description, suitable for
@@ -30311,7 +30078,7 @@ Inserts a #GParamSpec in the pool.
<function name="g_param_spec_pool_list">
<description>
-Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
+Gets an array of all #GParamSpecs owned by @owner_type in
the pool.
@@ -30338,7 +30105,7 @@ owned by @owner_type in the pool
<function name="g_param_spec_pool_list_owned">
<description>
-Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
+Gets an #GList of all #GParamSpecs owned by @owner_type in
the pool.
@@ -30354,8 +30121,8 @@ the pool.
</parameter>
</parameters>
<return> a
-#GList of all #GParamSpec<!-- -->s owned by @owner_type in
-the pool#GParamSpec<!-- -->s.
+#GList of all #GParamSpecs owned by @owner_type in
+the pool#GParamSpecs.
</return>
</function>
@@ -30491,7 +30258,7 @@ set, using %NULL as pointer essentially removes the data stored.
<function name="g_param_spec_set_qdata_full">
<description>
This function works like g_param_spec_set_qdata(), but in addition,
-a <literal>void (*destroy) (gpointer)</literal> function may be
+a `void (*destroy) (gpointer)` function may be
specified which is called with @data as argument when the @pspec is
finalized, or the data is being overwritten by a call to
g_param_spec_set_qdata() with the same @quark.
@@ -30524,8 +30291,8 @@ be freed
The initial reference count of a newly created #GParamSpec is 1,
even though no one has explicitly called g_param_spec_ref() on it
yet. So the initial reference count is flagged as "floating", until
-someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink
-(pspec);</literal> in sequence on it, taking over the initial
+someone calls `g_param_spec_ref (pspec); g_param_spec_sink
+(pspec);` in sequence on it, taking over the initial
reference count (thus ending up with a @pspec that has a reference
count of 1 still, but is not flagged "floating" anymore).
@@ -31051,12 +30818,12 @@ into a %guint containing bit flags. This is used
within GDK and GTK+ to parse the debug options passed on the
command line or through environment variables.
-If @string is equal to <code>"all"</code>, all flags are set. Any flags
-specified along with <code>"all"</code> in @string are inverted; thus,
-<code>"all,foo,bar"</code> or <code>"foo,bar,all"</code> sets
all flags
-except those corresponding to <code>"foo"</code> and
<code>"bar"</code>.
+If @string is equal to "all", all flags are set. Any flags
+specified along with "all" in @string are inverted; thus,
+"all,foo,bar" or "foo,bar,all" sets all flags except those
+corresponding to "foo" and "bar".
-If @string is equal to <code>"help"</code>, all the available keys in @keys
+If @string is equal to "help", all the available keys in @keys
are printed out to standard error.
@@ -31073,7 +30840,7 @@ strings with bit flags.
</parameter_description>
</parameter>
<parameter name="nkeys">
-<parameter_description> the number of #GDebugKey<!-- -->s in the array.
+<parameter_description> the number of #GDebugKeys in the array.
</parameter_description>
</parameter>
</parameters>
@@ -31195,10 +30962,9 @@ more efficient to provide the reversed string to avoid multiple
constructions thereof in the various calls to g_pattern_match().
Note also that the reverse of a UTF-8 encoded string can in general
-<emphasis>not</emphasis> be obtained by g_strreverse(). This works
-only if the string doesn't contain any multibyte characters. GLib
-offers the g_utf8_strreverse() function to reverse UTF-8 encoded
-strings.
+not be obtained by g_strreverse(). This works only if the string
+does not contain any multibyte characters. GLib offers the
+g_utf8_strreverse() function to reverse UTF-8 encoded strings.
</description>
@@ -31209,7 +30975,7 @@ strings.
</parameter>
<parameter name="string_length">
<parameter_description> the length of @string (in bytes, i.e. strlen(),
-<emphasis>not</emphasis> g_utf8_strlen())
+not g_utf8_strlen())
</parameter_description>
</parameter>
<parameter name="string">
@@ -31430,7 +31196,7 @@ On POSIX systems, the file descriptors in @fds can be any sort of
file descriptor, but the situation is much more complicated on
Windows. If you need to use g_poll() in code that has to run on
Windows, the easiest solution is to construct all of your
-#GPollFD<!-- -->s with g_io_channel_win32_make_pollfd().
+#GPollFDs with g_io_channel_win32_make_pollfd().
Since: 2.20
@@ -31458,16 +31224,13 @@ if the call was interrupted.
<function name="g_prefix_error">
<description>
-Formats a string according to @format and
-prefix it to an existing error message. If
- err is %NULL (ie: no error variable) then do
+Formats a string according to @format and prefix it to an existing
+error message. If @err is %NULL (ie: no error variable) then do
nothing.
-If * err is %NULL (ie: an error variable is
-present but there is no error condition) then
-also do nothing. Whether or not it makes
-sense to take advantage of this feature is up
-to you.
+If * err is %NULL (ie: an error variable is present but there is no
+error condition) then also do nothing. Whether or not it makes sense
+to take advantage of this feature is up to you.
Since: 2.16
@@ -31556,7 +31319,7 @@ Since: 2.2
<parameters>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="Varargs">
@@ -31697,9 +31460,8 @@ The error variable @dest points to must be %NULL.
<function name="g_propagate_prefixed_error">
<description>
-If @dest is %NULL, free @src; otherwise,
-moves @src into * dest * dest must be %NULL.
-After the move, add a prefix as with
+If @dest is %NULL, free @src; otherwise, moves @src into * dest
+* dest must be %NULL. After the move, add a prefix as with
g_prefix_error().
Since: 2.16
@@ -31734,11 +31496,11 @@ in size automatically if necessary.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the pointer to add.
+<parameter_description> the pointer to add
</parameter_description>
</parameter>
</parameters>
@@ -31778,19 +31540,19 @@ underlying array for use elsewhere. If the reference count of @array
is greater than one, the #GPtrArray wrapper is preserved but the
size of @array will be set to zero.
-<note><para>If array contents point to dynamically-allocated
-memory, they should be freed separately if @free_seg is %TRUE and no
-#GDestroyNotify function has been set for @array.</para></note>
+If array contents point to dynamically-allocated memory, they should
+be freed separately if @free_seg is %TRUE and no #GDestroyNotify
+function has been set for @array.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="free_seg">
-<parameter_description> if %TRUE the actual pointer array is freed as well.
+<parameter_description> if %TRUE the actual pointer array is freed as well
</parameter_description>
</parameter>
</parameters>
@@ -31803,23 +31565,22 @@ The pointer array should be freed using g_free().
<description>
Returns the pointer at the given index of the pointer array.
-<note><para>
-This does not perform bounds checking on the given @index_, so you are
-responsible for checking it against the array length.</para></note>
+This does not perform bounds checking on the given @index_,
+so you are responsible for checking it against the array length.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the pointer to return.
+<parameter_description> the index of the pointer to return
</parameter_description>
</parameter>
</parameters>
-<return> the pointer at the given index.
+<return> the pointer at the given index
</return>
</function>
@@ -31833,11 +31594,11 @@ Since: 2.40
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index to place the new element at, or -1 to append.
+<parameter_description> the index to place the new element at, or -1 to append
</parameter_description>
</parameter>
<parameter name="data">
@@ -31856,7 +31617,7 @@ Creates a new #GPtrArray with a reference count of 1.
</description>
<parameters>
</parameters>
-<return> the new #GPtrArray.
+<return> the new #GPtrArray
</return>
</function>
@@ -31867,44 +31628,46 @@ and a reference count of 1. This avoids frequent reallocation, if
you are going to add many pointers to the array. Note however that
the size of the array is still 0. It also set @element_free_func
for freeing each element when the array is destroyed either via
-g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment
-set to %TRUE or when removing elements.
+g_ptr_array_unref(), when g_ptr_array_free() is called with
+ free_segment set to %TRUE or when removing elements.
Since: 2.30
</description>
<parameters>
<parameter name="reserved_size">
-<parameter_description> number of pointers preallocated.
+<parameter_description> number of pointers preallocated
</parameter_description>
</parameter>
<parameter name="element_free_func">
-<parameter_description> A function to free elements with destroy @array or %NULL.
+<parameter_description> A function to free elements with
+destroy @array or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A new #GPtrArray.
+<return> A new #GPtrArray
</return>
</function>
<function name="g_ptr_array_new_with_free_func">
<description>
-Creates a new #GPtrArray with a reference count of 1 and use @element_free_func
-for freeing each element when the array is destroyed either via
-g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment
-set to %TRUE or when removing elements.
+Creates a new #GPtrArray with a reference count of 1 and use
+ element_free_func for freeing each element when the array is destroyed
+either via g_ptr_array_unref(), when g_ptr_array_free() is called with
+ free_segment set to %TRUE or when removing elements.
Since: 2.22
</description>
<parameters>
<parameter name="element_free_func">
-<parameter_description> A function to free elements with destroy @array or %NULL.
+<parameter_description> A function to free elements with
+destroy @array or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> A new #GPtrArray.
+<return> A new #GPtrArray
</return>
</function>
@@ -31942,16 +31705,16 @@ pointer was not found.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the pointer to remove.
+<parameter_description> the pointer to remove
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the pointer is removed. %FALSE if the pointer is
-not found in the array.
+<return> %TRUE if the pointer is removed, %FALSE if the pointer
+is not found in the array
</return>
</function>
@@ -31959,8 +31722,8 @@ not found in the array.
<description>
Removes the first occurrence of the given pointer from the pointer
array. The last element in the array is used to fill in the space,
-so this function does not preserve the order of the array. But it is
-faster than g_ptr_array_remove(). If @array has a non-%NULL
+so this function does not preserve the order of the array. But it
+is faster than g_ptr_array_remove(). If @array has a non-%NULL
#GDestroyNotify function it is called for the removed element.
It returns %TRUE if the pointer was removed, or %FALSE if the
@@ -31970,71 +31733,71 @@ pointer was not found.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the pointer to remove.
+<parameter_description> the pointer to remove
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the pointer was found in the array.
+<return> %TRUE if the pointer was found in the array
</return>
</function>
<function name="g_ptr_array_remove_index">
<description>
-Removes the pointer at the given index from the pointer array. The
-following elements are moved down one place. If @array has a
-non-%NULL #GDestroyNotify function it is called for the removed
+Removes the pointer at the given index from the pointer array.
+The following elements are moved down one place. If @array has
+a non-%NULL #GDestroyNotify function it is called for the removed
element.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the pointer to remove.
+<parameter_description> the index of the pointer to remove
</parameter_description>
</parameter>
</parameters>
-<return> the pointer which was removed.
+<return> the pointer which was removed
</return>
</function>
<function name="g_ptr_array_remove_index_fast">
<description>
-Removes the pointer at the given index from the pointer array. The
-last element in the array is used to fill in the space, so this
-function does not preserve the order of the array. But it is faster
-than g_ptr_array_remove_index(). If @array has a non-%NULL
+Removes the pointer at the given index from the pointer array.
+The last element in the array is used to fill in the space, so
+this function does not preserve the order of the array. But it
+is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
#GDestroyNotify function it is called for the removed element.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="index_">
-<parameter_description> the index of the pointer to remove.
+<parameter_description> the index of the pointer to remove
</parameter_description>
</parameter>
</parameters>
-<return> the pointer which was removed.
+<return> the pointer which was removed
</return>
</function>
<function name="g_ptr_array_remove_range">
<description>
Removes the given number of pointers starting at the given index
-from a #GPtrArray. The following elements are moved to close the
-gap. If @array has a non-%NULL #GDestroyNotify function it is called
-for the removed elements.
+from a #GPtrArray. The following elements are moved to close the
+gap. If @array has a non-%NULL #GDestroyNotify function it is
+called for the removed elements.
Since: 2.4
@@ -32069,11 +31832,12 @@ Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GPtrArray.
+<parameter_description> A #GPtrArray
</parameter_description>
</parameter>
<parameter name="element_free_func">
-<parameter_description> A function to free elements with destroy @array or %NULL.
+<parameter_description> A function to free elements with
+destroy @array or %NULL
</parameter_description>
</parameter>
</parameters>
@@ -32090,11 +31854,11 @@ called for the removed elements.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="length">
-<parameter_description> the new length of the pointer array.
+<parameter_description> the new length of the pointer array
</parameter_description>
</parameter>
</parameters>
@@ -32112,11 +31876,11 @@ the size of the array is still 0.
</description>
<parameters>
<parameter name="reserved_size">
-<parameter_description> number of pointers preallocated.
+<parameter_description> number of pointers preallocated
</parameter_description>
</parameter>
</parameters>
-<return> the new #GPtrArray.
+<return> the new #GPtrArray
</return>
</function>
@@ -32127,20 +31891,20 @@ comparison function (returns less than zero for first arg is less
than second arg, zero for equal, greater than zero if irst arg is
greater than second arg).
-<note><para>The comparison function for g_ptr_array_sort() doesn't
+Note that the comparison function for g_ptr_array_sort() doesn't
take the pointers from the array as arguments, it takes pointers to
-the pointers in the array.</para></note>
+the pointers in the array.
This is guaranteed to be a stable sort since version 2.32.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="compare_func">
-<parameter_description> comparison function.
+<parameter_description> comparison function
</parameter_description>
</parameter>
</parameters>
@@ -32152,24 +31916,24 @@ This is guaranteed to be a stable sort since version 2.32.
Like g_ptr_array_sort(), but the comparison function has an extra
user data argument.
-<note><para>The comparison function for g_ptr_array_sort_with_data()
+Note that the comparison function for g_ptr_array_sort_with_data()
doesn't take the pointers from the array as arguments, it takes
-pointers to the pointers in the array.</para></note>
+pointers to the pointers in the array.
This is guaranteed to be a stable sort since version 2.32.
</description>
<parameters>
<parameter name="array">
-<parameter_description> a #GPtrArray.
+<parameter_description> a #GPtrArray
</parameter_description>
</parameter>
<parameter name="compare_func">
-<parameter_description> comparison function.
+<parameter_description> comparison function
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> data to pass to @compare_func.
+<parameter_description> data to pass to @compare_func
</parameter_description>
</parameter>
</parameters>
@@ -32188,7 +31952,7 @@ Since: 2.22
</description>
<parameters>
<parameter name="array">
-<parameter_description> A #GPtrArray.
+<parameter_description> A #GPtrArray
</parameter_description>
</parameter>
</parameters>
@@ -32237,8 +32001,8 @@ is created, linked to the given string.
Note that this function is identical to g_quark_from_string() except
that if a new #GQuark is created the string itself is used rather
than a copy. This saves memory, but can only be used if the string
-will <emphasis>always</emphasis> exist. It can be used with
-statically allocated strings in the main program, but not with
+will continue to exist until the program terminates. It can be used
+with statically allocated strings in the main program, but not with
statically allocated memory in dynamically loaded modules, if you
expect to ever unload the module again (e.g. do not use this
function in GTK+ theme engines).
@@ -32247,12 +32011,11 @@ function in GTK+ theme engines).
</description>
<parameters>
<parameter name="string">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
-<return> the #GQuark identifying the string, or 0 if @string is
-%NULL.
+<return> the #GQuark identifying the string, or 0 if @string is %NULL
</return>
</function>
@@ -32266,12 +32029,11 @@ using a copy of the string.
</description>
<parameters>
<parameter name="string">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
-<return> the #GQuark identifying the string, or 0 if @string is
-%NULL.
+<return> the #GQuark identifying the string, or 0 if @string is %NULL
</return>
</function>
@@ -32299,15 +32061,16 @@ Gets the #GQuark associated with the given string, or 0 if string is
If you want the GQuark to be created if it doesn't already exist,
use g_quark_from_string() or g_quark_from_static_string().
+
</description>
<parameters>
<parameter name="string">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
<return> the #GQuark associated with the string, or 0 if @string is
-%NULL or there is no #GQuark associated with it.
+%NULL or there is no #GQuark associated with it
</return>
</function>
@@ -32343,7 +32106,7 @@ Since: 2.4
</parameter_description>
</parameter>
</parameters>
-<return> A copy of @queue
+<return> a copy of @queue
</return>
</function>
@@ -32363,7 +32126,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="link_">
-<parameter_description> a #GList link that <emphasis>must</emphasis> be part of @queue
+<parameter_description> a #GList link that must be part of @queue
</parameter_description>
</parameter>
</parameters>
@@ -32387,7 +32150,7 @@ Since: 2.4
</parameter_description>
</parameter>
</parameters>
-<return> The first link in @queue which contains @data.
+<return> the first link in @queue which contains @data
</return>
</function>
@@ -32418,7 +32181,7 @@ when the desired element is found
</parameter_description>
</parameter>
</parameters>
-<return> The found link, or %NULL if it wasn't found
+<return> the found link, or %NULL if it wasn't found
</return>
</function>
@@ -32450,20 +32213,17 @@ Since: 2.4
<function name="g_queue_free">
<description>
-Frees the memory allocated for the #GQueue. Only call this function if
- queue was created with g_queue_new(). If queue elements contain
+Frees the memory allocated for the #GQueue. Only call this function
+if @queue was created with g_queue_new(). If queue elements contain
dynamically-allocated memory, they should be freed first.
-<note><para>
-If queue elements contain dynamically-allocated memory,
-you should either use g_queue_free_full() or free them manually
-first.
-</para></note>
+If queue elements contain dynamically-allocated memory, you should
+either use g_queue_free_full() or free them manually first.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
@@ -32472,8 +32232,8 @@ first.
<function name="g_queue_free_full">
<description>
-Convenience method, which frees all the memory used by a #GQueue, and
-calls the specified destroy function on every element's data.
+Convenience method, which frees all the memory used by a #GQueue,
+and calls the specified destroy function on every element's data.
Since: 2.32
@@ -32504,7 +32264,7 @@ Since: 2.4
</parameter_description>
</parameter>
</parameters>
-<return> The number of items in @queue.
+<return> the number of items in @queue
</return>
</function>
@@ -32522,11 +32282,12 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the data to find.
+<parameter_description> the data to find
</parameter_description>
</parameter>
</parameters>
-<return> The position of the first element in @queue which contains @data, or -1 if no element in @queue
contains @data.
+<return> the position of the first element in @queue which
+contains @data, or -1 if no element in @queue contains @data
</return>
</function>
@@ -32565,7 +32326,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="sibling">
-<parameter_description> a #GList link that <emphasis>must</emphasis> be part of @queue
+<parameter_description> a #GList link that must be part of @queue
</parameter_description>
</parameter>
<parameter name="data">
@@ -32591,7 +32352,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="sibling">
-<parameter_description> a #GList link that <emphasis>must</emphasis> be part of @queue
+<parameter_description> a #GList link that must be part of @queue
</parameter_description>
</parameter>
<parameter name="data">
@@ -32627,7 +32388,7 @@ element comes before the first.
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> user data passed to @func.
+<parameter_description> user data passed to @func
</parameter_description>
</parameter>
</parameters>
@@ -32646,7 +32407,7 @@ Returns %TRUE if the queue is empty.
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the queue is empty.
+<return> %TRUE if the queue is empty
</return>
</function>
@@ -32663,11 +32424,11 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="link_">
-<parameter_description> A #GList link
+<parameter_description> a #GList link
</parameter_description>
</parameter>
</parameters>
-<return> The position of @link_, or -1 if the link is
+<return> the position of @link_, or -1 if the link is
not part of @queue
</return>
@@ -32681,7 +32442,7 @@ Creates a new #GQueue.
</description>
<parameters>
</parameters>
-<return> a new #GQueue.
+<return> a newly allocated #GQueue
</return>
</function>
@@ -32693,18 +32454,18 @@ Returns the first element of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
-<return> the data of the first element in the queue, or %NULL if the queue
-is empty.
+<return> the data of the first element in the queue, or %NULL
+if the queue is empty
</return>
</function>
<function name="g_queue_peek_head_link">
<description>
-Returns the first link in @queue
+Returns the first link in @queue.
Since: 2.4
@@ -32733,12 +32494,12 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="n">
-<parameter_description> the position of the element.
+<parameter_description> the position of the element
</parameter_description>
</parameter>
</parameters>
-<return> The data for the @n'th element of @queue, or %NULL if @n is
-off the end of @queue.
+<return> the data for the @n'th element of @queue,
+or %NULL if @n is off the end of @queue
</return>
</function>
@@ -32760,8 +32521,8 @@ Since: 2.4
</parameter_description>
</parameter>
</parameters>
-<return> The link at the @n'th position, or %NULL if @n is off the
-end of the list
+<return> the link at the @n'th position, or %NULL
+if @n is off the end of the list
</return>
</function>
@@ -32774,18 +32535,18 @@ Returns the last element of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
-<return> the data of the last element in the queue, or %NULL if the queue
-is empty.
+<return> the data of the last element in the queue, or %NULL
+if the queue is empty
</return>
</function>
<function name="g_queue_peek_tail_link">
<description>
-Returns the last link @queue.
+Returns the last link in @queue.
Since: 2.4
@@ -32803,41 +32564,41 @@ Since: 2.4
<function name="g_queue_pop_head">
<description>
-Removes the first element of the queue.
+Removes the first element of the queue and returns its data.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
-<return> the data of the first element in the queue, or %NULL if the queue
-is empty.
+<return> the data of the first element in the queue, or %NULL
+if the queue is empty
</return>
</function>
<function name="g_queue_pop_head_link">
<description>
-Removes the first element of the queue.
+Removes and returns the first element of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
-<return> the #GList element at the head of the queue, or %NULL if the queue
-is empty.
+<return> the #GList element at the head of the queue, or %NULL
+if the queue is empty
</return>
</function>
<function name="g_queue_pop_nth">
<description>
-Removes the @n'th element of @queue.
+Removes the @n'th element of @queue and returns its data.
Since: 2.4
@@ -32848,11 +32609,11 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="n">
-<parameter_description> the position of the element.
+<parameter_description> the position of the element
</parameter_description>
</parameter>
</parameters>
-<return> the element's data, or %NULL if @n is off the end of @queue.
+<return> the element's data, or %NULL if @n is off the end of @queue
</return>
</function>
@@ -32874,42 +32635,42 @@ Since: 2.4
</parameter_description>
</parameter>
</parameters>
-<return> The @n'th link, or %NULL if @n is off the end of @queue.
+<return> the @n'th link, or %NULL if @n is off the end of @queue
</return>
</function>
<function name="g_queue_pop_tail">
<description>
-Removes the last element of the queue.
+Removes the last element of the queue and returns its data.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
-<return> the data of the last element in the queue, or %NULL if the queue
-is empty.
+<return> the data of the last element in the queue, or %NULL
+if the queue is empty
</return>
</function>
<function name="g_queue_pop_tail_link">
<description>
-Removes the last element of the queue.
+Removes and returns the last element of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
</parameters>
-<return> the #GList element at the tail of the queue, or %NULL if the queue
-is empty.
+<return> the #GList element at the tail of the queue, or %NULL
+if the queue is empty
</return>
</function>
@@ -32938,12 +32699,11 @@ Adds a new element at the head of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="link_">
-<parameter_description> a single #GList element, <emphasis>not</emphasis> a list with
-more than one element.
+<parameter_description> a single #GList element, not a list with more than one element
</parameter_description>
</parameter>
</parameters>
@@ -32952,7 +32712,7 @@ more than one element.
<function name="g_queue_push_nth">
<description>
-Inserts a new element into @queue at the given position
+Inserts a new element into @queue at the given position.
Since: 2.4
@@ -33009,11 +32769,11 @@ Adds a new element at the tail of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> the data for the new element.
+<parameter_description> the data for the new element
</parameter_description>
</parameter>
</parameters>
@@ -33027,12 +32787,11 @@ Adds a new element at the tail of the queue.
</description>
<parameters>
<parameter name="queue">
-<parameter_description> a #GQueue.
+<parameter_description> a #GQueue
</parameter_description>
</parameter>
<parameter name="link_">
-<parameter_description> a single #GList element, <emphasis>not</emphasis> a list with
-more than one element.
+<parameter_description> a single #GList element, not a list with more than one element
</parameter_description>
</parameter>
</parameters>
@@ -33052,7 +32811,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> data to remove.
+<parameter_description> the data to remove
</parameter_description>
</parameter>
</parameters>
@@ -33074,7 +32833,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="data">
-<parameter_description> data to remove
+<parameter_description> the data to remove
</parameter_description>
</parameter>
</parameters>
@@ -33128,10 +32887,10 @@ a positive value if the second comes before the first.
<function name="g_queue_unlink">
<description>
-Unlinks @link_ so that it will no longer be part of @queue. The link is
-not freed.
+Unlinks @link_ so that it will no longer be part of @queue.
+The link is not freed.
- link_ must be part of @queue,
+ link_ must be part of @queue.
Since: 2.4
@@ -33142,7 +32901,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="link_">
-<parameter_description> a #GList link that <emphasis>must</emphasis> be part of @queue
+<parameter_description> a #GList link that must be part of @queue
</parameter_description>
</parameter>
</parameters>
@@ -33151,18 +32910,18 @@ Since: 2.4
<function name="g_rand_boolean">
<description>
-Returns a random #gboolean from @rand_. This corresponds to a
-unbiased coin toss.
+Returns a random #gboolean from @rand_.
+This corresponds to a unbiased coin toss.
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
</parameters>
-<return> a random #gboolean.
+<return> a random #gboolean
</return>
</function>
@@ -33177,11 +32936,11 @@ Since: 2.4
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
</parameters>
-<return> the new #GRand.
+<return> the new #GRand
</return>
</function>
@@ -33195,11 +32954,11 @@ the range [0..1).
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
@@ -33212,19 +32971,19 @@ the range [ begin @end).
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
<parameter name="begin">
-<parameter_description> lower closed bound of the interval.
+<parameter_description> lower closed bound of the interval
</parameter_description>
</parameter>
<parameter name="end">
-<parameter_description> upper open bound of the interval.
+<parameter_description> upper open bound of the interval
</parameter_description>
</parameter>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
@@ -33235,7 +32994,7 @@ Frees the memory allocated for the #GRand.
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
</parameters>
@@ -33251,11 +33010,11 @@ the range [0..2^32-1].
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
@@ -33268,34 +33027,35 @@ the range [ begin @end-1].
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
<parameter name="begin">
-<parameter_description> lower closed bound of the interval.
+<parameter_description> lower closed bound of the interval
</parameter_description>
</parameter>
<parameter name="end">
-<parameter_description> upper open bound of the interval.
+<parameter_description> upper open bound of the interval
</parameter_description>
</parameter>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
<function name="g_rand_new">
<description>
Creates a new random number generator initialized with a seed taken
-either from <filename>/dev/urandom</filename> (if existing) or from
-the current time (as a fallback). On Windows, the seed is taken from
-rand_s().
+either from `/dev/urandom` (if existing) or from the current time
+(as a fallback).
+
+On Windows, the seed is taken from rand_s().
</description>
<parameters>
</parameters>
-<return> the new #GRand.
+<return> the new #GRand
</return>
</function>
@@ -33307,11 +33067,11 @@ Creates a new random number generator initialized with @seed.
</description>
<parameters>
<parameter name="seed">
-<parameter_description> a value to initialize the random number generator.
+<parameter_description> a value to initialize the random number generator
</parameter_description>
</parameter>
</parameters>
-<return> the new #GRand.
+<return> the new #GRand
</return>
</function>
@@ -33324,15 +33084,16 @@ Since: 2.4
</description>
<parameters>
<parameter name="seed">
-<parameter_description> an array of seeds to initialize the random number generator.
+<parameter_description> an array of seeds to initialize the random number generator
</parameter_description>
</parameter>
<parameter name="seed_length">
-<parameter_description> an array of seeds to initialize the random number generator.
+<parameter_description> an array of seeds to initialize the random number
+generator
</parameter_description>
</parameter>
</parameters>
-<return> the new #GRand.
+<return> the new #GRand
</return>
</function>
@@ -33344,11 +33105,11 @@ Sets the seed for the random number generator #GRand to @seed.
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
<parameter name="seed">
-<parameter_description> a value to reinitialize the random number generator.
+<parameter_description> a value to reinitialize the random number generator
</parameter_description>
</parameter>
</parameters>
@@ -33357,18 +33118,18 @@ Sets the seed for the random number generator #GRand to @seed.
<function name="g_rand_set_seed_array">
<description>
-Initializes the random number generator by an array of
-longs. Array can be of arbitrary size, though only the
-first 624 values are taken. This function is useful
-if you have many low entropy seeds, or if you require more then
-32bits of actual entropy for your application.
+Initializes the random number generator by an array of longs.
+Array can be of arbitrary size, though only the first 624 values
+are taken. This function is useful if you have many low entropy
+seeds, or if you require more then 32 bits of actual entropy for
+your application.
Since: 2.4
</description>
<parameters>
<parameter name="rand_">
-<parameter_description> a #GRand.
+<parameter_description> a #GRand
</parameter_description>
</parameter>
<parameter name="seed">
@@ -33385,13 +33146,14 @@ Since: 2.4
<function name="g_random_boolean">
<description>
-Returns a random #gboolean. This corresponds to a unbiased coin toss.
+Returns a random #gboolean.
+This corresponds to a unbiased coin toss.
</description>
<parameters>
</parameters>
-<return> a random #gboolean.
+<return> a random #gboolean
</return>
</function>
@@ -33403,27 +33165,28 @@ Returns a random #gdouble equally distributed over the range [0..1).
</description>
<parameters>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
<function name="g_random_double_range">
<description>
-Returns a random #gdouble equally distributed over the range [ begin @end).
+Returns a random #gdouble equally distributed over the range
+[ begin @end).
</description>
<parameters>
<parameter name="begin">
-<parameter_description> lower closed bound of the interval.
+<parameter_description> lower closed bound of the interval
</parameter_description>
</parameter>
<parameter name="end">
-<parameter_description> upper open bound of the interval.
+<parameter_description> upper open bound of the interval
</parameter_description>
</parameter>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
@@ -33436,7 +33199,7 @@ Return a random #guint32 equally distributed over the range
</description>
<parameters>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
@@ -33449,27 +33212,27 @@ Returns a random #gint32 equally distributed over the range
</description>
<parameters>
<parameter name="begin">
-<parameter_description> lower closed bound of the interval.
+<parameter_description> lower closed bound of the interval
</parameter_description>
</parameter>
<parameter name="end">
-<parameter_description> upper open bound of the interval.
+<parameter_description> upper open bound of the interval
</parameter_description>
</parameter>
</parameters>
-<return> A random number.
+<return> a random number
</return>
</function>
<function name="g_random_set_seed">
<description>
Sets the seed for the global random number generator, which is used
-by the <function>g_random_*</function> functions, to @seed.
+by the g_random_* functions, to @seed.
</description>
<parameters>
<parameter name="seed">
-<parameter_description> a value to reinitialize the global random number generator.
+<parameter_description> a value to reinitialize the global random number generator
</parameter_description>
</parameter>
</parameters>
@@ -33560,7 +33323,7 @@ structure.
It is not necessary to initialise a recursive mutex that has been
statically allocated.
-|[
+|[<!-- language="C" -->
typedef struct {
GRecMutex m;
...
@@ -33910,14 +33673,14 @@ i.e. you must free it regardless if regular expression actually matched.
To retrieve all the non-overlapping matches of the pattern in
string you can use g_match_info_next().
-|[
+|[<!-- language="C" -->
static void
print_uppercase_words (const gchar *string)
{
-/ * Print all uppercase-only words. * /
+// Print all uppercase-only words.
GRegex *regex;
GMatchInfo *match_info;
- 
+
regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
g_regex_match (regex, string, 0, &match_info);
while (g_match_info_matches (match_info))
@@ -34018,7 +33781,7 @@ you get "<a> <b> <c>".
This function uses a different algorithm (called DFA, i.e. deterministic
finite automaton), so it can retrieve all the possible matches, all
starting at the same point in the string. For instance matching
-"<a> <b> <c>" against the pattern "<.*>"
+"<a> <b> <c>" against the pattern "<.*>;"
you would obtain three matches: "<a> <b> <c>",
"<a> <b>" and "<a>".
@@ -34109,15 +33872,15 @@ freeing or modifying @string then the behaviour is undefined.
To retrieve all the non-overlapping matches of the pattern in
string you can use g_match_info_next().
-|[
+|[<!-- language="C" -->
static void
print_uppercase_words (const gchar *string)
{
-/ * Print all uppercase-only words. * /
+// Print all uppercase-only words.
GRegex *regex;
GMatchInfo *match_info;
GError *error = NULL;
- 
+
regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
while (g_match_info_matches (match_info))
@@ -34271,38 +34034,18 @@ Replaces all occurrences of the pattern in @regex with the
replacement text. Backreferences of the form '\number' or
'\g<number>' in the replacement text are interpolated by the
number-th captured subexpression of the match, '\g<name>' refers
-to the captured subexpression with the given name. '\0' refers to the
-complete match, but '\0' followed by a number is the octal representation
-of a character. To include a literal '\' in the replacement, write '\\'.
+to the captured subexpression with the given name. '\0' refers
+to the complete match, but '\0' followed by a number is the octal
+representation of a character. To include a literal '\' in the
+replacement, write '\\'.
+
There are also escapes that changes the case of the following text:
-<variablelist>
-<varlistentry><term>\l</term>
-<listitem>
-<para>Convert to lower case the next character</para>
-</listitem>
-</varlistentry>
-<varlistentry><term>\u</term>
-<listitem>
-<para>Convert to upper case the next character</para>
-</listitem>
-</varlistentry>
-<varlistentry><term>\L</term>
-<listitem>
-<para>Convert to lower case till \E</para>
-</listitem>
-</varlistentry>
-<varlistentry><term>\U</term>
-<listitem>
-<para>Convert to upper case till \E</para>
-</listitem>
-</varlistentry>
-<varlistentry><term>\E</term>
-<listitem>
-<para>End case modification</para>
-</listitem>
-</varlistentry>
-</variablelist>
+- \l: Convert to lower case the next character
+- \u: Convert to upper case the next character
+- \L: Convert to lower case till \E
+- \U: Convert to upper case till \E
+- \E: End case modification
If you do not need to use backreferences use g_regex_replace_literal().
@@ -34363,7 +34106,7 @@ that begins with any kind of lookbehind assertion, such as "\b".
The following example uses g_regex_replace_eval() to replace multiple
strings at once:
-|[
+|[<!-- language="C" -->
static gboolean
eval_cb (const GMatchInfo *info,
GString *res,
@@ -34380,7 +34123,7 @@ g_free (match);
return FALSE;
}
-/ * ... * /
+...
GRegex *reg;
GHashTable *h;
@@ -34397,7 +34140,7 @@ reg = g_regex_new ("1|2|3|4", 0, 0, NULL);
res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL);
g_hash_table_destroy (h);
-/ * ... * /
+...
]|
Since: 2.14
@@ -34993,10 +34736,18 @@ Care is taken to avoid overflow when calculating the size of the allocated block
<function name="g_return_if_fail">
<description>
-Verifies that the expression evaluates to %TRUE. If the expression
-evaluates to %FALSE, a critical message is logged and the current
-function returns. This can only be used in functions which do not
-return a value.
+Verifies that the expression @expr, usually representing a precondition,
+evaluates to %TRUE. If the function returns a value, use
+g_return_val_if_fail() instead.
+
+If @expr evaluates to %FALSE, the current function should be considered to
+have undefined behaviour (a programmer error). The only correct solution
+to such an error is to change the module that is calling the current
+function, so that it avoids this incorrect call.
+
+To make this undefined behaviour visible, if @expr evaluates to %FALSE,
+the result is usually that a critical message is logged and the current
+function returns.
If G_DISABLE_CHECKS is defined then the check is not performed. You
should therefore not depend on any side effects of @expr.
@@ -35024,8 +34775,17 @@ This can only be used in functions which do not return a value.
<function name="g_return_val_if_fail">
<description>
-Verifies that the expression evaluates to %TRUE. If the expression
-evaluates to %FALSE, a critical message is logged and @val is
+Verifies that the expression @expr, usually representing a precondition,
+evaluates to %TRUE. If the function does not return a value, use
+g_return_if_fail() instead.
+
+If @expr evaluates to %FALSE, the current function should be considered to
+have undefined behaviour (a programmer error). The only correct solution
+to such an error is to change the module that is calling the current
+function, so that it avoids this incorrect call.
+
+To make this undefined behaviour visible, if @expr evaluates to %FALSE,
+the result is usually that a critical message is logged and @val is
returned from the current function.
If G_DISABLE_CHECKS is defined then the check is not performed. You
@@ -35114,7 +34874,7 @@ allocated on the stack, or as part of a larger structure. It is not
necessary to initialise a reader-writer lock that has been statically
allocated.
-|[
+|[<!-- language="C" -->
typedef struct {
GRWLock l;
...
@@ -35909,8 +35669,8 @@ Since: 2.14
<function name="g_sequence_free">
<description>
Frees the memory allocated for @seq. If @seq has a data destroy
-function associated with it, that function is called on all items in
- seq
+function associated with it, that function is called on all items
+in @seq.
Since: 2.14
@@ -35992,7 +35752,7 @@ Since: 2.14
</parameter_description>
</parameter>
<parameter name="pos">
-<parameter_description> a position in @seq, or -1 for the end.
+<parameter_description> a position in @seq, or -1 for the end
</parameter_description>
</parameter>
</parameters>
@@ -36140,8 +35900,8 @@ Since: 2.14
</parameter_description>
</parameter>
</parameters>
-<return> A negative number if @a comes before @b, 0 if they are
-equal, and a positive number if @a comes after @b.
+<return> a negative number if @a comes before @b, 0 if they are
+equal, and a positive number if @a comes after @b
</return>
</function>
@@ -36177,7 +35937,7 @@ Since: 2.14
</parameter_description>
</parameter>
</parameters>
-<return> the #GSequence that @iter points into.
+<return> the #GSequence that @iter points into
</return>
</function>
@@ -36213,7 +35973,7 @@ Since: 2.14
</parameter_description>
</parameter>
</parameters>
-<return> Whether @iter is the end iterator.
+<return> Whether @iter is the end iterator
</return>
</function>
@@ -36235,19 +35995,19 @@ Since: 2.14
</parameter>
<parameter name="delta">
<parameter_description> A positive or negative number indicating how many positions away
-from @iter the returned #GSequenceIter will be.
+from @iter the returned #GSequenceIter will be
</parameter_description>
</parameter>
</parameters>
-<return> a #GSequenceIter which is @delta positions away from @iter.
+<return> a #GSequenceIter which is @delta positions away from @iter
</return>
</function>
<function name="g_sequence_iter_next">
<description>
-Returns an iterator pointing to the next position after @iter. If
- iter is the end iterator, the end iterator is returned.
+Returns an iterator pointing to the next position after @iter.
+If @iter is the end iterator, the end iterator is returned.
Since: 2.14
@@ -36258,15 +36018,15 @@ Since: 2.14
</parameter_description>
</parameter>
</parameters>
-<return> a #GSequenceIter pointing to the next position after @iter.
+<return> a #GSequenceIter pointing to the next position after @iter
</return>
</function>
<function name="g_sequence_iter_prev">
<description>
-Returns an iterator pointing to the previous position before @iter. If
- iter is the begin iterator, the begin iterator is returned.
+Returns an iterator pointing to the previous position before @iter.
+If @iter is the begin iterator, the begin iterator is returned.
Since: 2.14
@@ -36277,8 +36037,8 @@ Since: 2.14
</parameter_description>
</parameter>
</parameters>
-<return> a #GSequenceIter pointing to the previous position before
- iter
+<return> a #GSequenceIter pointing to the previous position
+before @iter
</return>
</function>
@@ -36296,13 +36056,11 @@ It should return 0 if the items are equal, a negative value if
the first item comes before the second, and a positive value if
the second item comes before the first.
-<note><para>
This function will fail if the data contained in the sequence is
unsorted. Use g_sequence_insert_sorted() or
g_sequence_insert_sorted_iter() to add data to your sequence or, if
you want to add a large amount of data, call g_sequence_sort() after
doing unsorted insertions.
-</para></note>
Since: 2.28
@@ -36321,13 +36079,13 @@ Since: 2.28
</parameter_description>
</parameter>
<parameter name="cmp_data">
-<parameter_description> user data passed to @cmp_func.
+<parameter_description> user data passed to @cmp_func
</parameter_description>
</parameter>
</parameters>
<return> an #GSequenceIter pointing to the position of the
first item found equal to @data according to @cmp_func and
- cmp_data, or %NULL if no such item exists.
+ cmp_data, or %NULL if no such item exists
</return>
</function>
@@ -36342,13 +36100,11 @@ It should return 0 if the iterators are equal, a negative value
if the first iterator comes before the second, and a positive
value if the second iterator comes before the first.
-<note><para>
This function will fail if the data contained in the sequence is
unsorted. Use g_sequence_insert_sorted() or
g_sequence_insert_sorted_iter() to add data to your sequence or, if
you want to add a large amount of data, call g_sequence_sort() after
doing unsorted insertions.
-</para></note>
Since: 2.28
@@ -36373,7 +36129,7 @@ Since: 2.28
</parameters>
<return> an #GSequenceIter pointing to the position of
the first item found equal to @data according to @cmp_func
-and @cmp_data, or %NULL if no such item exists.
+and @cmp_data, or %NULL if no such item exists
</return>
</function>
@@ -36395,7 +36151,7 @@ Since: 2.14
</parameter>
<parameter name="dest">
<parameter_description> a #GSequenceIter pointing to the position to which
-the item is moved.
+the item is moved
</parameter_description>
</parameter>
</parameters>
@@ -36479,10 +36235,10 @@ Since: 2.14
<description>
Finds an iterator somewhere in the range (@begin, @end). This
iterator will be close to the middle of the range, but is not
-guaranteed to be <emphasis>exactly</emphasis> in the middle.
+guaranteed to be exactly in the middle.
-The @begin and @end iterators must both point to the same sequence and
- begin must come before or be equal to @end in the sequence.
+The @begin and @end iterators must both point to the same sequence
+and @begin must come before or be equal to @end in the sequence.
Since: 2.14
@@ -36497,8 +36253,8 @@ Since: 2.14
</parameter_description>
</parameter>
</parameters>
-<return> A #GSequenceIter pointing somewhere in the
-(@begin, @end) range.
+<return> a #GSequenceIter pointing somewhere in the
+(@begin, @end) range
</return>
</function>
@@ -36559,13 +36315,11 @@ the second item comes before the first.
If you are simply searching for an existing element of the sequence,
consider using g_sequence_lookup().
-<note><para>
This function will fail if the data contained in the sequence is
unsorted. Use g_sequence_insert_sorted() or
g_sequence_insert_sorted_iter() to add data to your sequence or, if
you want to add a large amount of data, call g_sequence_sort() after
doing unsorted insertions.
-</para></note>
Since: 2.14
@@ -36584,12 +36338,12 @@ Since: 2.14
</parameter_description>
</parameter>
<parameter name="cmp_data">
-<parameter_description> user data passed to @cmp_func.
+<parameter_description> user data passed to @cmp_func
</parameter_description>
</parameter>
</parameters>
<return> an #GSequenceIter pointing to the position where @data
-would have been inserted according to @cmp_func and @cmp_data.
+would have been inserted according to @cmp_func and @cmp_data
</return>
</function>
@@ -36607,13 +36361,11 @@ value if the second iterator comes before the first.
If you are simply searching for an existing element of the sequence,
consider using g_sequence_lookup_iter().
-<note><para>
This function will fail if the data contained in the sequence is
unsorted. Use g_sequence_insert_sorted() or
g_sequence_insert_sorted_iter() to add data to your sequence or, if
you want to add a large amount of data, call g_sequence_sort() after
doing unsorted insertions.
-</para></note>
Since: 2.14
@@ -36638,7 +36390,7 @@ Since: 2.14
</parameters>
<return> a #GSequenceIter pointing to the position in @seq
where @data would have been inserted according to @iter_cmp
-and @cmp_data.
+and @cmp_data
</return>
</function>
@@ -36899,9 +36651,10 @@ Since: 2.18
<function name="g_set_prgname">
<description>
-Sets the name of the program. This name should <emphasis>not</emphasis>
-be localized, contrast with g_set_application_name(). Note that for
-thread-safety reasons this function can only be called once.
+Sets the name of the program. This name should not be localized,
+in contrast to g_set_application_name().
+
+Note that for thread-safety reasons this function can only be called once.
</description>
<parameters>
@@ -36967,20 +36720,18 @@ UTF-8.
Note that on some systems, when variables are overwritten, the memory
used for the previous variables and its value isn't reclaimed.
-<warning><para>
-Environment variable handling in UNIX is not thread-safe, and your
-program may crash if one thread calls g_setenv() while another
-thread is calling getenv(). (And note that many functions, such as
-gettext(), call getenv() internally.) This function is only safe to
-use at the very start of your program, before creating any other
-threads (or creating objects that create worker threads of their
-own).
-</para><para>
+You should be mindful fo the fact that environment variable handling
+in UNIX is not thread-safe, and your program may crash if one thread
+calls g_setenv() while another thread is calling getenv(). (And note
+that many functions, such as gettext(), call getenv() internally.)
+This function is only safe to use at the very start of your program,
+before creating any other threads (or creating objects that create
+worker threads of their own).
+
If you need to set up the environment for a child process, you can
use g_get_environ() to get an environment array, modify that with
g_environ_setenv() and g_environ_unsetenv(), and then pass that
array directly to execvpe(), g_spawn_async(), or the like.
-</para></warning>
Since: 2.4
@@ -37147,8 +36898,8 @@ boolean values. The behavior that this accumulator gives is
that a return of %TRUE stops the signal emission: no further
callbacks will be invoked, while a return of %FALSE allows
the emission to continue. The idea here is that a %TRUE return
-indicates that the callback <emphasis>handled</emphasis> the signal,
-and no further handling is needed.
+indicates that the callback handled the signal, and no further
+handling is needed.
Since: 2.4
@@ -37385,8 +37136,8 @@ default handler of the signal.
Connects a #GCallback function to a signal for a particular object. Similar
to g_signal_connect(), but allows to provide a #GClosureNotify for the data
which will be called when the signal handler is disconnected and no longer
-used. Specify @connect_flags if you need <literal>..._after()</literal> or
-<literal>..._swapped()</literal> variants of this function.
+used. Specify @connect_flags if you need `..._after()` or
+`..._swapped()` variants of this function.
</description>
@@ -38133,9 +37884,8 @@ When registering a signal and looking up a signal, either separator can
be used, but they cannot be mixed.
If 0 is used for @class_offset subclasses cannot override the class handler
-in their <code>class_init</code> method by doing
-<code>super_class->signal_handler = my_signal_handler</code>. Instead they
-will have to use g_signal_override_class_handler().
+in their class_init method by doing super_class->signal_handler = my_signal_handler.
+Instead they will have to use g_signal_override_class_handler().
If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
the marshaller for this signal.
@@ -38611,12 +38361,12 @@ structure which is to be invoked by the new closure
<description>
Allocates a block of memory from the slice allocator.
The block adress handed out can be expected to be aligned
-to at least <literal>1 * sizeof (void*)</literal>,
+to at least 1 * sizeof (void*),
though in general slices are 2 * sizeof (void*) bytes aligned,
if a malloc() fallback implementation is used instead,
the alignment may be reduced in a libc dependent fashion.
Note that the underlying slice allocation mechanism can
-be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+be changed with the [`G_SLICE=always-malloc`][G_SLICE]
environment variable.
Since: 2.10
@@ -38637,8 +38387,7 @@ Since: 2.10
<description>
Allocates a block of memory via g_slice_alloc() and initializes
the returned memory to 0. Note that the underlying slice allocation
-mechanism can be changed with the
-<link linkend="G_SLICE">G_SLICE=always-malloc</link>
+mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
environment variable.
Since: 2.10
@@ -38683,11 +38432,11 @@ Since: 2.14
A convenience macro to duplicate a block of memory using
the slice allocator.
-It calls g_slice_copy() with <literal>sizeof (@type)</literal>
+It calls g_slice_copy() with `sizeof (@type)`
and casts the returned pointer to a pointer of the given type,
avoiding a type cast in the source code.
Note that the underlying slice allocation mechanism can
-be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+be changed with the [`G_SLICE=always-malloc`][G_SLICE]
environment variable.
Since: 2.14
@@ -38713,12 +38462,11 @@ Since: 2.14
A convenience macro to free a block of memory that has
been allocated from the slice allocator.
-It calls g_slice_free1() using <literal>sizeof (type)</literal>
+It calls g_slice_free1() using `sizeof (type)`
as the block size.
Note that the exact release behaviour can be changed with the
-<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
-variable, also see <link linkend="G_SLICE">G_SLICE</link> for
-related debugging options.
+[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
+[`G_SLICE`][G_SLICE] for related debugging options.
Since: 2.10
@@ -38743,10 +38491,8 @@ Frees a block of memory.
The memory must have been allocated via g_slice_alloc() or
g_slice_alloc0() and the @block_size has to match the size
specified upon allocation. Note that the exact release behaviour
-can be changed with the
-<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
-variable, also see <link linkend="G_SLICE">G_SLICE</link> for
-related debugging options.
+can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment
+variable, also see [`G_SLICE`][G_SLICE] for related debugging options.
Since: 2.10
@@ -38772,9 +38518,8 @@ g_slice_alloc() or g_slice_alloc0() and linked together by
a @next pointer (similar to #GSList). The name of the
@next field in @type is passed as third argument.
Note that the exact release behaviour can be changed with the
-<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
-variable, also see <link linkend="G_SLICE">G_SLICE</link> for
-related debugging options.
+[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
+[`G_SLICE`][G_SLICE] for related debugging options.
Since: 2.10
@@ -38805,9 +38550,8 @@ g_slice_alloc() or g_slice_alloc0() and linked together by a
@next pointer (similar to #GSList). The offset of the @next
field in each block is passed as third argument.
Note that the exact release behaviour can be changed with the
-<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
-variable, also see <link linkend="G_SLICE">G_SLICE</link> for
-related debugging options.
+[`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
+[`G_SLICE`][G_SLICE] for related debugging options.
Since: 2.10
@@ -38834,11 +38578,10 @@ Since: 2.10
A convenience macro to allocate a block of memory from the
slice allocator.
-It calls g_slice_alloc() with <literal>sizeof (@type)</literal>
-and casts the returned pointer to a pointer of the given type,
-avoiding a type cast in the source code.
-Note that the underlying slice allocation mechanism can
-be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+It calls g_slice_alloc() with `sizeof (@type)` and casts the
+returned pointer to a pointer of the given type, avoiding a type
+cast in the source code. Note that the underlying slice allocation
+mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
environment variable.
Since: 2.10
@@ -38860,11 +38603,11 @@ Since: 2.10
A convenience macro to allocate a block of memory from the
slice allocator and set the memory to 0.
-It calls g_slice_alloc0() with <literal>sizeof (@type)</literal>
+It calls g_slice_alloc0() with `sizeof (@type)`
and casts the returned pointer to a pointer of the given type,
avoiding a type cast in the source code.
Note that the underlying slice allocation mechanism can
-be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+be changed with the [`G_SLICE=always-malloc`][G_SLICE]
environment variable.
Since: 2.10
@@ -38897,27 +38640,23 @@ g_slist_insert_sorted() functions and so is rarely used on its own.
<description>
Adds a new element on to the end of the list.
-<note><para>
The return value is the new start of the list, which may
have changed, so make sure you store the new value.
-</para></note>
-<note><para>
Note that g_slist_append() has to traverse the entire list
to find the end, which is inefficient when adding multiple
elements. A common idiom to avoid the inefficiency is to prepend
the elements and reverse the list when all elements have been added.
-</para></note>
-|[
-/ * Notice that these are initialized to the empty list. * /
+|[<!-- language="C" -->
+// Notice that these are initialized to the empty list.
GSList *list = NULL, *number_list = NULL;
-/ * This is a list of strings. * /
+// This is a list of strings.
list = g_slist_append (list, "first");
list = g_slist_append (list, "second");
-/ * This is a list of integers. * /
+// This is a list of integers.
number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
]|
@@ -38964,12 +38703,10 @@ They are used directly.
<description>
Copies a #GSList.
-<note><para>
Note that this is a "shallow" copy. If the list elements
consist of pointers to data, the pointers are copied but
the actual data isn't. See g_slist_copy_deep() if you need
to copy the data as well.
-</para></note>
</description>
@@ -38995,12 +38732,12 @@ pointer. It's safe to pass #NULL as user_data, if the copy function takes only
one argument.
For instance, if @list holds a list of GObjects, you can do:
-|[
+|[<!-- language="C" -->
another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
]|
And, to entirely free the new list, you could do:
-|[
+|[<!-- language="C" -->
g_slist_free_full (another_list, g_object_unref);
]|
@@ -39032,11 +38769,11 @@ Removes the node link_ from the list and frees it.
Compare this to g_slist_remove_link() which removes the node
without freeing it.
-<note>Removing arbitrary nodes from a singly-linked list
-requires time that is proportional to the length of the list
-(ie. O(n)). If you find yourself using g_slist_delete_link()
-frequently, you should consider a different data structure, such
-as the doubly-linked #GList.</note>
+Removing arbitrary nodes from a singly-linked list requires time
+that is proportional to the length of the list (ie. O(n)). If you
+find yourself using g_slist_delete_link() frequently, you should
+consider a different data structure, such as the doubly-linked
+#GList.
</description>
@@ -39133,11 +38870,9 @@ Calls a function for each element of a #GSList.
Frees all of the memory used by a #GSList.
The freed elements are returned to the slice allocator.
-<note><para>
If list elements contain dynamically-allocated memory,
you should either use g_slist_free_full() or free them manually
first.
-</para></note>
</description>
<parameters>
@@ -39334,9 +39069,7 @@ comes after the second parameter in the sort order.
<description>
Gets the last element in a #GSList.
-<note><para>
This function iterates over the whole list.
-</para></note>
</description>
@@ -39355,10 +39088,8 @@ or %NULL if the #GSList has no elements
<description>
Gets the number of elements in a #GSList.
-<note><para>
This function iterates over the whole list to
count its elements.
-</para></note>
</description>
@@ -39456,13 +39187,11 @@ or -1 if the element is not found
<description>
Adds a new element on to the start of the list.
-<note><para>
The return value is the new start of the list, which
may have changed, so make sure you store the new value.
-</para></note>
-|[
-/ * Notice that it is initialized to the empty list. * /
+|[<!-- language="C" -->
+// Notice that it is initialized to the empty list.
GSList *list = NULL;
list = g_slist_prepend (list, "last");
list = g_slist_prepend (list, "first");
@@ -39536,11 +39265,11 @@ freeing the element. The removed element's next
link is set to %NULL, so that it becomes a
self-contained list with one element.
-<note>Removing arbitrary nodes from a singly-linked list
+Removing arbitrary nodes from a singly-linked list
requires time that is proportional to the length of the list
(ie. O(n)). If you find yourself using g_slist_remove_link()
-frequently, you should consider a different data structure, such
-as the doubly-linked #GList.</note>
+frequently, you should consider a different data structure,
+such as the doubly-linked #GList.
</description>
@@ -39656,7 +39385,7 @@ terminating nul character).
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="Varargs">
@@ -39686,6 +39415,9 @@ callback that does nothing (except return %TRUE if appropriate).
@source will hold a reference on @child_source while @child_source
is attached to it.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
Since: 2.28
</description>
@@ -39710,6 +39442,9 @@ event source. The event source's check function will typically test
the @revents field in the #GPollFD struct and return %TRUE if events need
to be processed.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
Using this API forces the linear scanning of event sources on each
main loop iteration. Newly-written event sources should try to use
g_source_add_unix_fd() instead of this API.
@@ -39740,6 +39475,9 @@ g_source_modify_unix_fd().
It is not necessary to remove the fd before destroying the source; it
will be cleaned up automatically.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
As the name suggests, this function is not available on Windows.
Since: 2.36
@@ -39790,7 +39528,8 @@ that context. Remove it by calling g_source_destroy().
<description>
Removes a source from its #GMainContext, if any, and mark it as
destroyed. The source cannot be subsequently added to another
-context.
+context. It is safe to call this on sources which have already been
+removed from their context.
</description>
<parameters>
@@ -39971,16 +39710,16 @@ This is important when you operate upon your objects
from within idle handlers, but may have freed the object
before the dispatch of your idle handler.
-|[
+|[<!-- language="C" -->
static gboolean
idle_callback (gpointer data)
{
SomeWidget *self = data;
-GDK_THREADS_ENTER (<!-- -->);
-/<!-- -->* do stuff with self *<!-- -->/
+GDK_THREADS_ENTER ();
+// do stuff with self
self->idle_id = 0;
-GDK_THREADS_LEAVE (<!-- -->);
+GDK_THREADS_LEAVE ();
return G_SOURCE_REMOVE;
}
@@ -40009,7 +39748,7 @@ to the use after free in the callback. A solution, to
this particular problem, is to check to if the source
has already been destroy within the callback.
-|[
+|[<!-- language="C" -->
static gboolean
idle_callback (gpointer data)
{
@@ -40018,7 +39757,7 @@ SomeWidget *self = data;
GDK_THREADS_ENTER ();
if (!g_source_is_destroyed (g_main_current_source ()))
{
-/<!-- -->* do stuff with self *<!-- -->/
+// do stuff with self
}
GDK_THREADS_LEAVE ();
@@ -40049,6 +39788,9 @@ Updates the event mask to watch for the fd identified by @tag.
If you want to remove a fd, don't set its event mask to zero.
Instead, call g_source_remove_unix_fd().
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
As the name suggests, this function is not available on Windows.
Since: 2.36
@@ -40076,7 +39818,7 @@ Since: 2.36
Creates a new #GSource structure. The size is specified to
allow creating structures derived from #GSource that contain
additional data. The size passed in must be at least
-<literal>sizeof (GSource)</literal>.
+`sizeof (GSource)`.
The source will not initially be associated with any #GMainContext
and must be added to one with g_source_attach() before it will be
@@ -40107,6 +39849,9 @@ Queries the events reported for the fd corresponding to @tag on
The return value of this function is only defined when the function
is called from the check or dispatch functions for @source.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
As the name suggests, this function is not available on Windows.
Since: 2.36
@@ -40214,6 +39959,9 @@ data, only one will be destroyed.
<description>
Detaches @child_source from @source and destroys it.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
Since: 2.28
</description>
@@ -40236,6 +39984,9 @@ g_source_add_child_source().
Removes a file descriptor from the set of file descriptors polled for
this source.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
</description>
<parameters>
<parameter name="source">
@@ -40258,6 +40009,9 @@ You only need to call this if you want to remove an fd from being
watched while keeping the same source around. In the normal case you
will just want to destroy the source.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
As the name suggests, this function is not available on Windows.
Since: 2.36
@@ -40485,6 +40239,10 @@ source will be dispatched if it is ready to be dispatched and no
sources at a higher (numerically smaller) priority are ready to be
dispatched.
+A child source always has the same priority as its parent. It is not
+permitted to change the priority of a source once it has been added
+as a child of another source.
+
</description>
<parameters>
<parameter name="source">
@@ -40518,6 +40276,9 @@ other suggests that it would be delivered first, and the ready time
for both sources is reached during the same main context iteration
then the order of dispatch is undefined.
+This API is only intended to be used by implementations of #GSource.
+Do not call this API on a #GSource that you did not create.
+
Since: 2.36
</description>
@@ -40581,17 +40342,14 @@ simply calls the g_spawn_async_with_pipes() without any pipes.
You should call g_spawn_close_pid() on the returned child process
reference when you don't need it any more.
-<note><para>
-If you are writing a GTK+ application, and the program you
-are spawning is a graphical application, too, then you may
-want to use gdk_spawn_on_screen() instead to ensure that
-the spawned program opens its windows on the right screen.
-</para></note>
+If you are writing a GTK+ application, and the program you are
+spawning is a graphical application, too, then you may want to
+use gdk_spawn_on_screen() instead to ensure that the spawned program
+opens its windows on the right screen.
-<note><para> Note that the returned @child_pid on Windows is a
-handle to the child process and not its identifier. Process handles
-and process identifiers are different concepts on Windows.
-</para></note>
+Note that the returned @child_pid on Windows is a handle to the child
+process and not its identifier. Process handles and process identifiers
+are different concepts on Windows.
</description>
@@ -40637,18 +40395,18 @@ and process identifiers are different concepts on Windows.
<description>
Executes a child program asynchronously (your program will not
block waiting for the child to exit). The child program is
-specified by the only argument that must be provided, @argv. @argv
-should be a %NULL-terminated array of strings, to be passed as the
-argument vector for the child. The first string in @argv is of
-course the name of the program to execute. By default, the name of
-the program must be a full path. If @flags contains the
-%G_SPAWN_SEARCH_PATH flag, the <envar>PATH</envar> environment variable
-is used to search for the executable. If @flags contains the
-%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the <envar>PATH</envar> variable from
- envp is used to search for the executable.
-If both the %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
-flags are set, the <envar>PATH</envar> variable from @envp takes precedence
-over the environment variable.
+specified by the only argument that must be provided, @argv.
+ argv should be a %NULL-terminated array of strings, to be passed
+as the argument vector for the child. The first string in @argv
+is of course the name of the program to execute. By default, the
+name of the program must be a full path. If @flags contains the
+%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
+used to search for the executable. If @flags contains the
+%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
+ envp is used to search for the executable. If both the
+%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
+are set, the `PATH` variable from @envp takes precedence over
+the environment variable.
If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
used, then the program will be run from the current directory (or
@@ -40673,21 +40431,19 @@ for that function. Alternatively, you can retrieve the Win32 system
level wide character command line passed to the spawned program
using the GetCommandLineW() function.
-On Windows the low-level child process creation API
-<function>CreateProcess()</function> doesn't use argument vectors,
-but a command line. The C runtime library's
-<function>spawn*()</function> family of functions (which
-g_spawn_async_with_pipes() eventually calls) paste the argument
-vector elements together into a command line, and the C runtime startup code
-does a corresponding reconstruction of an argument vector from the
-command line, to be passed to main(). Complications arise when you have
-argument vector elements that contain spaces of double quotes. The
-<function>spawn*()</function> functions don't do any quoting or
-escaping, but on the other hand the startup code does do unquoting
-and unescaping in order to enable receiving arguments with embedded
-spaces or double quotes. To work around this asymmetry,
-g_spawn_async_with_pipes() will do quoting and escaping on argument
-vector elements that need it before calling the C runtime
+On Windows the low-level child process creation API CreateProcess()
+doesn't use argument vectors, but a command line. The C runtime
+library's spawn*() family of functions (which g_spawn_async_with_pipes()
+eventually calls) paste the argument vector elements together into
+a command line, and the C runtime startup code does a corresponding
+reconstruction of an argument vector from the command line, to be
+passed to main(). Complications arise when you have argument vector
+elements that contain spaces of double quotes. The spawn*() functions
+don't do any quoting or escaping, but on the other hand the startup
+code does do unquoting and unescaping in order to enable receiving
+arguments with embedded spaces or double quotes. To work around this
+asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
+argument vector elements that need it before calling the C runtime
spawn() function.
The returned @child_pid on Windows is a handle to the child
@@ -40695,9 +40451,8 @@ process, not its identifier. Process handles and process
identifiers are different concepts on Windows.
@envp is a %NULL-terminated array of strings, where each string
-has the form <literal>KEY=VALUE</literal>. This will become
-the child's environment. If @envp is %NULL, the child inherits its
-parent's environment.
+has the form `KEY=VALUE`. This will become the child's environment.
+If @envp is %NULL, the child inherits its parent's environment.
@flags should be the bitwise OR of any flags you want to affect the
function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
@@ -40706,22 +40461,21 @@ be notified about the death of the child process. Eventually you must
call g_spawn_close_pid() on the @child_pid, in order to free
resources which may be associated with the child process. (On Unix,
using a child watch is equivalent to calling waitpid() or handling
-the <literal>SIGCHLD</literal> signal manually. On Windows, calling g_spawn_close_pid()
+the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
is equivalent to calling CloseHandle() on the process handle returned
-in @child_pid). See g_child_watch_add().
+in @child_pid). See g_child_watch_add().
%G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file
-descriptors will be inherited by the child; otherwise all
-descriptors except stdin/stdout/stderr will be closed before
-calling exec() in the child. %G_SPAWN_SEARCH_PATH
-means that <literal>argv[0]</literal> need not be an absolute path, it
-will be looked for in the <envar>PATH</envar> environment variable.
-%G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute path, it
-will be looked for in the <envar>PATH</envar> variable from @envp. If
-both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP are used,
-the value from @envp takes precedence over the environment.
-%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will
-be discarded, instead of going to the same location as the parent's
+descriptors will be inherited by the child; otherwise all descriptors
+except stdin/stdout/stderr will be closed before calling exec() in
+the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
+absolute path, it will be looked for in the `PATH` environment
+variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
+absolute path, it will be looked for in the `PATH` variable from
+ envp If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
+are used, the value from @envp takes precedence over the environment.
+%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
+will be discarded, instead of going to the same location as the parent's
standard output. If you use this flag, @standard_output must be %NULL.
%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
will be discarded, instead of going to the same location as the parent's
@@ -40730,42 +40484,40 @@ standard error. If you use this flag, @standard_error must be %NULL.
standard input (by default, the child's standard input is attached to
/dev/null). If you use this flag, @standard_input must be %NULL.
%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
-the file to execute, while the remaining elements are the
-actual argument vector to pass to the file. Normally
-g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and
-passes all of @argv to the child.
+the file to execute, while the remaining elements are the actual
+argument vector to pass to the file. Normally g_spawn_async_with_pipes()
+uses @argv[0] as the file to execute, and passes all of @argv to the child.
@child_setup and @user_data are a function and user data. On POSIX
platforms, the function is called in the child after GLib has
performed all the setup it plans to perform (including creating
-pipes, closing file descriptors, etc.) but before calling
-exec(). That is, @child_setup is called just
-before calling exec() in the child. Obviously
-actions taken in this function will only affect the child, not the
-parent.
-
-On Windows, there is no separate fork() and exec()
-functionality. Child processes are created and run with a single
-API call, CreateProcess(). There is no sensible thing @child_setup
+pipes, closing file descriptors, etc.) but before calling exec().
+That is, @child_setup is called just before calling exec() in the
+child. Obviously actions taken in this function will only affect
+the child, not the parent.
+
+On Windows, there is no separate fork() and exec() functionality.
+Child processes are created and run with a single API call,
+CreateProcess(). There is no sensible thing @child_setup
could be used for on Windows so it is ignored and not called.
If non-%NULL, @child_pid will on Unix be filled with the child's
-process ID. You can use the process ID to send signals to the
-child, or to use g_child_watch_add() (or waitpid()) if you specified the
+process ID. You can use the process ID to send signals to the child,
+or to use g_child_watch_add() (or waitpid()) if you specified the
%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
filled with a handle to the child process only if you specified the
%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
process using the Win32 API, for example wait for its termination
-with the <function>WaitFor*()</function> functions, or examine its
-exit code with GetExitCodeProcess(). You should close the handle
-with CloseHandle() or g_spawn_close_pid() when you no longer need it.
+with the WaitFor*() functions, or examine its exit code with
+GetExitCodeProcess(). You should close the handle with CloseHandle()
+or g_spawn_close_pid() when you no longer need it.
If non-%NULL, the @standard_input, @standard_output, @standard_error
locations will be filled with file descriptors for writing to the child's
standard input or reading from its standard output or standard error.
The caller of g_spawn_async_with_pipes() must close these file descriptors
-when they are no longer in use. If these parameters are %NULL, the corresponding
-pipe won't be created.
+when they are no longer in use. If these parameters are %NULL, the
+corresponding pipe won't be created.
If @standard_input is NULL, the child's standard input is attached to
/dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
@@ -40779,11 +40531,11 @@ location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL
is set.
@error can be %NULL to ignore errors, or non-%NULL to report errors.
-If an error is set, the function returns %FALSE. Errors
-are reported even if they occur in the child (for example if the
-executable in <literal>argv[0]</literal> is not found). Typically
-the <literal>message</literal> field of returned errors should be displayed
-to users. Possible errors are those from the #G_SPAWN_ERROR domain.
+If an error is set, the function returns %FALSE. Errors are reported
+even if they occur in the child (for example if the executable in
+ argv[0] is not found). Typically the `message` field of returned
+errors should be displayed to users. Possible errors are those from
+the #G_SPAWN_ERROR domain.
If an error occurs, @child_pid, @standard_input, @standard_output,
and @standard_error will not be filled with valid values.
@@ -40791,12 +40543,10 @@ and @standard_error will not be filled with valid values.
If @child_pid is not %NULL and an error does not occur then the returned
process reference must be closed using g_spawn_close_pid().
-<note><para>
If you are writing a GTK+ application, and the program you
are spawning is a graphical application, too, then you may
want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
the spawned program opens its windows on the right screen.
-</para></note>
</description>
@@ -40857,25 +40607,23 @@ Set @error if @exit_status indicates the child exited abnormally
The g_spawn_sync() and g_child_watch_add() family of APIs return an
exit status for subprocesses encoded in a platform-specific way.
-On Unix, this is guaranteed to be in the same format
-<literal>waitpid(2)</literal> returns, and on Windows it is
-guaranteed to be the result of
-<literal>GetExitCodeProcess()</literal>. Prior to the introduction
-of this function in GLib 2.34, interpreting @exit_status required
-use of platform-specific APIs, which is problematic for software
-using GLib as a cross-platform layer.
+On Unix, this is guaranteed to be in the same format waitpid() returns,
+and on Windows it is guaranteed to be the result of GetExitCodeProcess().
+
+Prior to the introduction of this function in GLib 2.34, interpreting
+ exit_status required use of platform-specific APIs, which is problematic
+for software using GLib as a cross-platform layer.
Additionally, many programs simply want to determine whether or not
the child exited successfully, and either propagate a #GError or
-print a message to standard error. In that common case, this
-function can be used. Note that the error message in @error will
-contain human-readable information about the exit status.
+print a message to standard error. In that common case, this function
+can be used. Note that the error message in @error will contain
+human-readable information about the exit status.
-The <literal>domain</literal> and <literal>code</literal> of @error
-have special semantics in the case where the process has an "exit
-code", as opposed to being killed by a signal. On Unix, this
-happens if <literal>WIFEXITED</literal> would be true of
- exit_status On Windows, it is always the case.
+The @domain and @code of @error have special semantics in the case
+where the process has an "exit code", as opposed to being killed by
+a signal. On Unix, this happens if WIFEXITED() would be true of
+ exit_status On Windows, it is always the case.
The special semantics are that the actual exit code will be the
code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
@@ -40887,10 +40635,9 @@ status, the domain will be %G_SPAWN_ERROR, and the code will be
This function just offers convenience; you can of course also check
the available platform via a macro such as %G_OS_UNIX, and use
-<literal>WIFEXITED()</literal> and <literal>WEXITSTATUS()</literal>
-on @exit_status directly. Do not attempt to scan or parse the
-error message string; it may be translated and/or change in future
-versions of GLib.
+WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt
+to scan or parse the error message string; it may be translated and/or
+change in future versions of GLib.
Since: 2.34
@@ -40905,7 +40652,9 @@ Since: 2.34
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if child exited successfully, %FALSE otherwise (and @error will be set)
+<return> %TRUE if child exited successfully, %FALSE otherwise (and
+ error will be set)
+
</return>
</function>
@@ -40950,7 +40699,7 @@ The same concerns on Windows apply as for g_spawn_command_line_sync().
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE on success, %FALSE if error is set.
+<return> %TRUE on success, %FALSE if error is set
</return>
</function>
@@ -41072,7 +40821,7 @@ how these functions work on Windows.
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE on success, %FALSE if an error was set.
+<return> %TRUE on success, %FALSE if an error was set
</return>
</function>
@@ -41098,7 +40847,7 @@ enough to hold the formatted result
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="Varargs">
@@ -41117,21 +40866,20 @@ A wrapper for the POSIX stat() function. The stat() function
returns information about a file. On Windows the stat() function in
the C library checks only the FAT-style READONLY attribute and does
not look at the ACL at all. Thus on Windows the protection bits in
-the st_mode field are a fabrication of little use.
+the @st_mode field are a fabrication of little use.
On Windows the Microsoft C libraries have several variants of the
-<structname>stat</structname> struct and stat() function with names
-like "_stat", "_stat32", "_stat32i64" and "_stat64i32". The one
-used here is for 32-bit code the one with 32-bit size and time
-fields, specifically called "_stat32".
+stat struct and stat() function with names like _stat(), _stat32(),
+_stat32i64() and _stat64i32(). The one used here is for 32-bit code
+the one with 32-bit size and time fields, specifically called _stat32().
-In Microsoft's compiler, by default "struct stat" means one with
-64-bit time fields while in MinGW "struct stat" is the legacy one
+In Microsoft's compiler, by default struct stat means one with
+64-bit time fields while in MinGW struct stat is the legacy one
with 32-bit fields. To hopefully clear up this messs, the gstdio.h
-header defines a type GStatBuf which is the appropriate struct type
+header defines a type #GStatBuf which is the appropriate struct type
depending on the platform and/or compiler being used. On POSIX it
-is just "struct stat", but note that even on POSIX platforms,
-"stat" might be a macro.
+is just struct stat, but note that even on POSIX platforms, stat()
+might be a macro.
See your C library manual for more details about stat().
@@ -41144,13 +40892,13 @@ Since: 2.6
</parameter_description>
</parameter>
<parameter name="buf">
-<parameter_description> a pointer to a <structname>stat</structname> struct, which
-will be filled with the file information
+<parameter_description> a pointer to a stat struct, which will be filled with the file
+information
</parameter_description>
</parameter>
</parameters>
-<return> 0 if the information was successfully retrieved, -1 if an error
-occurred
+<return> 0 if the information was successfully retrieved,
+-1 if an error occurred
</return>
</function>
@@ -41164,8 +40912,8 @@ unbounded lifetime, i.e. objects declared 'static', but if you have
a #GStaticMutex as a member of a structure and the structure is
freed, you should also free the #GStaticMutex.
-<note><para>Calling g_static_mutex_free() on a locked mutex may
-result in undefined behaviour.</para></note>
+Calling g_static_mutex_free() on a locked mutex may result in
+undefined behaviour.
Deprecated: 2.32: Use g_mutex_clear()
@@ -41330,8 +41078,7 @@ If g_thread_init() is called later, the @data keyed to @private_key
will be inherited only by the main thread, i.e. the one that called
g_thread_init().
-<note><para>@notify is used quite differently from @destructor in
-g_private_new().</para></note>
+ notify is used quite differently from @destructor in g_private_new().
</description>
<parameters>
@@ -41575,11 +41322,11 @@ g_static_rw_lock_reader_unlock().
</description>
<parameters>
<parameter name="lock">
-<parameter_description> a #GStaticRWLock to lock for reading.
+<parameter_description> a #GStaticRWLock to lock for reading
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE, if @lock could be locked for reading.
+<return> %TRUE, if @lock could be locked for reading
Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead
</return>
@@ -41596,7 +41343,7 @@ Deprectated: 2.32: Use g_rw_lock_reader_unlock() instead
</description>
<parameters>
<parameter name="lock">
-<parameter_description> a #GStaticRWLock to unlock after reading.
+<parameter_description> a #GStaticRWLock to unlock after reading
</parameter_description>
</parameter>
</parameters>
@@ -41618,7 +41365,7 @@ Deprectated: 2.32: Use g_rw_lock_writer_lock() instead
</description>
<parameters>
<parameter name="lock">
-<parameter_description> a #GStaticRWLock to lock for writing.
+<parameter_description> a #GStaticRWLock to lock for writing
</parameter_description>
</parameter>
</parameters>
@@ -41636,11 +41383,11 @@ lock has to be unlocked by g_static_rw_lock_writer_unlock().
</description>
<parameters>
<parameter name="lock">
-<parameter_description> a #GStaticRWLock to lock for writing.
+<parameter_description> a #GStaticRWLock to lock for writing
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE, if @lock could be locked for writing.
+<return> %TRUE, if @lock could be locked for writing
Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead
</return>
@@ -41765,11 +41512,11 @@ Since: 2.2
<description>
Converts a string to a hash value.
-This function implements the widely used "djb" hash apparently posted
-by Daniel Bernstein to comp.lang.c some time ago. The 32 bit
-unsigned hash value starts at 5381 and for each byte 'c' in the
-string, is updated: <literal>hash = hash * 33 + c</literal>. This
-function uses the signed value of each byte.
+This function implements the widely used "djb" hash apparently
+posted by Daniel Bernstein to comp.lang.c some time ago. The 32
+bit unsigned hash value starts at 5381 and for each byte 'c' in
+the string, is updated: `hash = hash * 33 + c`. This function
+uses the signed value of each byte.
It can be passed to g_hash_table_new() as the @hash_func parameter,
when using non-%NULL strings as keys in a #GHashTable.
@@ -41788,19 +41535,19 @@ when using non-%NULL strings as keys in a #GHashTable.
<function name="g_str_is_ascii">
<description>
-Determines if a string is pure ASCII. A string is pure ASCII if it
+Determines if a string is pure ASCII. A string is pure ASCII if it
contains no bytes with the high bit set.
Since: 2.40
</description>
<parameters>
-<parameter name="string">
-<parameter_description> a string.
+<parameter name="str">
+<parameter_description> a string
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if @string is ascii
+<return> %TRUE if @str is ASCII
</return>
</function>
@@ -41852,6 +41599,43 @@ Since: 2.40
</return>
</function>
+<function name="g_str_to_ascii">
+<description>
+Transliterate @str to plain ASCII.
+
+For best results, @str should be in composed normalised form.
+
+This function performs a reasonably good set of character
+replacements. The particular set of replacements that is done may
+change by version or even by runtime environment.
+
+If the source language of @str is known, it can used to improve the
+accuracy of the translation by passing it as @from_locale. It should
+be a valid POSIX locale string (of the form
+"language[_territory][ codeset][ modifier]").
+
+If @from_locale is %NULL then the current locale is used.
+
+If you want to do translation for no specific locale, and you want it
+to be done independently of the currently locale, specify "C" for
+ from_locale
+
+
+</description>
+<parameters>
+<parameter name="str">
+<parameter_description> a string, in UTF-8
+</parameter_description>
+</parameter>
+<parameter name="from_locale">
+<parameter_description> the source locale, if known
+</parameter_description>
+</parameter>
+</parameters>
+<return> a string in plain ASCII
+</return>
+</function>
+
<function name="g_str_tokenize_and_fold">
<description>
Tokenises @string and performs folding on each token.
@@ -41896,11 +41680,11 @@ return location for ASCII alternates
<function name="g_strcanon">
<description>
-For each character in @string, if the character is not in
- valid_chars, replaces the character with @substitutor.
-Modifies @string in place, and return @string itself, not
-a copy. The return value is to allow nesting such as
-|[
+For each character in @string, if the character is not in @valid_chars,
+replaces the character with @substitutor. Modifies @string in place,
+and return @string itself, not a copy. The return value is to allow
+nesting such as
+|[<!-- language="C" -->
g_ascii_strup (g_strcanon (str, "abc", '?'))
]|
@@ -41929,17 +41713,17 @@ g_ascii_strup (g_strcanon (str, "abc", '?'))
A case-insensitive string comparison, corresponding to the standard
strcasecmp() function on platforms which support it.
-Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
-is deprecated and how to replace it.
+Deprecated:2.2: See g_strncasecmp() for a discussion of why this
+function is deprecated and how to replace it.
</description>
<parameters>
<parameter name="s1">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
<parameter name="s2">
-<parameter_description> a string to compare with @s1.
+<parameter_description> a string to compare with @s1
</parameter_description>
</parameter>
</parameters>
@@ -41954,8 +41738,10 @@ or a positive value if @s1 > @s2.
Removes trailing whitespace from a string.
This function doesn't allocate or reallocate any memory;
-it modifies @string in place. The pointer to @string is
-returned to allow the nesting of functions.
+it modifies @string in place. Therefore, it cannot be used
+on statically allocated strings.
+
+The pointer to @string is returned to allow the nesting of functions.
Also see g_strchug() and g_strstrip().
@@ -41967,7 +41753,7 @@ Also see g_strchug() and g_strstrip().
</parameter_description>
</parameter>
</parameters>
-<return> @string.
+<return> @string
</return>
</function>
@@ -41977,8 +41763,10 @@ Removes leading whitespace from a string, by moving the rest
of the characters forward.
This function doesn't allocate or reallocate any memory;
-it modifies @string in place. The pointer to @string is
-returned to allow the nesting of functions.
+it modifies @string in place. Therefore, it cannot be used on
+statically allocated strings.
+
+The pointer to @string is returned to allow the nesting of functions.
Also see g_strchomp() and g_strstrip().
@@ -42039,17 +41827,16 @@ character compressed
<function name="g_strconcat">
<description>
-Concatenates all of the given strings into one long string.
-The returned string should be freed with g_free() when no longer needed.
+Concatenates all of the given strings into one long string. The
+returned string should be freed with g_free() when no longer needed.
+
+The variable argument list must end with %NULL. If you forget the %NULL,
+g_strconcat() will start appending random memory junk to your string.
Note that this function is usually not the right function to use to
assemble a translated message from pieces, since proper translation
often requires the pieces to be reordered.
-<warning><para>The variable argument list <emphasis>must</emphasis> end
-with %NULL. If you forget the %NULL, g_strconcat() will start appending
-random memory junk to your string.</para></warning>
-
</description>
<parameters>
@@ -42073,7 +41860,7 @@ Any characters in @string which are found in @delimiters are
changed to the @new_delimiter character. Modifies @string in place,
and returns @string itself, not a copy. The return value is to
allow nesting such as
-|[
+|[<!-- language="C" -->
g_ascii_strup (g_strdelimit (str, "abc", '?'))
]|
@@ -42085,8 +41872,8 @@ g_ascii_strup (g_strdelimit (str, "abc", '?'))
</parameter_description>
</parameter>
<parameter name="delimiters">
-<parameter_description> a string containing the current delimiters, or %NULL
-to use the standard delimiters defined in #G_STR_DELIMITERS
+<parameter_description> a string containing the current delimiters,
+or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
</parameter_description>
</parameter>
<parameter name="new_delimiter">
@@ -42148,7 +41935,7 @@ longer needed.
<parameters>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="Varargs">
@@ -42194,7 +41981,7 @@ additionally returns the length of the allocated string.
<parameters>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="args">
@@ -43336,7 +43123,8 @@ should be freed with g_free().
</description>
<parameters>
<parameter name="separator">
-<parameter_description> a string to insert between each of the strings, or %NULL
+<parameter_description> a string to insert between each of the
+strings, or %NULL
</parameter_description>
</parameter>
<parameter name="Varargs">
@@ -43359,7 +43147,8 @@ should be freed with g_free().
</description>
<parameters>
<parameter name="separator">
-<parameter_description> a string to insert between each of the strings, or %NULL
+<parameter_description> a string to insert between each of the
+strings, or %NULL
</parameter_description>
</parameter>
<parameter name="str_array">
@@ -43379,15 +43168,14 @@ and emulates it otherwise. Appends nul-terminated @src string to @dest,
guaranteeing nul-termination for @dest. The total size of @dest won't
exceed @dest_size.
-At most dest_size - 1 characters will be copied.
-Unlike strncat, dest_size is the full size of dest, not the space left over.
-This function does NOT allocate memory.
-This always NUL terminates (unless siz == 0 or there were no NUL characters
-in the dest_size characters of dest to start with).
+At most @dest_size - 1 characters will be copied. Unlike strncat(),
+ dest_size is the full size of dest, not the space left over. This
+function does not allocate memory. It always nul-terminates (unless
+ dest_size == 0 or there were no nul characters in the @dest_size
+characters of dest to start with).
-<note><para>Caveat: this is supposedly a more secure alternative to
-strcat() or strncat(), but for real security g_strconcat() is harder
-to mess up.</para></note>
+Caveat: this is supposedly a more secure alternative to strcat() or
+strncat(), but for real security g_strconcat() is harder to mess up.
</description>
@@ -43417,17 +43205,17 @@ truncation occurred.
Portability wrapper that calls strlcpy() on systems which have it,
and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
guaranteed to be nul-terminated; @src must be nul-terminated;
- dest_size is the buffer size, not the number of chars to copy.
+ dest_size is the buffer size, not the number of bytes to copy.
-At most dest_size - 1 characters will be copied. Always nul-terminates
-(unless dest_size == 0). This function does <emphasis>not</emphasis>
-allocate memory. Unlike strncpy(), this function doesn't pad dest (so
-it's often faster). It returns the size of the attempted result,
-strlen (src), so if @retval >= @dest_size, truncation occurred.
+At most @dest_size - 1 characters will be copied. Always nul-terminates
+(unless @dest_size is 0). This function does not allocate memory. Unlike
+strncpy(), this function doesn't pad @dest (so it's often faster). It
+returns the size of the attempted result, strlen (src), so if
+ retval >= @dest_size, truncation occurred.
-<note><para>Caveat: strlcpy() is supposedly more secure than
-strcpy() or strncpy(), but if you really want to avoid screwups,
-g_strdup() is an even better idea.</para></note>
+Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
+but if you really want to avoid screwups, g_strdup() is an even better
+idea.
</description>
@@ -43452,37 +43240,37 @@ g_strdup() is an even better idea.</para></note>
<function name="g_strncasecmp">
<description>
A case-insensitive string comparison, corresponding to the standard
-strncasecmp() function on platforms which support it.
-It is similar to g_strcasecmp() except it only compares the first @n
-characters of the strings.
-
-Deprecated:2.2: The problem with g_strncasecmp() is that it does the
-comparison by calling toupper()/tolower(). These functions are
-locale-specific and operate on single bytes. However, it is impossible
-to handle things correctly from an I18N standpoint by operating on
-bytes, since characters may be multibyte. Thus g_strncasecmp() is
-broken if your string is guaranteed to be ASCII, since it's
-locale-sensitive, and it's broken if your string is localized, since
-it doesn't work on many encodings at all, including UTF-8, EUC-JP,
-etc.
+strncasecmp() function on platforms which support it. It is similar
+to g_strcasecmp() except it only compares the first @n characters of
+the strings.
+
+Deprecated:2.2: The problem with g_strncasecmp() is that it does
+the comparison by calling toupper()/tolower(). These functions
+are locale-specific and operate on single bytes. However, it is
+impossible to handle things correctly from an internationalization
+standpoint by operating on bytes, since characters may be multibyte.
+Thus g_strncasecmp() is broken if your string is guaranteed to be
+ASCII, since it is locale-sensitive, and it's broken if your string
+is localized, since it doesn't work on many encodings at all,
+including UTF-8, EUC-JP, etc.
There are therefore two replacement techniques: g_ascii_strncasecmp(),
which only works on ASCII and is not locale-sensitive, and
-g_utf8_casefold() followed by strcmp() on the resulting strings, which is
-good for case-insensitive sorting of UTF-8.
+g_utf8_casefold() followed by strcmp() on the resulting strings,
+which is good for case-insensitive sorting of UTF-8.
</description>
<parameters>
<parameter name="s1">
-<parameter_description> a string.
+<parameter_description> a string
</parameter_description>
</parameter>
<parameter name="s2">
-<parameter_description> a string to compare with @s1.
+<parameter_description> a string to compare with @s1
</parameter_description>
</parameter>
<parameter name="n">
-<parameter_description> the maximum number of characters to compare.
+<parameter_description> the maximum number of characters to compare
</parameter_description>
</parameter>
</parameters>
@@ -43495,15 +43283,13 @@ or a positive value if @s1 > @s2.
<function name="g_strndup">
<description>
Duplicates the first @n bytes of a string, returning a newly-allocated
-buffer @n + 1 bytes long which will always be nul-terminated.
-If @str is less than @n bytes long the buffer is padded with nuls.
-If @str is %NULL it returns %NULL.
-The returned value should be freed when no longer needed.
+buffer @n + 1 bytes long which will always be nul-terminated. If @str
+is less than @n bytes long the buffer is padded with nuls. If @str is
+%NULL it returns %NULL. The returned value should be freed when no longer
+needed.
-<note><para>
-To copy a number of characters from a UTF-8 encoded string, use
-g_utf8_strncpy() instead.
-</para></note>
+To copy a number of characters from a UTF-8 encoded string,
+use g_utf8_strncpy() instead.
</description>
@@ -43546,8 +43332,7 @@ The returned string should be freed when no longer needed.
<function name="g_strreverse">
<description>
Reverses all of the bytes in a string. For example,
-<literal>g_strreverse ("abcdef")</literal> will result
-in "fedcba".
+`g_strreverse ("abcdef")` will result in "fedcba".
Note that g_strreverse() doesn't work on UTF-8 strings
containing multibyte characters. For that purpose, use
@@ -43625,8 +43410,7 @@ the strsignal() function.
</description>
<parameters>
<parameter name="signum">
-<parameter_description> the signal number. See the <literal>signal</literal>
-documentation
+<parameter_description> the signal number. See the `signal` documentation
</parameter_description>
</parameter>
</parameters>
@@ -43802,13 +43586,14 @@ the last character used in the conversion.
<description>
Converts a string to upper case.
-Deprecated:2.2: This function is totally broken for the reasons discussed
-in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
+Deprecated:2.2: This function is totally broken for the reasons
+discussed in the g_strncasecmp() docs - use g_ascii_strup()
+or g_utf8_strup() instead.
</description>
<parameters>
<parameter name="string">
-<parameter_description> the string to convert.
+<parameter_description> the string to convert
</parameter_description>
</parameter>
</parameters>
@@ -43887,8 +43672,7 @@ will be passed as first argument to @test_func.
If @testpath includes the component "subprocess" anywhere in it,
the test will be skipped by default, and only run if explicitly
-required via the <option>-p</option> command-line option or
-g_test_trap_subprocess().
+required via the `-p` command-line option or g_test_trap_subprocess().
Since: 2.16
@@ -43948,8 +43732,7 @@ slash-separated portions of @testpath.
If @testpath includes the component "subprocess" anywhere in it,
the test will be skipped by default, and only run if explicitly
-required via the <option>-p</option> command-line option or
-g_test_trap_subprocess().
+required via the `-p` command-line option or g_test_trap_subprocess().
Since: 2.16
@@ -44042,7 +43825,7 @@ system of that module (%G_TEST_BUILT).
In order for this function to work in srcdir != builddir situations,
the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to
-have been defined. As of 2.38, this is done by the Makefile.decl
+have been defined. As of 2.38, this is done by the glib.mk
included in GLib. Please ensure that your copy is up to date before
using this function.
@@ -44160,10 +43943,9 @@ the same order as the calls to g_test_expect_message().)
For example:
-|[
-/ * g_main_context_push_thread_default() should fail if the
-* context is already owned by another thread.
-* /
+|[<!-- language="C" -->
+// g_main_context_push_thread_default() should fail if the
+// context is already owned by another thread.
g_test_expect_message (G_LOG_DOMAIN,
G_LOG_LEVEL_CRITICAL,
"assertion*acquired_context*failed");
@@ -44191,8 +43973,7 @@ Since: 2.34
</parameter_description>
</parameter>
<parameter name="pattern">
-<parameter_description> a glob-style
-<link linkend="glib-Glob-style-pattern-matching">pattern</link>
+<parameter_description> a glob-style [pattern][glib-Glob-style-pattern-matching]
</parameter_description>
</parameter>
</parameters>
@@ -44349,82 +44130,32 @@ Since: 2.38
Initialize the GLib testing framework, e.g. by seeding the
test random number generator, the name for g_get_prgname()
and parsing test related command line args.
+
So far, the following arguments are understood:
-<variablelist>
-<varlistentry>
-<term><option>-l</option></term>
-<listitem><para>
-List test cases available in a test executable.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term>
-<listitem><para>
-Provide a random seed to reproduce test runs using random numbers.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>--verbose</option></term>
-<listitem><para>Run tests verbosely.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-q</option>, <option>--quiet</option></term>
-<listitem><para>Run tests quietly.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-p <replaceable>TESTPATH</replaceable></option></term>
-<listitem><para>
-Execute all tests matching <replaceable>TESTPATH</replaceable>.
+
+- `-l`: List test cases available in a test executable.
+- `--seed=SEED`: Provide a random seed to reproduce test
+runs using random numbers.
+- `--verbose`: Run tests verbosely.
+- `-q`, `--quiet`: Run tests quietly.
+- `-p PATH`: Execute all tests matching the given path.
This can also be used to force a test to run that would otherwise
be skipped (ie, a test whose name contains "/subprocess").
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>-m {perf|slow|thorough|quick|undefined|no-undefined}</option></term>
-<listitem><para>
-Execute tests according to these test modes:
-<variablelist>
-<varlistentry>
-<term>perf</term>
-<listitem><para>
-Performance tests, may take long and report results.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>slow, thorough</term>
-<listitem><para>
-Slow and thorough tests, may take quite long and
-maximize coverage.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>quick</term>
-<listitem><para>
-Quick tests, should run really quickly and give good coverage.
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>undefined</term>
-<listitem><para>
-Tests for undefined behaviour, may provoke programming errors
+- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
+
+`perf`: Performance tests, may take long and report results.
+
+`slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage.
+
+`quick`: Quick tests, should run really quickly and give good coverage.
+
+`undefined`: Tests for undefined behaviour, may provoke programming errors
under g_test_trap_subprocess() or g_test_expect_messages() to check
that appropriate assertions or warnings are given
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>no-undefined</term>
-<listitem><para>
-Avoid tests for undefined behaviour
-</para></listitem>
-</varlistentry>
-</variablelist>
-</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><option>--debug-log</option></term>
-<listitem><para>Debug test logging output.</para></listitem>
-</varlistentry>
-</variablelist>
+
+`no-undefined`: Avoid tests for undefined behaviour
+
+- `--debug-log`: Debug test logging output.
Since: 2.16
@@ -44442,7 +44173,7 @@ Any parameters understood by g_test_init() stripped before return.
</parameter>
<parameter name="Varargs">
<parameter_description> %NULL-terminated list of special options. Currently the only
-defined option is <literal>"no_g_set_prgname"</literal>, which
+defined option is `"no_g_set_prgname"`, which
will cause g_test_init() to not call g_set_prgname().
</parameter_description>
</parameter>
@@ -44824,15 +44555,13 @@ Since: 2.16
<description>
Runs all tests under the toplevel suite which can be retrieved
with g_test_get_root(). Similar to g_test_run_suite(), the test
-cases to be run are filtered according to
-test path arguments (-p <replaceable>testpath</replaceable>) as
-parsed by g_test_init().
-g_test_run_suite() or g_test_run() may only be called once
-in a program.
+cases to be run are filtered according to test path arguments
+(`-p testpath`) as parsed by g_test_init(). g_test_run_suite()
+or g_test_run() may only be called once in a program.
In general, the tests and sub-suites within each suite are run in
the order in which they are defined. However, note that prior to
-GLib 2.36, there was a bug in the <literal>g_test_add_*</literal>
+GLib 2.36, there was a bug in the `g_test_add_*`
functions which caused them to create multiple suites with the same
name, meaning that if you created tests "/foo/simple",
"/bar/simple", and "/foo/using-bar" in that order, they would get
@@ -44852,13 +44581,16 @@ on the order that tests are run in. If you need to ensure that some
particular code runs before or after a given test case, use
g_test_add(), which lets you specify setup and teardown functions.
+If all tests are skipped, this function will return 0 if
+producing TAP output, or 77 (treated as "skip test" by Automake) otherwise.
+
Since: 2.16
</description>
<parameters>
</parameters>
<return> 0 on success, 1 on failure (assuming it returns at all),
-77 if all tests were skipped with g_test_skip().
+0 or 77 if all tests were skipped with g_test_skip()
</return>
</function>
@@ -44867,9 +44599,9 @@ Since: 2.16
<description>
Execute the tests within @suite and all nested #GTestSuites.
The test suites to be executed are filtered according to
-test path arguments (-p <replaceable>testpath</replaceable>)
-as parsed by g_test_init(). See the g_test_run() documentation
-for more information on the order that tests are run in.
+test path arguments (`-p testpath`) as parsed by g_test_init().
+See the g_test_run() documentation for more information on the
+order that tests are run in.
g_test_run_suite() or g_test_run() may only be called once
in a program.
@@ -45108,8 +44840,7 @@ Since: 2.16
</description>
<parameters>
<parameter name="serrpattern">
-<parameter_description> a glob-style
-<link linkend="glib-Glob-style-pattern-matching">pattern</link>
+<parameter_description> a glob-style [pattern][glib-Glob-style-pattern-matching]
</parameter_description>
</parameter>
</parameters>
@@ -45126,8 +44857,7 @@ Since: 2.16
</description>
<parameters>
<parameter name="serrpattern">
-<parameter_description> a glob-style
-<link linkend="glib-Glob-style-pattern-matching">pattern</link>
+<parameter_description> a glob-style [pattern][glib-Glob-style-pattern-matching]
</parameter_description>
</parameter>
</parameters>
@@ -45144,8 +44874,7 @@ Since: 2.16
</description>
<parameters>
<parameter name="soutpattern">
-<parameter_description> a glob-style
-<link linkend="glib-Glob-style-pattern-matching">pattern</link>
+<parameter_description> a glob-style [pattern][glib-Glob-style-pattern-matching]
</parameter_description>
</parameter>
</parameters>
@@ -45162,8 +44891,7 @@ Since: 2.16
</description>
<parameters>
<parameter name="soutpattern">
-<parameter_description> a glob-style
-<link linkend="glib-Glob-style-pattern-matching">pattern</link>
+<parameter_description> a glob-style [pattern][glib-Glob-style-pattern-matching]
</parameter_description>
</parameter>
</parameters>
@@ -45185,7 +44913,7 @@ process produces some sample output and exits successfully.
The forking parent process then asserts successful child program
termination and validates child program outputs.
-|[
+|[<!-- language="C" -->
static void
test_fork_patterns (void)
{
@@ -45193,7 +44921,7 @@ if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR
{
g_print ("some stdout text: somagic17\n");
g_printerr ("some stderr text: semagic43\n");
-exit (0); / * successful test run * /
+exit (0); // successful test run
}
g_test_trap_assert_passed ();
g_test_trap_assert_stdout ("*somagic17*");
@@ -45261,12 +44989,11 @@ If @test_path is %NULL then the same test is re-run in a subprocess.
You can use g_test_subprocess() to determine whether the test is in
a subprocess or not.
- test_path can also be the name of the parent
-test, followed by "<literal>/subprocess/</literal>" and then a name
-for the specific subtest (or just ending with
-"<literal>/subprocess</literal>" if the test only has one child
-test); tests with names of this form will automatically be skipped
-in the parent process.
+ test_path can also be the name of the parent test, followed by
+"`/subprocess/`" and then a name for the specific subtest (or just
+ending with "`/subprocess`" if the test only has one child test);
+tests with names of this form will automatically be skipped in the
+parent process.
If @usec_timeout is non-0, the test subprocess is aborted and
considered failing if its run time exceeds it.
@@ -45281,15 +45008,15 @@ g_test_trap_assert_stdout() and g_test_trap_assert_stderr()
cannot be used if @test_flags specifies that the child should
inherit the parent stdout/stderr.)
-If your <literal>main ()</literal> needs to behave differently in
+If your `main ()` needs to behave differently in
the subprocess, you can call g_test_subprocess() (after calling
g_test_init()) to see whether you are in a subprocess.
The following example tests that calling
-<literal>my_object_new(1000000)</literal> will abort with an error
+`my_object_new(1000000)` will abort with an error
message.
-|[
+|[<!-- language="C" -->
static void
test_create_large_object_subprocess (void)
{
@@ -45299,7 +45026,7 @@ my_object_new (1000000);
return;
}
-/ * Reruns this same test in a subprocess * /
+// Reruns this same test in a subprocess
g_test_trap_subprocess (NULL, 0, 0);
g_test_trap_assert_failed ();
g_test_trap_assert_stderr ("*ERROR*too large*");
@@ -45455,15 +45182,13 @@ If another thread is waiting for us using g_thread_join() then the
waiting thread will be woken up and get @retval as the return value
of g_thread_join().
-Calling <literal>g_thread_exit (retval)</literal> is equivalent to
+Calling g_thread_exit() with a parameter @retval is equivalent to
returning @retval from the function @func, as given to g_thread_new().
-<note><para>
You must only call g_thread_exit() from a thread that you created
-yourself with g_thread_new() or related APIs. You must not call
+yourself with g_thread_new() or related APIs. You must not call
this function from a thread created with another threading library
or or from within a #GThreadPool.
-</para></note>
</description>
<parameters>
@@ -46190,11 +45915,11 @@ and only if it is nonzero, i.e. either
"YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".
This corresponds to the Internet date/time format defined by
-<ulink url="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</ulink>, and
-to either of the two most-precise formats defined by
-<ulink url="http://www.w3.org/TR/NOTE-datetime-19980827">the W3C Note
-"Date and Time Formats"</ulink>. Both of these documents are profiles of
-ISO 8601.
+[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt),
+and to either of the two most-precise formats defined by
+the W3C Note
+[Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827).
+Both of these documents are profiles of ISO 8601.
Use g_date_time_format() or g_strdup_printf() if a different
variation of ISO 8601 format is required.
@@ -46380,29 +46105,29 @@ Since: 2.26
Creates a #GTimeZone corresponding to @identifier.
@identifier can either be an RFC3339/ISO 8601 time offset or
-something that would pass as a valid value for the
-<varname>TZ</varname> environment variable (including %NULL).
+something that would pass as a valid value for the `TZ` environment
+variable (including %NULL).
In Windows, @identifier can also be the unlocalized name of a time
zone for standard time, for example "Pacific Standard Time".
-Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or
-<literal>"±hh:mm"</literal>. ISO 8601 additionally specifies
-<literal>"±hhmm"</literal> and <literal>"±hh"</literal>.
Offsets are
+Valid RFC3339 time offsets are `"Z"` (for UTC) or
+`"±hh:mm"`. ISO 8601 additionally specifies
+`"±hhmm"` and `"±hh"`. Offsets are
time values to be added to Coordinated Universal Time (UTC) to get
the local time.
-In Unix, the <varname>TZ</varname> environment variable typically
-corresponds to the name of a file in the zoneinfo database, or
-string in "std offset [dst [offset],start[/time],end[/time]]"
-(POSIX) format. There are no spaces in the specification. The
-name of standard and daylight savings time zone must be three or more
-alphabetic characters. Offsets are time values to be added to local
-time to get Coordinated Universal Time (UTC) and should be
-<literal>"[±]hh[[:]mm[:ss]]"</literal>. Dates are either
-<literal>"Jn"</literal> (Julian day with n between 1 and 365, leap
-years not counted), <literal>"n"</literal> (zero-based Julian day
-with n between 0 and 365) or <literal>"Mm.w.d"</literal> (day d
+In UNIX, the `TZ` environment variable typically corresponds
+to the name of a file in the zoneinfo database, or string in
+"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
+There are no spaces in the specification. The name of standard
+and daylight savings time zone must be three or more alphabetic
+characters. Offsets are time values to be added to local time to
+get Coordinated Universal Time (UTC) and should be
+`"[±]hh[[:]mm[:ss]]"`. Dates are either
+`"Jn"` (Julian day with n between 1 and 365, leap
+years not counted), `"n"` (zero-based Julian day
+with n between 0 and 365) or `"Mm.w.d"` (day d
(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
0 is a Sunday). Times are in local wall clock time, the default is
02:00:00.
@@ -46415,30 +46140,28 @@ Offsets are time values to be added to the local time to get
Coordinated Universal Time (UTC).
g_time_zone_new_local() calls this function with the value of the
-<varname>TZ</varname> environment variable. This function itself is
-independent of the value of <varname>TZ</varname>, but if @identifier
-is %NULL then <filename>/etc/localtime</filename> will be consulted
-to discover the correct time zone on Unix and the registry will be
-consulted or GetTimeZoneInformation() will be used to get the local
-time zone on Windows.
-
-If intervals are not available, only time zone rules from
-<varname>TZ</varname> environment variable or other means, then they
-will be computed from year 1900 to 2037. If the maximum year for the
-rules is available and it is greater than 2037, then it will followed
+`TZ` environment variable. This function itself is independent of
+the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
+will be consulted to discover the correct time zone on UNIX and the
+registry will be consulted or GetTimeZoneInformation() will be used
+to get the local time zone on Windows.
+
+If intervals are not available, only time zone rules from `TZ`
+environment variable or other means, then they will be computed
+from year 1900 to 2037. If the maximum year for the rules is
+available and it is greater than 2037, then it will followed
instead.
-See <ulink
-url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339
-§5.6</ulink> for a precise definition of valid RFC3339 time offsets
-(the <varname>time-offset</varname> expansion) and ISO 8601 for the
-full list of valid time offsets. See <ulink
-url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The
-GNU C Library manual</ulink> for an explanation of the possible
-values of the <varname>TZ</varname> environment variable. See <ulink
-url='http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx'>
-Microsoft Time Zone Index Values</ulink> for the list of time zones
-on Windows.
+See
+[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
+for a precise definition of valid RFC3339 time offsets
+(the `time-offset` expansion) and ISO 8601 for the
+full list of valid time offsets. See
+[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
+for an explanation of the possible
+values of the `TZ` environment variable. See
+[Microsoft Time Zone Index
Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
+for the list of time zones on Windows.
You should release the return value by calling g_time_zone_unref()
when you are done with it.
@@ -46463,9 +46186,8 @@ Creates a #GTimeZone corresponding to local time. The local time
zone may change between invocations to this function; for example,
if the system administrator changes it.
-This is equivalent to calling g_time_zone_new() with the value of the
-<varname>TZ</varname> environment variable (including the possibility
-of %NULL).
+This is equivalent to calling g_time_zone_new() with the value of
+the `TZ` environment variable (including the possibility of %NULL).
You should release the return value by calling g_time_zone_unref()
when you are done with it.
@@ -46988,14 +46710,14 @@ Pushes a piece of memory onto a #GTrashStack.
Removes all keys and values from the #GTree and decreases its
reference count by one. If keys and/or values are dynamically
allocated, you should either free them first or create the #GTree
-using g_tree_new_full(). In the latter case the destroy functions
+using g_tree_new_full(). In the latter case the destroy functions
you supplied will be called on all keys and values before destroying
the #GTree.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
</parameters>
@@ -47016,7 +46738,7 @@ the tree, then walk the list and remove each item.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="func">
@@ -47025,7 +46747,7 @@ If this function returns %TRUE, the traversal is stopped.
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> user data to pass to the function.
+<parameter_description> user data to pass to the function
</parameter_description>
</parameter>
</parameters>
@@ -47044,21 +46766,23 @@ If the root node has children the height is 2, etc.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
</parameters>
-<return> the height of the #GTree.
+<return> the height of @tree
</return>
</function>
<function name="g_tree_insert">
<description>
-Inserts a key/value pair into a #GTree. If the given key already exists
-in the #GTree its corresponding value is set to the new value. If you
-supplied a value_destroy_func when creating the #GTree, the old value is
-freed using that function. If you supplied a @key_destroy_func when
-creating the #GTree, the passed key is freed using that function.
+Inserts a key/value pair into a #GTree.
+
+If the given key already exists in the #GTree its corresponding value
+is set to the new value. If you supplied a @value_destroy_func when
+creating the #GTree, the old value is freed using that function. If
+you supplied a @key_destroy_func when creating the #GTree, the passed
+key is freed using that function.
The tree is automatically 'balanced' as new key/value pairs are added,
so that the distance from the root to every leaf is as small as possible.
@@ -47066,15 +46790,15 @@ so that the distance from the root to every leaf is as small as possible.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="key">
-<parameter_description> the key to insert.
+<parameter_description> the key to insert
</parameter_description>
</parameter>
<parameter name="value">
-<parameter_description> the value corresponding to the key.
+<parameter_description> the value corresponding to the key
</parameter_description>
</parameter>
</parameters>
@@ -47084,54 +46808,54 @@ so that the distance from the root to every leaf is as small as possible.
<function name="g_tree_lookup">
<description>
Gets the value corresponding to the given key. Since a #GTree is
-automatically balanced as key/value pairs are added, key lookup is very
-fast.
+automatically balanced as key/value pairs are added, key lookup
+is O(log n) (where n is the number of key/value pairs in the tree).
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="key">
-<parameter_description> the key to look up.
+<parameter_description> the key to look up
</parameter_description>
</parameter>
</parameters>
-<return> the value corresponding to the key, or %NULL if the key was
-not found.
+<return> the value corresponding to the key, or %NULL
+if the key was not found
</return>
</function>
<function name="g_tree_lookup_extended">
<description>
Looks up a key in the #GTree, returning the original key and the
-associated value and a #gboolean which is %TRUE if the key was found. This
-is useful if you need to free the memory allocated for the original key,
-for example before calling g_tree_remove().
+associated value. This is useful if you need to free the memory
+allocated for the original key, for example before calling
+g_tree_remove().
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="lookup_key">
-<parameter_description> the key to look up.
+<parameter_description> the key to look up
</parameter_description>
</parameter>
<parameter name="orig_key">
-<parameter_description> returns the original key.
+<parameter_description> returns the original key
</parameter_description>
</parameter>
<parameter name="value">
-<parameter_description> returns the value associated with the key.
+<parameter_description> returns the value associated with the key
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the key was found in the #GTree.
+<return> %TRUE if the key was found in the #GTree
</return>
</function>
@@ -47151,7 +46875,7 @@ after the second.
</parameter_description>
</parameter>
</parameters>
-<return> a new #GTree.
+<return> a newly allocated #GTree
</return>
</function>
@@ -47165,27 +46889,27 @@ removing the entry from the #GTree.
</description>
<parameters>
<parameter name="key_compare_func">
-<parameter_description> qsort()-style comparison function.
+<parameter_description> qsort()-style comparison function
</parameter_description>
</parameter>
<parameter name="key_compare_data">
-<parameter_description> data to pass to comparison function.
+<parameter_description> data to pass to comparison function
</parameter_description>
</parameter>
<parameter name="key_destroy_func">
<parameter_description> a function to free the memory allocated for the key
used when removing the entry from the #GTree or %NULL if you don't
-want to supply such a function.
+want to supply such a function
</parameter_description>
</parameter>
<parameter name="value_destroy_func">
<parameter_description> a function to free the memory allocated for the
value used when removing the entry from the #GTree or %NULL if you
-don't want to supply such a function.
+don't want to supply such a function
</parameter_description>
</parameter>
</parameters>
-<return> a new #GTree.
+<return> a newly allocated #GTree
</return>
</function>
@@ -47198,15 +46922,15 @@ See g_tree_new() for more details.
</description>
<parameters>
<parameter name="key_compare_func">
-<parameter_description> qsort()-style comparison function.
+<parameter_description> qsort()-style comparison function
</parameter_description>
</parameter>
<parameter name="key_compare_data">
-<parameter_description> data to pass to comparison function.
+<parameter_description> data to pass to comparison function
</parameter_description>
</parameter>
</parameters>
-<return> a new #GTree.
+<return> a newly allocated #GTree
</return>
</function>
@@ -47218,29 +46942,30 @@ Gets the number of nodes in a #GTree.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
</parameters>
-<return> the number of nodes in the #GTree.
+<return> the number of nodes in @tree
</return>
</function>
<function name="g_tree_ref">
<description>
-Increments the reference count of @tree by one. It is safe to call
-this function from any thread.
+Increments the reference count of @tree by one.
+
+It is safe to call this function from any thread.
Since: 2.22
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
</parameters>
-<return> the passed in #GTree.
+<return> the passed in #GTree
</return>
</function>
@@ -47258,22 +46983,22 @@ If the key does not exist in the #GTree, the function does nothing.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="key">
-<parameter_description> the key to remove.
+<parameter_description> the key to remove
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the key was found (prior to 2.8, this function returned
-nothing)
+<return> %TRUE if the key was found (prior to 2.8, this function
+returned nothing)
</return>
</function>
<function name="g_tree_replace">
<description>
-Inserts a new key and value into a #GTree similar to g_tree_insert().
+Inserts a new key and value into a #GTree similar to g_tree_insert().
The difference is that if the key already exists in the #GTree, it gets
replaced by the new key. If you supplied a @value_destroy_func when
creating the #GTree, the old value is freed using that function. If you
@@ -47286,15 +47011,15 @@ so that the distance from the root to every leaf is as small as possible.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="key">
-<parameter_description> the key to insert.
+<parameter_description> the key to insert
</parameter_description>
</parameter>
<parameter name="value">
-<parameter_description> the value corresponding to the key.
+<parameter_description> the value corresponding to the key
</parameter_description>
</parameter>
</parameters>
@@ -47329,8 +47054,8 @@ pairs that have a larger key.
</parameter_description>
</parameter>
</parameters>
-<return> the value corresponding to the found key, or %NULL if
-the key was not found.
+<return> the value corresponding to the found key, or %NULL
+if the key was not found
</return>
</function>
@@ -47345,16 +47070,16 @@ If the key does not exist in the #GTree, the function does nothing.
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="key">
-<parameter_description> the key to remove.
+<parameter_description> the key to remove
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if the key was found (prior to 2.8, this function returned
-nothing)
+<return> %TRUE if the key was found (prior to 2.8, this function
+returned nothing)
</return>
</function>
@@ -47362,15 +47087,15 @@ nothing)
<description>
Calls the given function for each node in the #GTree.
-Deprecated:2.2: The order of a balanced tree is somewhat arbitrary. If you
-just want to visit all nodes in sorted order, use g_tree_foreach()
-instead. If you really need to visit nodes in a different order, consider
-using an <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
+Deprecated:2.2: The order of a balanced tree is somewhat arbitrary.
+If you just want to visit all nodes in sorted order, use
+g_tree_foreach() instead. If you really need to visit nodes in
+a different order, consider using an [n-ary tree][glib-N-ary-Trees].
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
<parameter name="traverse_func">
@@ -47380,11 +47105,11 @@ function returns %TRUE, the traversal is stopped.
</parameter>
<parameter name="traverse_type">
<parameter_description> the order in which nodes are visited, one of %G_IN_ORDER,
-%G_PRE_ORDER and %G_POST_ORDER.
+%G_PRE_ORDER and %G_POST_ORDER
</parameter_description>
</parameter>
<parameter name="user_data">
-<parameter_description> user data to pass to the function.
+<parameter_description> user data to pass to the function
</parameter_description>
</parameter>
</parameters>
@@ -47393,10 +47118,10 @@ function returns %TRUE, the traversal is stopped.
<function name="g_tree_unref">
<description>
-Decrements the reference count of @tree by one. If the reference count
-drops to 0, all keys and values will be destroyed (if destroy
-functions were specified) and all memory allocated by @tree will be
-released.
+Decrements the reference count of @tree by one.
+If the reference count drops to 0, all keys and values will
+be destroyed (if destroy functions were specified) and all
+memory allocated by @tree will be released.
It is safe to call this function from any thread.
@@ -47405,7 +47130,7 @@ Since: 2.22
</description>
<parameters>
<parameter name="tree">
-<parameter_description> a #GTree.
+<parameter_description> a #GTree
</parameter_description>
</parameter>
</parameters>
@@ -47704,11 +47429,11 @@ Since: 2.24
</description>
<parameters>
<parameter name="class_type">
-<parameter_description> GType of an classed type.
+<parameter_description> GType of an classed type
</parameter_description>
</parameter>
<parameter name="private_size">
-<parameter_description> size of private structure.
+<parameter_description> size of private structure
</parameter_description>
</parameter>
</parameters>
@@ -47718,11 +47443,11 @@ Since: 2.24
<function name="g_type_add_interface_check">
<description>
Adds a function to be called after an interface vtable is
-initialized for any class (i.e. after the @interface_init member of
-#GInterfaceInfo has been called).
+initialized for any class (i.e. after the @interface_init
+member of #GInterfaceInfo has been called).
-This function is useful when you want to check an invariant that
-depends on the interfaces of a class. For instance, the
+This function is useful when you want to check an invariant
+that depends on the interfaces of a class. For instance, the
implementation of #GObject uses this facility to check that an
object implements all of the properties that are defined on its
interfaces.
@@ -47737,7 +47462,7 @@ Since: 2.4
</parameter>
<parameter name="check_func">
<parameter_description> function to be called after each interface
-is initialized.
+is initialized
</parameter_description>
</parameter>
</parameters>
@@ -47753,15 +47478,15 @@ is used to manage the relationship.
</description>
<parameters>
<parameter name="instance_type">
-<parameter_description> the #GType value of an instantiable type.
+<parameter_description> #GType value of an instantiable type
</parameter_description>
</parameter>
<parameter name="interface_type">
-<parameter_description> the #GType value of an interface type.
+<parameter_description> #GType value of an interface type
</parameter_description>
</parameter>
<parameter name="plugin">
-<parameter_description> the #GTypePlugin structure to retrieve the #GInterfaceInfo from.
+<parameter_description> #GTypePlugin structure to retrieve the #GInterfaceInfo from
</parameter_description>
</parameter>
</parameters>
@@ -47770,23 +47495,23 @@ is used to manage the relationship.
<function name="g_type_add_interface_static">
<description>
-Adds the static @interface_type to @instantiable_type. The
-information contained in the #GInterfaceInfo structure pointed to by
- info is used to manage the relationship.
+Adds the static @interface_type to @instantiable_type.
+The information contained in the #GInterfaceInfo structure
+pointed to by @info is used to manage the relationship.
</description>
<parameters>
<parameter name="instance_type">
-<parameter_description> #GType value of an instantiable type.
+<parameter_description> #GType value of an instantiable type
</parameter_description>
</parameter>
<parameter name="interface_type">
-<parameter_description> #GType value of an interface type.
+<parameter_description> #GType value of an interface type
</parameter_description>
</parameter>
<parameter name="info">
-<parameter_description> The #GInterfaceInfo structure for this
-(@instance_type, @interface_type) combination.
+<parameter_description> #GInterfaceInfo structure for this
+(@instance_type, @interface_type) combination
</parameter_description>
</parameter>
</parameters>
@@ -47795,41 +47520,41 @@ information contained in the #GInterfaceInfo structure pointed to by
<function name="g_type_check_instance">
<description>
-Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE()
-macro.
+Private helper function to aid implementation of the
+G_TYPE_CHECK_INSTANCE() macro.
</description>
<parameters>
<parameter name="instance">
-<parameter_description> A valid #GTypeInstance structure.
+<parameter_description> a valid #GTypeInstance structure
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if @instance is valid, %FALSE otherwise.
+<return> %TRUE if @instance is valid, %FALSE otherwise
</return>
</function>
<function name="g_type_children">
<description>
-Return a newly allocated and 0-terminated array of type IDs, listing the
-child types of @type. The return value has to be g_free()ed after use.
+Return a newly allocated and 0-terminated array of type IDs, listing
+the child types of @type.
</description>
<parameters>
<parameter name="type">
-<parameter_description> The parent type.
+<parameter_description> the parent type
</parameter_description>
</parameter>
<parameter name="n_children">
-<parameter_description> Optional #guint pointer to contain
-the number of child types.
+<parameter_description> location to store the length of
+the returned array, or %NULL
</parameter_description>
</parameter>
</parameters>
<return> Newly allocated
-and 0-terminated array of child types.
+and 0-terminated array of child types, free with g_free()
</return>
</function>
@@ -47850,14 +47575,13 @@ The private structure can be retrieved using the
G_TYPE_INSTANCE_GET_PRIVATE() macro.
The following example shows attaching a private structure
-<structname>MyObjectPrivate</structname> to an object
-<structname>MyObject</structname> defined in the standard GObject
-fashion.
-type's class_init() function.
+MyObjectPrivate to an object MyObject defined in the standard
+GObject fashion in the type's class_init() function.
+
Note the use of a structure member "priv" to avoid the overhead
of repeatedly calling MY_OBJECT_GET_PRIVATE().
-|[
+|[<!-- language="C" -->
typedef struct _MyObject MyObject;
typedef struct _MyObjectPrivate MyObjectPrivate;
@@ -47907,7 +47631,7 @@ Since: 2.4
</parameter_description>
</parameter>
<parameter name="private_size">
-<parameter_description> size of private structure.
+<parameter_description> size of private structure
</parameter_description>
</parameter>
</parameters>
@@ -47941,22 +47665,23 @@ Since: 2.38
<function name="g_type_class_peek">
<description>
-This function is essentially the same as g_type_class_ref(), except that
-the classes reference count isn't incremented. As a consequence, this function
-may return %NULL if the class of the type passed in does not currently
-exist (hasn't been referenced before).
+This function is essentially the same as g_type_class_ref(),
+except that the classes reference count isn't incremented.
+As a consequence, this function may return %NULL if the class
+of the type passed in does not currently exist (hasn't been
+referenced before).
</description>
<parameters>
<parameter name="type">
-<parameter_description> Type ID of a classed type.
+<parameter_description> type ID of a classed type
</parameter_description>
</parameter>
</parameters>
-<return> The #GTypeClass
+<return> the #GTypeClass
structure for the given type ID or %NULL if the class does not
-currently exist.
+currently exist
</return>
</function>
@@ -47966,24 +47691,22 @@ This is a convenience function often needed in class initializers.
It returns the class structure of the immediate parent type of the
class passed in. Since derived classes hold a reference count on
their parent classes as long as they are instantiated, the returned
-class will always exist. This function is essentially equivalent
-to:
+class will always exist.
-<programlisting>
-g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
-</programlisting>
+This function is essentially equivalent to:
+g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)))
</description>
<parameters>
<parameter name="g_class">
-<parameter_description> The #GTypeClass structure to
-retrieve the parent class for.
+<parameter_description> the #GTypeClass structure to
+retrieve the parent class for
</parameter_description>
</parameter>
</parameters>
-<return> The parent class
-of @g_class.
+<return> the parent class
+of @g_class
</return>
</function>
@@ -47997,13 +47720,14 @@ Since: 2.4
</description>
<parameters>
<parameter name="type">
-<parameter_description> Type ID of a classed type.
+<parameter_description> type ID of a classed type
</parameter_description>
</parameter>
</parameters>
-<return> The #GTypeClass
+<return> the #GTypeClass
structure for the given type ID or %NULL if the class does not
-currently exist or is dynamically loaded.
+currently exist or is dynamically loaded
+
</return>
</function>
@@ -48017,12 +47741,12 @@ exist already.
</description>
<parameters>
<parameter name="type">
-<parameter_description> Type ID of a classed type.
+<parameter_description> type ID of a classed type
</parameter_description>
</parameter>
</parameters>
-<return> The #GTypeClass
-structure for the given type ID.
+<return> the #GTypeClass
+structure for the given type ID
</return>
</function>
@@ -48036,8 +47760,7 @@ class pointer after g_type_class_unref() are invalid.
</description>
<parameters>
<parameter name="g_class">
-<parameter_description> The #GTypeClass structure to
-unreference.
+<parameter_description> a #GTypeClass structure to unref
</parameter_description>
</parameter>
</parameters>
@@ -48048,14 +47771,13 @@ unreference.
<description>
A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
implementations. It unreferences a class without consulting the chain
-of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur
+of #GTypeClassCacheFuncs, avoiding the recursion which would occur
otherwise.
</description>
<parameters>
<parameter name="g_class">
-<parameter_description> The #GTypeClass structure to
-unreference.
+<parameter_description> a #GTypeClass structure to unref
</parameter_description>
</parameter>
</parameters>
@@ -48070,24 +47792,24 @@ and structure setups for instances: actual instance creation should
happen through functions supplied by the type's fundamental type
implementation. So use of g_type_create_instance() is reserved for
implementators of fundamental types only. E.g. instances of the
-#GObject hierarchy should be created via g_object_new() and
-<emphasis>never</emphasis> directly through
-g_type_create_instance() which doesn't handle things like singleton
-objects or object construction. Note: Do <emphasis>not</emphasis>
-use this function, unless you're implementing a fundamental
-type. Also language bindings should <emphasis>not</emphasis> use
-this function but g_object_new() instead.
+#GObject hierarchy should be created via g_object_new() and never
+directly through g_type_create_instance() which doesn't handle things
+like singleton objects or object construction.
+
+Note: Do not use this function, unless you're implementing a
+fundamental type. Also language bindings should not use this
+function, but g_object_new() instead.
</description>
<parameters>
<parameter name="type">
-<parameter_description> An instantiatable type to create an instance for.
+<parameter_description> an instantiatable type to create an instance for
</parameter_description>
</parameter>
</parameters>
-<return> An allocated and initialized instance, subject to further
-treatment by the fundamental type implementation.
+<return> an allocated and initialized instance, subject to further
+treatment by the fundamental type implementation
</return>
</function>
@@ -48107,8 +47829,8 @@ Since: 2.4
</parameter>
</parameters>
<return> the default
-vtable for the interface, or %NULL if the type is not currently in
-use.
+vtable for the interface, or %NULL if the type is not currently
+in use
</return>
</function>
@@ -48120,8 +47842,7 @@ and returns the default interface vtable for the type.
If the type is not currently in use, then the default vtable
for the type will be created and initalized by calling
the base interface init and default vtable init functions for
-the type (the @<structfield>base_init</structfield>
-and <structfield>class_init</structfield> members of #GTypeInfo).
+the type (the @base_init and @class_init members of #GTypeInfo).
Calling g_type_default_interface_ref() is useful when you
want to make sure that signals and properties for an interface
have been installed.
@@ -48148,8 +47869,7 @@ Decrements the reference count for the type corresponding to the
interface default vtable @g_iface. If the type is dynamic, then
when no one is using the interface and all references have
been released, the finalize function for the interface's default
-vtable (the <structfield>class_finalize</structfield> member of
-#GTypeInfo) will be called.
+vtable (the @class_finalize member of #GTypeInfo) will be called.
Since: 2.4
@@ -48157,8 +47877,7 @@ Since: 2.4
<parameters>
<parameter name="g_iface">
<parameter_description> the default vtable
-structure for a interface, as returned by
-g_type_default_interface_ref()
+structure for a interface, as returned by g_type_default_interface_ref()
</parameter_description>
</parameter>
</parameters>
@@ -48174,11 +47893,11 @@ includes the type itself, so that e.g. a fundamental type has depth 1.
</description>
<parameters>
<parameter name="type">
-<parameter_description> A #GType value.
+<parameter_description> a #GType
</parameter_description>
</parameter>
</parameters>
-<return> The depth of @type.
+<return> the depth of @type
</return>
</function>
@@ -48202,7 +47921,7 @@ Since: 2.34
</description>
<parameters>
<parameter name="type">
-<parameter_description> a #GType.
+<parameter_description> a #GType
</parameter_description>
</parameter>
</parameters>
@@ -48220,7 +47939,7 @@ implementors of fundamental types.
</description>
<parameters>
<parameter name="instance">
-<parameter_description> an instance of a type.
+<parameter_description> an instance of a type
</parameter_description>
</parameter>
</parameters>
@@ -48238,18 +47957,18 @@ yet).
</description>
<parameters>
<parameter name="name">
-<parameter_description> Type name to lookup.
+<parameter_description> type name to lookup
</parameter_description>
</parameter>
</parameters>
-<return> Corresponding type ID or 0.
+<return> corresponding type ID or 0
</return>
</function>
<function name="g_type_fundamental">
<description>
Internal function, used to extract the fundamental type ID portion.
-use G_TYPE_FUNDAMENTAL() instead.
+Use G_TYPE_FUNDAMENTAL() instead.
</description>
@@ -48274,26 +47993,25 @@ fundamental type identifier.
</description>
<parameters>
</parameters>
-<return> The nextmost fundamental type ID to be registered,
-or 0 if the type system ran out of fundamental type IDs.
+<return> the next available fundamental type ID to be registered,
+or 0 if the type system ran out of fundamental type IDs
</return>
</function>
<function name="g_type_get_plugin">
<description>
-Returns the #GTypePlugin structure for @type or
-%NULL if @type does not have a #GTypePlugin structure.
+Returns the #GTypePlugin structure for @type.
</description>
<parameters>
<parameter name="type">
-<parameter_description> The #GType to retrieve the plugin for.
+<parameter_description> #GType to retrieve the plugin for
</parameter_description>
</parameter>
</parameters>
-<return> The corresponding plugin if @type is a
-dynamic type, %NULL otherwise.
+<return> the corresponding plugin
+if @type is a dynamic type, %NULL otherwise
</return>
</function>
@@ -48324,8 +48042,8 @@ be retrieved from a subtype using g_type_get_qdata().
<function name="g_type_get_type_registration_serial">
<description>
-Returns an opaque serial number that represents the state of the set of
-registered types. Any time a type is registered this serial changes,
+Returns an opaque serial number that represents the state of the set
+of registered types. Any time a type is registered this serial changes,
which means you can cache information based on type lookups (such as
g_type_from_name()) and know if the cache is still valid at a later
time by comparing the current serial with the one at the type lookup.
@@ -48336,7 +48054,7 @@ Since: 2.36
</description>
<parameters>
</parameters>
-<return> An unsigned int, representing the state of type registrations.
+<return> An unsigned int, representing the state of type registrations
</return>
</function>
@@ -48368,8 +48086,8 @@ Deprecated: 2.36: the type system is now initialised automatically
</description>
<parameters>
<parameter name="debug_flags">
-<parameter_description> Bitwise combination of #GTypeDebugFlags values for
-debugging purposes.
+<parameter_description> bitwise combination of #GTypeDebugFlags values for
+debugging purposes
</parameter_description>
</parameter>
</parameters>
@@ -48387,11 +48105,11 @@ at most one instantiatable prerequisite type.
</description>
<parameters>
<parameter name="interface_type">
-<parameter_description> #GType value of an interface type.
+<parameter_description> #GType value of an interface type
</parameter_description>
</parameter>
<parameter name="prerequisite_type">
-<parameter_description> #GType value of an interface or instantiatable type.
+<parameter_description> #GType value of an interface or instantiatable type
</parameter_description>
</parameter>
</parameters>
@@ -48401,24 +48119,24 @@ at most one instantiatable prerequisite type.
<function name="g_type_interface_get_plugin">
<description>
Returns the #GTypePlugin structure for the dynamic interface
- interface_type which has been added to @instance_type, or %NULL if
- interface_type has not been added to @instance_type or does not
-have a #GTypePlugin structure. See g_type_add_interface_dynamic().
+ interface_type which has been added to @instance_type, or %NULL
+if @interface_type has not been added to @instance_type or does
+not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
</description>
<parameters>
<parameter name="instance_type">
-<parameter_description> the #GType value of an instantiatable type.
+<parameter_description> #GType of an instantiatable type
</parameter_description>
</parameter>
<parameter name="interface_type">
-<parameter_description> the #GType value of an interface type.
+<parameter_description> #GType of an interface type
</parameter_description>
</parameter>
</parameters>
<return> the #GTypePlugin for the dynamic
-interface @interface_type of @instance_type.
+interface @interface_type of @instance_type
</return>
</function>
@@ -48431,16 +48149,16 @@ passed in class conforms.
</description>
<parameters>
<parameter name="instance_class">
-<parameter_description> A #GTypeClass structure.
+<parameter_description> a #GTypeClass structure
</parameter_description>
</parameter>
<parameter name="iface_type">
-<parameter_description> An interface ID which this class conforms to.
+<parameter_description> an interface ID which this class conforms to
</parameter_description>
</parameter>
</parameters>
-<return> The GTypeInterface
-structure of iface_type if implemented by @instance_class, %NULL
+<return> the #GTypeInterface
+structure of @iface_type if implemented by @instance_class, %NULL
otherwise
</return>
</function>
@@ -48456,14 +48174,14 @@ then possibly overriding some methods.
</description>
<parameters>
<parameter name="g_iface">
-<parameter_description> A #GTypeInterface structure.
+<parameter_description> a #GTypeInterface structure
</parameter_description>
</parameter>
</parameters>
-<return> The
+<return> the
corresponding #GTypeInterface structure of the parent type of the
instance type to which @g_iface belongs, or %NULL if the parent
-type doesn't conform to the interface.
+type doesn't conform to the interface
</return>
</function>
@@ -48494,47 +48212,47 @@ the prerequisites of @interface_type
<function name="g_type_interfaces">
<description>
-Return a newly allocated and 0-terminated array of type IDs, listing the
-interface types that @type conforms to. The return value has to be
-g_free()ed after use.
+Return a newly allocated and 0-terminated array of type IDs, listing
+the interface types that @type conforms to.
</description>
<parameters>
<parameter name="type">
-<parameter_description> The type to list interface types for.
+<parameter_description> the type to list interface types for
</parameter_description>
</parameter>
<parameter name="n_interfaces">
-<parameter_description> Optional #guint pointer to
-contain the number of interface types.
+<parameter_description> location to store the length of
+the returned array, or %NULL
</parameter_description>
</parameter>
</parameters>
-<return> Newly
-allocated and 0-terminated array of interface types.
+<return> Newly allocated
+and 0-terminated array of interface types, free with g_free()
</return>
</function>
<function name="g_type_is_a">
<description>
If @is_a_type is a derivable type, check whether @type is a
-descendant of @is_a_type. If @is_a_type is an interface, check
+descendant of @is_a_type. If @is_a_type is an interface, check
whether @type conforms to it.
</description>
<parameters>
<parameter name="type">
-<parameter_description> Type to check anchestry for.
+<parameter_description> type to check anchestry for
</parameter_description>
</parameter>
<parameter name="is_a_type">
-<parameter_description> Possible anchestor of @type or interface @type could conform to.
+<parameter_description> possible anchestor of @type or interface that @type
+could conform to
</parameter_description>
</parameter>
</parameters>
-<return> %TRUE if @type is_a @is_a_type holds true.
+<return> %TRUE if @type is a @is_a_type
</return>
</function>
@@ -48749,11 +48467,11 @@ not be passed in and will most likely lead to a crash.
</description>
<parameters>
<parameter name="type">
-<parameter_description> Type to return name for.
+<parameter_description> type to return name for
</parameter_description>
</parameter>
</parameters>
-<return> Static type name or %NULL.
+<return> static type name or %NULL
</return>
</function>
@@ -48761,7 +48479,7 @@ not be passed in and will most likely lead to a crash.
<description>
Given a @leaf_type and a @root_type which is contained in its
anchestry, return the type that @root_type is the immediate parent
-of. In other words, this function determines the type that is
+of. In other words, this function determines the type that is
derived directly from @root_type which is also a base class of
@leaf_type. Given a root type and a leaf type, this function can
be used to determine the types and order in which the leaf type is
@@ -48771,32 +48489,32 @@ descended from the root type.
</description>
<parameters>
<parameter name="leaf_type">
-<parameter_description> Descendant of @root_type and the type to be returned.
+<parameter_description> descendant of @root_type and the type to be returned
</parameter_description>
</parameter>
<parameter name="root_type">
-<parameter_description> Immediate parent of the returned type.
+<parameter_description> immediate parent of the returned type
</parameter_description>
</parameter>
</parameters>
-<return> Immediate child of @root_type and anchestor of @leaf_type.
+<return> immediate child of @root_type and anchestor of @leaf_type
</return>
</function>
<function name="g_type_parent">
<description>
-Return the direct parent type of the passed in type. If the passed
+Return the direct parent type of the passed in type. If the passed
in type has no parent, i.e. is a fundamental type, 0 is returned.
</description>
<parameters>
<parameter name="type">
-<parameter_description> The derived type.
+<parameter_description> the derived type
</parameter_description>
</parameter>
</parameters>
-<return> The parent type.
+<return> the parent type
</return>
</function>
@@ -48897,11 +48615,11 @@ Get the corresponding quark of the type IDs name.
</description>
<parameters>
<parameter name="type">
-<parameter_description> Type to return quark of type name for.
+<parameter_description> type to return quark of type name for
</parameter_description>
</parameter>
</parameters>
-<return> The type names quark or 0.
+<return> the type names quark or 0
</return>
</function>
@@ -48917,12 +48635,12 @@ left untouched.
</description>
<parameters>
<parameter name="type">
-<parameter_description> the #GType value of a static, classed type.
+<parameter_description> #GType of a static, classed type
</parameter_description>
</parameter>
<parameter name="query">
-<parameter_description> A user provided structure that is
-filled in with constant values upon success.
+<parameter_description> a user provided structure that is
+filled in with constant values upon success
</parameter_description>
</parameter>
</parameters>
@@ -48941,93 +48659,93 @@ instances (if not abstract). The value of @flags determines the nature
</description>
<parameters>
<parameter name="parent_type">
-<parameter_description> Type from which this type will be derived.
+<parameter_description> type from which this type will be derived
</parameter_description>
</parameter>
<parameter name="type_name">
-<parameter_description> 0-terminated string used as the name of the new type.
+<parameter_description> 0-terminated string used as the name of the new type
</parameter_description>
</parameter>
<parameter name="plugin">
-<parameter_description> The #GTypePlugin structure to retrieve the #GTypeInfo from.
+<parameter_description> #GTypePlugin structure to retrieve the #GTypeInfo from
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Bitwise combination of #GTypeFlags values.
+<parameter_description> bitwise combination of #GTypeFlags values
</parameter_description>
</parameter>
</parameters>
-<return> The new type identifier or #G_TYPE_INVALID if registration failed.
+<return> the new type identifier or #G_TYPE_INVALID if registration failed
</return>
</function>
<function name="g_type_register_fundamental">
<description>
Registers @type_id as the predefined identifier and @type_name as the
-name of a fundamental type. If @type_id is already registered, or a type
-named @type_name is already registered, the behaviour is undefined. The type
-system uses the information contained in the #GTypeInfo structure pointed to
-by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to
-manage the type and its instances. The value of @flags determines additional
-characteristics of the fundamental type.
+name of a fundamental type. If @type_id is already registered, or a
+type named @type_name is already registered, the behaviour is undefined.
+The type system uses the information contained in the #GTypeInfo structure
+pointed to by @info and the #GTypeFundamentalInfo structure pointed to by
+ finfo to manage the type and its instances. The value of @flags determines
+additional characteristics of the fundamental type.
</description>
<parameters>
<parameter name="type_id">
-<parameter_description> A predefined type identifier.
+<parameter_description> a predefined type identifier
</parameter_description>
</parameter>
<parameter name="type_name">
-<parameter_description> 0-terminated string used as the name of the new type.
+<parameter_description> 0-terminated string used as the name of the new type
</parameter_description>
</parameter>
<parameter name="info">
-<parameter_description> The #GTypeInfo structure for this type.
+<parameter_description> #GTypeInfo structure for this type
</parameter_description>
</parameter>
<parameter name="finfo">
-<parameter_description> The #GTypeFundamentalInfo structure for this type.
+<parameter_description> #GTypeFundamentalInfo structure for this type
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Bitwise combination of #GTypeFlags values.
+<parameter_description> bitwise combination of #GTypeFlags values
</parameter_description>
</parameter>
</parameters>
-<return> The predefined type identifier.
+<return> the predefined type identifier
</return>
</function>
<function name="g_type_register_static">
<description>
Registers @type_name as the name of a new static type derived from
- parent_type The type system uses the information contained in the
+ parent_type The type system uses the information contained in the
#GTypeInfo structure pointed to by @info to manage the type and its
-instances (if not abstract). The value of @flags determines the nature
+instances (if not abstract). The value of @flags determines the nature
(e.g. abstract or not) of the type.
</description>
<parameters>
<parameter name="parent_type">
-<parameter_description> Type from which this type will be derived.
+<parameter_description> type from which this type will be derived
</parameter_description>
</parameter>
<parameter name="type_name">
-<parameter_description> 0-terminated string used as the name of the new type.
+<parameter_description> 0-terminated string used as the name of the new type
</parameter_description>
</parameter>
<parameter name="info">
-<parameter_description> The #GTypeInfo structure for this type.
+<parameter_description> #GTypeInfo structure for this type
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Bitwise combination of #GTypeFlags values.
+<parameter_description> bitwise combination of #GTypeFlags values
</parameter_description>
</parameter>
</parameters>
-<return> The new type identifier.
+<return> the new type identifier
</return>
</function>
@@ -49044,35 +48762,35 @@ Since: 2.12
</description>
<parameters>
<parameter name="parent_type">
-<parameter_description> Type from which this type will be derived.
+<parameter_description> type from which this type will be derived
</parameter_description>
</parameter>
<parameter name="type_name">
-<parameter_description> 0-terminated string used as the name of the new type.
+<parameter_description> 0-terminated string used as the name of the new type
</parameter_description>
</parameter>
<parameter name="class_size">
-<parameter_description> Size of the class structure (see #GTypeInfo)
+<parameter_description> size of the class structure (see #GTypeInfo)
</parameter_description>
</parameter>
<parameter name="class_init">
-<parameter_description> Location of the class initialization function (see #GTypeInfo)
+<parameter_description> location of the class initialization function (see #GTypeInfo)
</parameter_description>
</parameter>
<parameter name="instance_size">
-<parameter_description> Size of the instance structure (see #GTypeInfo)
+<parameter_description> size of the instance structure (see #GTypeInfo)
</parameter_description>
</parameter>
<parameter name="instance_init">
-<parameter_description> Location of the instance initialization function (see #GTypeInfo)
+<parameter_description> location of the instance initialization function (see #GTypeInfo)
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Bitwise combination of #GTypeFlags values.
+<parameter_description> bitwise combination of #GTypeFlags values
</parameter_description>
</parameter>
</parameters>
-<return> The new type identifier.
+<return> the new type identifier
</return>
</function>
@@ -49142,20 +48860,21 @@ Attaches arbitrary data to a type.
<function name="g_type_value_table_peek">
<description>
Returns the location of the #GTypeValueTable associated with @type.
-<emphasis>Note that this function should only be used from source code
+
+Note that this function should only be used from source code
that implements or has internal knowledge of the implementation of
- type </emphasis>
+ type
</description>
<parameters>
<parameter name="type">
-<parameter_description> A #GType value.
+<parameter_description> a #GType
</parameter_description>
</parameter>
</parameters>
-<return> Location of the #GTypeValueTable associated with @type or
-%NULL if there is no #GTypeValueTable associated with @type.
+<return> location of the #GTypeValueTable associated with @type or
+%NULL if there is no #GTypeValueTable associated with @type
</return>
</function>
@@ -49177,15 +48896,15 @@ If @len < 0, then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
-<parameter_description> location to store number of bytes read, or %NULL.
-If an error occurs then the index of the invalid input
+<parameter_description> location to store number of bytes read,
+or %NULL. If an error occurs then the index of the invalid input
is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store number of <type>gunichar2</type>
-written, or %NULL. The value stored here does not
-include the trailing 0.
+<parameter_description> location to store number of #gunichar2
+written, or %NULL. The value stored here does not include the
+trailing 0.
</parameter_description>
</parameter>
<parameter name="error">
@@ -49196,9 +48915,8 @@ errors. Any of the errors in #GConvertError other than
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-16 string.
-This value must be freed with g_free(). If an
-error occurs, %NULL will be returned and
- error set.
+This value must be freed with g_free(). If an error occurs,
+%NULL will be returned and @error set.
</return>
</function>
@@ -49220,13 +48938,14 @@ If @len < 0, then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
-<parameter_description> location to store number of characters read, or %NULL.
+<parameter_description> location to store number of characters
+read, or %NULL.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store number of bytes written or %NULL.
-The value here stored does not include the trailing 0
-byte.
+<parameter_description> location to store number of bytes
+written or %NULL. The value here stored does not include the
+trailing 0 byte.
</parameter_description>
</parameter>
<parameter name="error">
@@ -49237,11 +48956,9 @@ errors. Any of the errors in #GConvertError other than
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-8 string.
-This value must be freed with g_free(). If an
-error occurs, %NULL will be returned and
- error set. In that case, @items_read will be
-set to the position of the first invalid input
-character.
+This value must be freed with g_free(). If an error occurs,
+%NULL will be returned and @error set. In that case, @items_read
+will be set to the position of the first invalid input character.
</return>
</function>
@@ -49299,7 +49016,8 @@ Standard for the definition of Primary Composite.
If @a and @b do not compose a new character, @ch is set to zero.
-See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
+See
+[UAX#15](http://unicode.org/reports/tr15/)
for details.
Since: 2.30
@@ -49346,7 +49064,8 @@ canonical decomposition for @ch, one would need to
recursively call this function on @a. Or use
g_unichar_fully_decompose().
-See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
+See
+[UAX#15](http://unicode.org/reports/tr15/)
for details.
Since: 2.30
@@ -49407,7 +49126,8 @@ At any rate, Unicode does guarantee that a buffer of length
decompositions, so that is the size recommended. This is provided
as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
-See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
+See
+[UAX#15](http://unicode.org/reports/tr15/)
for details.
Since: 2.30
@@ -49438,10 +49158,10 @@ Since: 2.30
<function name="g_unichar_get_mirror_char">
<description>
-In Unicode, some characters are <firstterm>mirrored</firstterm>. This
-means that their images are mirrored horizontally in text that is laid
-out from right to left. For instance, "(" would become its mirror image,
-")", in right-to-left text.
+In Unicode, some characters are "mirrored". This means that their
+images are mirrored horizontally in text that is laid out from right
+to left. For instance, "(" would become its mirror image, ")", in
+right-to-left text.
If @ch has the Unicode mirrored property and there is another unicode
character that typically has a glyph that is the mirror image of @ch's
@@ -49761,9 +49481,9 @@ cell.
Determines if a character is typically rendered in a double-width
cell under legacy East Asian locales. If a character is wide according to
g_unichar_iswide(), then it is also reported wide with this function, but
-the converse is not necessarily true. See the
-<ulink url="http://www.unicode.org/reports/tr11/">Unicode Standard
-Annex #11</ulink> for details.
+the converse is not necessarily true. See the
+[Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
+for details.
If a character passes the g_unichar_iswide() test then it will also pass
this test, but not the other way around. Note that some characters may
@@ -50006,8 +49726,9 @@ This function accepts four letter codes encoded as a @guint32 in a
big-endian fashion. That is, the code expected for Arabic is
0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
-See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the
-representation of names of scripts</ulink> for details.
+See
+[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
+for details.
Since: 2.30
@@ -50033,8 +49754,9 @@ four letter codes are encoded as a @guint32 by this function in a
big-endian fashion. That is, the code returned for Arabic is
0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
-See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the
-representation of names of scripts</ulink> for details.
+See
+[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
+for details.
Since: 2.30
@@ -50166,14 +49888,12 @@ Since: 2.36
<description>
Similar to the UNIX pipe() call, but on modern systems like Linux
uses the pipe2() system call, which atomically creates a pipe with
-the configured flags. The only supported flag currently is
-<literal>FD_CLOEXEC</literal>. If for example you want to configure
-<literal>O_NONBLOCK</literal>, that must still be done separately with
-fcntl().
+the configured flags. The only supported flag currently is
+%FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
+must still be done separately with fcntl().
-<note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
-<literal>FD_CLOEXEC</literal> as if for fcntl(); these are
-different on Linux/glibc.</note>
+This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
+for fcntl(); these are different on Linux/glibc.
Since: 2.30
@@ -50184,7 +49904,7 @@ Since: 2.30
</parameter_description>
</parameter>
<parameter name="flags">
-<parameter_description> Bitfield of file descriptor flags, see "man 2 fcntl"
+<parameter_description> Bitfield of file descriptor flags, as for fcntl()
</parameter_description>
</parameter>
<parameter name="error">
@@ -50200,8 +49920,8 @@ Since: 2.30
<function name="g_unix_set_fd_nonblocking">
<description>
Control the non-blocking state of the given file descriptor,
-according to @nonblock. On most systems this uses <literal>O_NONBLOCK</literal>, but
-on some older ones may use <literal>O_NDELAY</literal>.
+according to @nonblock. On most systems this uses %O_NONBLOCK, but
+on some older ones may use %O_NDELAY.
Since: 2.30
@@ -50293,17 +50013,15 @@ the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
<function name="g_unix_signal_source_new">
<description>
Create a #GSource that will be dispatched upon delivery of the UNIX
-signal @signum. In GLib versions before 2.36, only
-<literal>SIGHUP</literal>, <literal>SIGINT</literal>,
-<literal>SIGTERM</literal> can be monitored. In GLib 2.36,
-<literal>SIGUSR1</literal> and <literal>SIGUSR2</literal> were
-added.
+signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
+`SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2`
+were added.
Note that unlike the UNIX default, all sources which have created a
watch will be dispatched, regardless of which underlying thread
invoked g_unix_signal_source_new().
-For example, an effective use of this function is to handle <literal>SIGTERM</literal>
+For example, an effective use of this function is to handle `SIGTERM`
cleanly; flushing any outstanding files, and then calling
g_main_loop_quit (). It is not safe to do any of this a regular
UNIX signal handler; your handler may be invoked while malloc() or
@@ -50365,20 +50083,18 @@ Removes an environment variable from the environment.
Note that on some systems, when variables are overwritten, the
memory used for the previous variables and its value isn't reclaimed.
-<warning><para>
-Environment variable handling in UNIX is not thread-safe, and your
-program may crash if one thread calls g_unsetenv() while another
-thread is calling getenv(). (And note that many functions, such as
-gettext(), call getenv() internally.) This function is only safe
-to use at the very start of your program, before creating any other
-threads (or creating objects that create worker threads of their
-own).
-</para><para>
+You should be mindful of the fact that environment variable handling
+in UNIX is not thread-safe, and your program may crash if one thread
+calls g_unsetenv() while another thread is calling getenv(). (And note
+that many functions, such as gettext(), call getenv() internally.) This
+function is only safe to use at the very start of your program, before
+creating any other threads (or creating objects that create worker
+threads of their own).
+
If you need to set up the environment for a child process, you can
use g_get_environ() to get an environment array, modify that with
g_environ_setenv() and g_environ_unsetenv(), and then pass that
array directly to execvpe(), g_spawn_async(), or the like.
-</para></warning>
Since: 2.4
@@ -50452,9 +50168,9 @@ with g_strfreev().
<function name="g_uri_parse_scheme">
<description>
Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
-<programlisting>
+|[
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
-</programlisting>
+]|
Common schemes include "file", "http", "svn+ssh", etc.
Since: 2.16
@@ -50569,21 +50285,20 @@ nul-terminated.
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the maximum length (number of <type>gunichar2</type>) of @str to use.
+<parameter_description> the maximum length (number of #gunichar2) of @str to use.
If @len < 0, then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
-<parameter_description> location to store number of words read, or %NULL.
-If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
-returned in case @str contains a trailing partial
-character. If an error occurs then the index of the
-invalid input is stored here.
+<parameter_description> location to store number of words read,
+or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+returned in case @str contains a trailing partial character. If
+an error occurs then the index of the invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store number of characters written, or %NULL.
-The value stored here does not include the trailing
+<parameter_description> location to store number of characters
+written, or %NULL. The value stored here does not include the trailing
0 character.
</parameter_description>
</parameter>
@@ -50595,9 +50310,8 @@ errors. Any of the errors in #GConvertError other than
</parameter>
</parameters>
<return> a pointer to a newly allocated UCS-4 string.
-This value must be freed with g_free(). If an
-error occurs, %NULL will be returned and
- error set.
+This value must be freed with g_free(). If an error occurs,
+%NULL will be returned and @error set.
</return>
</function>
@@ -50625,22 +50339,20 @@ things unpaired surrogates.
</parameter_description>
</parameter>
<parameter name="len">
-<parameter_description> the maximum length (number of <type>gunichar2</type>) of @str to use.
+<parameter_description> the maximum length (number of #gunichar2) of @str to use.
If @len < 0, then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
-<parameter_description> location to store number of words read, or %NULL.
-If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
-returned in case @str contains a trailing partial
-character. If an error occurs then the index of the
-invalid input is stored here.
+<parameter_description> location to store number of words read,
+or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+returned in case @str contains a trailing partial character. If
+an error occurs then the index of the invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store number of bytes written, or %NULL.
-The value stored here does not include the trailing
-0 byte.
+<parameter_description> location to store number of bytes written,
+or %NULL. The value stored here does not include the trailing 0 byte.
</parameter_description>
</parameter>
<parameter name="error">
@@ -50651,9 +50363,8 @@ errors. Any of the errors in #GConvertError other than
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-8 string.
-This value must be freed with g_free(). If an
-error occurs, %NULL will be returned and
- error set.
+This value must be freed with g_free(). If an error occurs,
+%NULL will be returned and @error set.
</return>
</function>
@@ -50691,7 +50402,7 @@ case independent form of @str.
<function name="g_utf8_collate">
<description>
Compares two strings for ordering using the linguistically
-correct rules for the <link linkend="setlocale">current locale</link>.
+correct rules for the [current locale][setlocale].
When sorting a large number of strings, it will be significantly
faster to obtain collation keys with g_utf8_collate_key() and
compare the keys with strcmp() when sorting instead of sorting
@@ -50724,8 +50435,7 @@ The results of comparing the collation keys of two strings
with strcmp() will always be the same as comparing the two
original keys with g_utf8_collate().
-Note that this function depends on the
-<link linkend="setlocale">current locale</link>.
+Note that this function depends on the [current locale][setlocale].
</description>
@@ -50756,8 +50466,7 @@ insignificant, thus producing the ordering "event.c" "eventgenera
would like to treat numbers intelligently so that "file1" "file10" "file5"
is sorted as "file1" "file5" "file10".
-Note that this function depends on the
-<link linkend="setlocale">current locale</link>.
+Note that this function depends on the [current locale][setlocale].
Since: 2.8
@@ -50795,7 +50504,7 @@ it starts with an appropriate byte.
</parameter>
<parameter name="end">
<parameter_description> a pointer to the byte following the end of the string,
-or %NULL to indicate that the string is nul-terminated.
+or %NULL to indicate that the string is nul-terminated
</parameter_description>
</parameter>
</parameters>
@@ -50832,8 +50541,9 @@ it starts with an appropriate byte.
<function name="g_utf8_get_char">
<description>
Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
-If @p does not point to a valid UTF-8 encoded character, results are
-undefined. If you are not sure that the bytes are complete
+
+If @p does not point to a valid UTF-8 encoded character, results
+are undefined. If you are not sure that the bytes are complete
valid Unicode characters, you should use g_utf8_get_char_validated()
instead.
@@ -50956,14 +50666,11 @@ step backwards. It is usually worth stepping backwards from the end
instead of forwards if @offset is in the last fourth of the string,
since moving forward is about 3 times faster than moving backward.
-<note><para>
-This function doesn't abort when reaching the end of @str. Therefore
-you should be sure that @offset is within string boundaries before
-calling that function. Call g_utf8_strlen() when unsure.
-
+Note that this function doesn't abort when reaching the end of @str.
+Therefore you should be sure that @offset is within string boundaries
+before calling that function. Call g_utf8_strlen() when unsure.
This limitation exists as this function is called frequently during
text rendering and therefore has to be as fast as possible.
-</para></note>
</description>
@@ -51022,7 +50729,7 @@ character of the string, you must use g_utf8_find_prev_char() instead.
</parameter_description>
</parameter>
</parameters>
-<return> a pointer to the found character.
+<return> a pointer to the found character
</return>
</function>
@@ -51049,8 +50756,8 @@ If @len is -1, allow unbounded search.
</parameter>
</parameters>
<return> %NULL if the string does not contain the character,
-otherwise, a pointer to the start of the leftmost occurrence of
-the character in the string.
+otherwise, a pointer to the start of the leftmost occurrence
+of the character in the string.
</return>
</function>
@@ -51106,11 +50813,10 @@ bytes are examined
<function name="g_utf8_strncpy">
<description>
-Like the standard C strncpy() function, but
-copies a given number of characters instead of a given number of
-bytes. The @src string must be valid UTF-8 encoded text.
-(Use g_utf8_validate() on all text before trying to use UTF-8
-utility functions with it.)
+Like the standard C strncpy() function, but copies a given number
+of characters instead of a given number of bytes. The @src string
+must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
+text before trying to use UTF-8 utility functions with it.)
</description>
@@ -51155,8 +50861,8 @@ If @len is -1, allow unbounded search.
</parameter>
</parameters>
<return> %NULL if the string does not contain the character,
-otherwise, a pointer to the start of the rightmost occurrence of the
-character in the string.
+otherwise, a pointer to the start of the rightmost occurrence
+of the character in the string.
</return>
</function>
@@ -51190,7 +50896,7 @@ then the string is nul-terminated.
</parameter_description>
</parameter>
</parameters>
-<return> a newly-allocated string which is the reverse of @str.
+<return> a newly-allocated string which is the reverse of @str
</return>
</function>
@@ -51223,8 +50929,7 @@ converted to uppercase.
<function name="g_utf8_substring">
<description>
Copies a substring out of a UTF-8 encoded string.
-The substring will contain @end_pos - @start_pos
-characters.
+The substring will contain @end_pos - @start_pos characters.
Since: 2.30
@@ -51276,9 +50981,9 @@ invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store number of characters written or %NULL.
-The value here stored does not include the trailing 0
-character.
+<parameter_description> location to store number of characters
+written or %NULL. The value here stored does not include the
+trailing 0 character.
</parameter_description>
</parameter>
<parameter name="error">
@@ -51289,9 +50994,8 @@ errors. Any of the errors in #GConvertError other than
</parameter>
</parameters>
<return> a pointer to a newly allocated UCS-4 string.
-This value must be freed with g_free(). If an
-error occurs, %NULL will be returned and
- error set.
+This value must be freed with g_free(). If an error occurs,
+%NULL will be returned and @error set.
</return>
</function>
@@ -51316,8 +51020,8 @@ then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store the number of characters in the
-result, or %NULL.
+<parameter_description> location to store the number of
+characters in the result, or %NULL.
</parameter_description>
</parameter>
</parameters>
@@ -51344,17 +51048,16 @@ If @len < 0, then the string is nul-terminated.
</parameter_description>
</parameter>
<parameter name="items_read">
-<parameter_description> location to store number of bytes read, or %NULL.
-If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
-returned in case @str contains a trailing partial
-character. If an error occurs then the index of the
-invalid input is stored here.
+<parameter_description> location to store number of bytes read,
+or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+returned in case @str contains a trailing partial character. If
+an error occurs then the index of the invalid input is stored here.
</parameter_description>
</parameter>
<parameter name="items_written">
-<parameter_description> location to store number of <type>gunichar2</type> written,
-or %NULL.
-The value stored here does not include the trailing 0.
+<parameter_description> location to store number of #gunichar2
+written, or %NULL. The value stored here does not include the
+trailing 0.
</parameter_description>
</parameter>
<parameter name="error">
@@ -51365,9 +51068,8 @@ errors. Any of the errors in #GConvertError other than
</parameter>
</parameters>
<return> a pointer to a newly allocated UTF-16 string.
-This value must be freed with g_free(). If an
-error occurs, %NULL will be returned and
- error set.
+This value must be freed with g_free(). If an error occurs,
+%NULL will be returned and @error set.
</return>
</function>
@@ -51382,7 +51084,7 @@ character if some bytes were invalid, or the end of the text
being validated otherwise).
Note that g_utf8_validate() returns %FALSE if @max_len is
-positive and any of the @max_len bytes are NUL.
+positive and any of the @max_len bytes are nul.
</description>
@@ -51425,8 +51127,7 @@ Since: 2.18
</parameter_description>
</parameter>
</parameters>
-<return> 0 if the operation was successful, -1 if an error
-occurred
+<return> 0 if the operation was successful, -1 if an error occurred
</return>
</function>
@@ -51596,8 +51297,7 @@ Deprecated: 2.32: Use #GArray and g_array_remove_index() instead.
</parameter>
<parameter name="index_">
<parameter_description> position of value to remove, which must be less than
-<code>value_array-><link
-linkend="GValueArray.n-values">n_values</link></code>
+ value_array->n_values
</parameter_description>
</parameter>
</parameters>
@@ -52919,7 +52619,9 @@ a #GValue of type @dest_type.
<function name="g_value_type_transformable">
<description>
Check whether g_value_transform() is able to transform values
-of type @src_type into values of type @dest_type.
+of type @src_type into values of type @dest_type. Note that for
+the types to be transformable, they must be compatible and a
+transform function must be registered.
</description>
@@ -52961,9 +52663,13 @@ Adds to a #GVariantBuilder.
This call is a convenience wrapper that is exactly equivalent to
calling g_variant_new() followed by g_variant_builder_add_value().
+Note that the arguments must be of the correct width for their types
+specified in @format_string. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
This function might be used as follows:
-|[
+|[<!-- language="C" -->
GVariant *
make_pointless_dictionary (void)
{
@@ -53011,9 +52717,13 @@ This call is a convenience wrapper that is exactly equivalent to
calling g_variant_new_parsed() followed by
g_variant_builder_add_value().
+Note that the arguments must be of the correct width for their types
+specified in @format_string. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
This function might be used as follows:
-|[
+|[<!-- language="C" -->
GVariant *
make_pointless_dictionary (void)
{
@@ -53427,6 +53137,341 @@ positive value if a > b.
</return>
</function>
+<function name="g_variant_dict_clear">
+<description>
+Releases all memory associated with a #GVariantDict without freeing
+the #GVariantDict structure itself.
+
+It typically only makes sense to do this on a stack-allocated
+#GVariantDict if you want to abort building the value part-way
+through. This function need not be called if you call
+g_variant_dict_end() and it also doesn't need to be called on dicts
+allocated with g_variant_dict_new (see g_variant_dict_unref() for
+that).
+
+It is valid to call this function on either an initialised
+#GVariantDict or one that was previously cleared by an earlier call
+to g_variant_dict_clear() but it is not valid to call this function
+on uninitialised memory.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_variant_dict_contains">
+<description>
+Checks if @key exists in @dict.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to lookup in the dictionary
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if @key is in @dict
+
+</return>
+</function>
+
+<function name="g_variant_dict_end">
+<description>
+Returns the current value of @dict as a #GVariant of type
+%G_VARIANT_TYPE_VARDICT, clearing it in the process.
+
+It is not permissible to use @dict in any way after this call except
+for reference counting operations (in the case of a heap-allocated
+#GVariantDict) or by reinitialising it with g_variant_dict_init() (in
+the case of stack-allocated).
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+</parameters>
+<return> a new, floating, #GVariant
+
+</return>
+</function>
+
+<function name="g_variant_dict_init">
+<description>
+Initialises a #GVariantDict structure.
+
+If @from_asv is given, it is used to initialise the dictionary.
+
+This function completely ignores the previous contents of @dict. On
+one hand this means that it is valid to pass in completely
+uninitialised memory. On the other hand, this means that if you are
+initialising over top of an existing #GVariantDict you need to first
+call g_variant_dict_clear() in order to avoid leaking memory.
+
+You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
+#GVariantDict that was initialised with this function. If you ever
+pass a reference to a #GVariantDict outside of the control of your
+own code then you should assume that the person receiving that
+reference may try to use reference counting; you should use
+g_variant_dict_new() instead of this function.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="from_asv">
+<parameter_description> the initial value for @dict
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_variant_dict_insert">
+<description>
+Inserts a value into a #GVariantDict.
+
+This call is a convenience wrapper that is exactly equivalent to
+calling g_variant_new() followed by g_variant_dict_insert_value().
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to insert a value for
+</parameter_description>
+</parameter>
+<parameter name="format_string">
+<parameter_description> a #GVariant varargs format string
+</parameter_description>
+</parameter>
+<parameter name="Varargs">
+<parameter_description> arguments, as per @format_string
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_variant_dict_insert_value">
+<description>
+Inserts (or replaces) a key in a #GVariantDict.
+
+ value is consumed if it is floating.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to insert a value for
+</parameter_description>
+</parameter>
+<parameter name="value">
+<parameter_description> the value to insert
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_variant_dict_lookup">
+<description>
+Looks up a value in a #GVariantDict.
+
+This function is a wrapper around g_variant_dict_lookup_value() and
+g_variant_get(). In the case that %NULL would have been returned,
+this function returns %FALSE. Otherwise, it unpacks the returned
+value and returns %TRUE.
+
+ 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].
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to lookup in the dictionary
+</parameter_description>
+</parameter>
+<parameter name="format_string">
+<parameter_description> a GVariant format string
+</parameter_description>
+</parameter>
+<parameter name="Varargs">
+<parameter_description> the arguments to unpack the value into
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if a value was unpacked
+
+</return>
+</function>
+
+<function name="g_variant_dict_lookup_value">
+<description>
+Looks up a value in a #GVariantDict.
+
+If @key is not found in @dictionary, %NULL is returned.
+
+The @expected_type string specifies what type of value is expected.
+If the value associated with @key has a different type then %NULL is
+returned.
+
+If the key is found and the value has the correct type, it is
+returned. If @expected_type was specified then any non-%NULL return
+value will have this type.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to lookup in the dictionary
+</parameter_description>
+</parameter>
+<parameter name="expected_type">
+<parameter_description> a #GVariantType, or %NULL
+</parameter_description>
+</parameter>
+</parameters>
+<return> the value of the dictionary key, or %NULL
+
+</return>
+</function>
+
+<function name="g_variant_dict_new">
+<description>
+Allocates and initialises a new #GVariantDict.
+
+You should call g_variant_dict_unref() on the return value when it
+is no longer needed. The memory will not be automatically freed by
+any other call.
+
+In some cases it may be easier to place a #GVariantDict directly on
+the stack of the calling function and initialise it with
+g_variant_dict_init(). This is particularly useful when you are
+using #GVariantDict to construct a #GVariant.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="from_asv">
+<parameter_description> the #GVariant with which to initialise the
+dictionary
+</parameter_description>
+</parameter>
+</parameters>
+<return> a #GVariantDict
+
+</return>
+</function>
+
+<function name="g_variant_dict_ref">
+<description>
+Increases the reference count on @dict.
+
+Don't call this on stack-allocated #GVariantDict instances or bad
+things will happen.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a heap-allocated #GVariantDict
+</parameter_description>
+</parameter>
+</parameters>
+<return> a new reference to @dict
+
+</return>
+</function>
+
+<function name="g_variant_dict_remove">
+<description>
+Removes a key and its associated value from a #GVariantDict.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a #GVariantDict
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to remove
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if the key was found and removed
+
+</return>
+</function>
+
+<function name="g_variant_dict_unref">
+<description>
+Decreases the reference count on @dict.
+
+In the event that there are no more references, releases all memory
+associated with the #GVariantDict.
+
+Don't call this on stack-allocated #GVariantDict instances or bad
+things will happen.
+
+Since: 2.40
+
+</description>
+<parameters>
+<parameter name="dict">
+<parameter_description> a heap-allocated #GVariantDict
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
<function name="g_variant_dup_bytestring">
<description>
Similar to g_variant_get_bytestring() except that instead of
@@ -53608,15 +53653,15 @@ Think of this function as an analogue to scanf().
The arguments that are expected by this function are entirely
determined by @format_string. @format_string also restricts the
permissible types of @value. It is an error to give a value with
-an incompatible type. See the section on <link
-linkend='gvariant-format-strings'>GVariant Format Strings</link>.
+an incompatible type. See the section on
+[GVariant format strings][gvariant-format-strings].
Please note that the syntax of the format string is very likely to be
extended in the future.
@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
-<link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+[GVariant format strings][gvariant-format-strings-pointers].
Since: 2.24
@@ -53754,7 +53799,7 @@ g_variant_get().
@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
-<link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+[GVariant format strings][gvariant-format-strings-pointers].
Since: 2.24
@@ -53907,32 +53952,21 @@ fixed-size, as are tuples containing only other fixed-sized types.
@element_size must be the size of a single element in the array,
as given by the section on
-<link linkend='gvariant-serialised-data-memory'>Serialised Data
-Memory</link>.
+[serialized data memory][gvariant-serialised-data-memory].
In particular, arrays of these fixed-sized types can be interpreted
-as an array of the given C type, with @element_size set to
-<code>sizeof</code> the appropriate type:
-
-<informaltable>
-<tgroup cols='2'>
-<thead><row><entry>element type</entry> <entry>C
type</entry></row></thead>
-<tbody>
-<row><entry>%G_VARIANT_TYPE_INT16 (etc.)</entry>
-<entry>#gint16 (etc.)</entry></row>
-<row><entry>%G_VARIANT_TYPE_BOOLEAN</entry>
-<entry>#guchar (not #gboolean!)</entry></row>
-<row><entry>%G_VARIANT_TYPE_BYTE</entry> <entry>#guchar</entry></row>
-<row><entry>%G_VARIANT_TYPE_HANDLE</entry> <entry>#guint32</entry></row>
-<row><entry>%G_VARIANT_TYPE_DOUBLE</entry> <entry>#gdouble</entry></row>
-</tbody>
-</tgroup>
-</informaltable>
-
-For example, if calling this function for an array of 32 bit integers,
-you might say <code>sizeof (gint32)</code>. This value isn't used
-except for the purpose of a double-check that the form of the
-serialised data matches the caller's expectation.
+as an array of the given C type, with @element_size set to the size
+the appropriate type:
+- %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.)
+- %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!)
+- %G_VARIANT_TYPE_BYTE: #guchar
+- %G_VARIANT_TYPE_HANDLE: #guint32
+- %G_VARIANT_TYPE_DOUBLE: #gdouble
+
+For example, if calling this function for an array of 32-bit integers,
+you might say sizeof(gint32). This value isn't used except for the purpose
+of a double-check that the form of the serialised data matches the caller's
+expectation.
@n_elements, which must be non-%NULL is set equal to the number of
items in the array.
@@ -54366,7 +54400,7 @@ varargs call by the user.
@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
-<link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+[GVariant format strings][gvariant-format-strings-pointers].
Since: 2.24
@@ -54677,13 +54711,9 @@ If you break out of a such a while loop using g_variant_iter_loop() then
you must free or unreference all the unpacked values as you would with
g_variant_get(). Failure to do so will cause a memory leak.
-See the section on <link linkend='gvariant-format-strings'>GVariant
-Format Strings</link>.
-
-<example>
-<title>Memory management with g_variant_iter_loop()</title>
-<programlisting>
-/<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
+Here is an example for memory management with g_variant_iter_loop():
+|[<!-- language="C" -->
+// Iterates a dictionary of type 'a{sv}'
void
iterate_dictionary (GVariant *dictionary)
{
@@ -54697,12 +54727,11 @@ while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
g_print ("Item '%s' has type '%s'\n", key,
g_variant_get_type_string (value));
-/<!-- -->* no need to free 'key' and 'value' here *<!-- -->/
-/<!-- -->* unless breaking out of this loop *<!-- -->/
+// no need to free 'key' and 'value' here
+// unless breaking out of this loop
}
}
-</programlisting>
-</example>
+]|
For most cases you should use g_variant_iter_next().
@@ -54716,9 +54745,10 @@ types, use the '&' prefix to avoid allocating any memory at all (and
thereby avoiding the need to free anything as well).
@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
-<link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+the values and also determines if the values are copied or borrowed.
+
+See the section on
+[GVariant format strings][gvariant-format-strings-pointers].
Since: 2.24
@@ -54802,13 +54832,9 @@ function are assumed to point at uninitialised memory. It is the
responsibility of the caller to free all of the values returned by
the unpacking process.
-See the section on <link linkend='gvariant-format-strings'>GVariant
-Format Strings</link>.
-
-<example>
-<title>Memory management with g_variant_iter_next()</title>
-<programlisting>
-/<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
+Here is an example for memory management with g_variant_iter_next():
+|[<!-- language="C" -->
+// Iterates a dictionary of type 'a{sv}'
void
iterate_dictionary (GVariant *dictionary)
{
@@ -54822,21 +54848,21 @@ while (g_variant_iter_next (&iter, "{sv}", &key, &value))
g_print ("Item '%s' has type '%s'\n", key,
g_variant_get_type_string (value));
-/<!-- -->* must free data for ourselves *<!-- -->/
+// must free data for ourselves
g_variant_unref (value);
g_free (key);
}
}
-</programlisting>
-</example>
+]|
For a solution that is likely to be more convenient to C programmers
when dealing with loops, see g_variant_iter_loop().
@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
-<link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+the values and also determines if the values are copied or borrowed.
+
+See the section on
+[GVariant format strings][gvariant-format-strings-pointers].
Since: 2.24
@@ -54868,10 +54894,9 @@ Gets the next item in the container. If no more items remain then
Use g_variant_unref() to drop your reference on the return value when
you no longer need it.
-<example>
-<title>Iterating with g_variant_iter_next_value()</title>
-<programlisting>
-/<!-- -->* recursively iterate a container *<!-- -->/
+Here is an example for iterating with g_variant_iter_next_value():
+|[<!-- language="C" -->
+// recursively iterate a container
void
iterate_container_recursive (GVariant *container)
{
@@ -54889,8 +54914,7 @@ iterate_container_recursive (child);
g_variant_unref (child);
}
}
-</programlisting>
-</example>
+]|
Since: 2.24
@@ -54918,7 +54942,10 @@ value and returns %TRUE.
@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
-<link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+[GVariant format strings][gvariant-format-strings-pointers].
+
+This function is currently implemented with a linear scan. If you
+plan to do many lookups then #GVariantDict may be more efficient.
Since: 2.28
@@ -54950,26 +54977,26 @@ Since: 2.28
<description>
Looks up a value in a dictionary #GVariant.
-This function works with dictionaries of the type
-<literal>a{s*}</literal> (and equally well with type
-<literal>a{o*}</literal>, but we only further discuss the string case
+This function works with dictionaries of the type a{s*} (and equally
+well with type a{o*}, but we only further discuss the string case
for sake of clarity).
-In the event that @dictionary has the type <literal>a{sv}</literal>,
-the @expected_type string specifies what type of value is expected to
-be inside of the variant. If the value inside the variant has a
-different type then %NULL is returned. In the event that @dictionary
-has a value type other than <literal>v</literal> then @expected_type
-must directly match the key type and it is used to unpack the value
-directly or an error occurs.
+In the event that @dictionary has the type a{sv}, the @expected_type
+string specifies what type of value is expected to be inside of the
+variant. If the value inside the variant has a different type then
+%NULL is returned. In the event that @dictionary has a value type other
+than v then @expected_type must directly match the key type and it is
+used to unpack the value directly or an error occurs.
-In either case, if @key is not found in @dictionary, %NULL is
-returned.
+In either case, if @key is not found in @dictionary, %NULL is returned.
If the key is found and the value has the correct type, it is
returned. If @expected_type was specified then any non-%NULL return
value will have this type.
+This function is currently implemented with a linear scan. If you
+plan to do many lookups then #GVariantDict may be more efficient.
+
Since: 2.28
</description>
@@ -55026,16 +55053,31 @@ Creates a new #GVariant instance.
Think of this function as an analogue to g_strdup_printf().
-The type of the created instance and the arguments that are
-expected by this function are determined by @format_string. See the
-section on <link linkend='gvariant-format-strings'>GVariant Format
-Strings</link>. Please note that the syntax of the format string is
-very likely to be extended in the future.
+The type of the created instance and the arguments that are expected
+by this function are determined by @format_string. See the section on
+[GVariant format strings][gvariant-format-strings]. Please note that
+the syntax of the format string is very likely to be extended in the
+future.
The first character of the format string must not be '*' '?' '@' or
'r'; in essence, a new #GVariant must always be constructed by this
function (and not merely passed through it unmodified).
+Note that the arguments must be of the correct width for their types
+specified in @format_string. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
+
+|[
+MyFlags some_flags = FLAG_ONE | FLAG_TWO;
+const gchar *some_strings[] = { "a", "b", "c", NULL };
+GVariant *new_variant;
+
+new_variant = g_variant_new ("(t^as)",
+/<!-- -->* This cast is required. *<!-- -->/
+(guint64) some_flags,
+some_strings);
+]|
+
Since: 2.24
</description>
@@ -55232,11 +55274,11 @@ items.
@value must be an array with fixed-sized elements. Numeric types are
fixed-size as are tuples containing only other fixed-sized types.
- element_size must be the size of a single element in the array. For
-example, if calling this function for an array of 32 bit integers,
-you might say <code>sizeof (gint32)</code>. This value isn't used
-except for the purpose of a double-check that the form of the
-serialised data matches the caller's expectation.
+ element_size must be the size of a single element in the array.
+For example, if calling this function for an array of 32-bit integers,
+you might say sizeof(gint32). This value isn't used except for the purpose
+of a double-check that the form of the serialised data matches the caller's
+expectation.
@n_elements, which must be non-%NULL is set equal to the number of
items in the array.
@@ -55523,15 +55565,21 @@ by a GVariant format string (as per g_variant_new()) may appear. In
that case, the same arguments are collected from the argument list as
g_variant_new() would have collected.
-Consider this simple example:
+Note that the arguments must be of the correct width for their types
+specified in @format. This can be achieved by casting them. See
+the [GVariant varargs documentation][gvariant-varargs].
-<informalexample><programlisting>
+Consider this simple example:
+|[<!-- language="C" -->
g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
-</programlisting></informalexample>
+]|
In the example, the variable argument parameters are collected and
filled in as if they were part of the original string to produce the
-result of <code>[('one', 1), ('two', 2), ('three', 3)]</code>.
+result of
+|[<!-- language="C" -->
+[('one', 1), ('two', 2), ('three', 3)]
+]|
This function is intended only to be used with @format as a string
literal. Any parse error is fatal to the calling process. If you
@@ -55571,6 +55619,10 @@ of a #GVariant pointer (eg: @format was "%*") then the collected
#GVariant pointer will be returned unmodified, without adding any
additional references.
+Note that the arguments in @app must be of the correct width for their types
+specified in @format when collected into the #va_list. See
+the [GVariant varargs documentation][gvariant-varargs].
+
In order to behave correctly in all cases it is necessary for the
calling function to g_variant_ref_sink() the return result before
returning control to the user that originally provided the pointer.
@@ -55815,6 +55867,10 @@ end of the format string.
@format_string, are collected from this #va_list and the list is left
pointing to the argument following the last.
+Note that the arguments in @app must be of the correct width for their
+types specified in @format_string when collected into the #va_list.
+See the [GVariant varargs documentation][gvariant-varargs.
+
These two generalisations allow mixing of multiple calls to
g_variant_new_va() and g_variant_get_va() within a single actual
varargs call by the user.
@@ -55883,7 +55939,7 @@ Parses a #GVariant from a text representation.
A single #GVariant is parsed from the content of @text.
-The format is described <link linkend='gvariant-text'>here</link>.
+The format is described [here][gvariant-text].
The memory at @limit will never be accessed and the parser behaves as
if the character at @limit is the nul terminator. This has the
@@ -55988,11 +56044,21 @@ Since: 2.40
</return>
</function>
+<function name="g_variant_parser_get_error_quark">
+<description>
+Deprecated: Use g_variant_parse_error_quark() instead.
+
+</description>
+<parameters>
+</parameters>
+<return></return>
+</function>
+
<function name="g_variant_print">
<description>
Pretty-prints @value in the format understood by g_variant_parse().
-The format is described <link linkend='gvariant-text'>here</link>.
+The format is described [here][gvariant-text].
If @type_annotate is %TRUE, then type information is included in
the output.
@@ -56067,7 +56133,7 @@ Since: 2.24
<function name="g_variant_ref_sink">
<description>
#GVariant uses a floating reference count system. All functions with
-names starting with <literal>g_variant_new_</literal> return floating
+names starting with `g_variant_new_` return floating
references.
Calling g_variant_ref_sink() on a #GVariant with a floating reference
@@ -56907,7 +56973,7 @@ Since: 2.4
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="args">
@@ -56935,7 +57001,7 @@ Since: 2.2
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="args">
@@ -56959,7 +57025,7 @@ Since: 2.2
<parameters>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="args">
@@ -57006,7 +57072,7 @@ terminating nul character).
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="args">
@@ -57034,7 +57100,7 @@ Since: 2.2
</parameter>
<parameter name="format">
<parameter_description> a standard printf() format string, but notice
-<link linkend="string-precision">string precision pitfalls</link>.
+[string precision pitfalls][string-precision]
</parameter_description>
</parameter>
<parameter name="args">
@@ -57179,13 +57245,13 @@ Since: 2.16
<description>
A convenience function/macro to log a warning message.
-You can make warnings fatal at runtime by setting the
-<envar>G_DEBUG</envar> environment variable (see
-<ulink url="glib-running.html">Running GLib Applications</ulink>).
+You can make warnings fatal at runtime by setting the `G_DEBUG`
+environment variable (see
+[Running GLib Applications](glib-running.html)).
-If g_log_default_handler() is used as the log handler function, a new-line
-character will automatically be appended to @..., and need not be entered
-manually.
+If g_log_default_handler() is used as the log handler function,
+a newline character will automatically be appended to @..., and
+need not be entered manually.
</description>
<parameters>
@@ -57320,6 +57386,49 @@ g_free().
</return>
</function>
+<function name="g_win32_get_command_line">
+<description>
+Gets the command line arguments, on Windows, in the GLib filename
+encoding (ie: UTF-8).
+
+Normally, on Windows, the command line arguments are passed to main()
+in the system codepage encoding. This prevents passing filenames as
+arguments if the filenames contain characters that fall outside of
+this codepage. If such filenames are passed, then substitutions
+will occur (such as replacing some characters with '?').
+
+GLib's policy of using UTF-8 as a filename encoding on Windows was
+designed to localise the pain of dealing with filenames outside of
+the system codepage to one area: dealing with commandline arguments
+in main().
+
+As such, most GLib programs should ignore the value of argv passed to
+their main() function and call g_win32_get_command_line() instead.
+This will get the "full Unicode" commandline arguments using
+GetCommandLineW() and convert it to the GLib filename encoding (which
+is UTF-8 on Windows).
+
+The strings returned by this function are suitable for use with
+functions such as g_open() and g_file_new_for_commandline_arg() but
+are not suitable for use with g_option_context_parse(), which assumes
+that its input will be in the system codepage. The return value is
+suitable for use with g_option_context_parse_strv(), however, which
+is a better match anyway because it won't leak memory.
+
+Unlike argv, the returned value is a normal strv and can (and should)
+be freed with g_strfreev() when no longer needed.
+
+Since: 2.40
+
+</description>
+<parameters>
+</parameters>
+<return> the commandline arguments in the GLib
+filename encoding (ie: UTF-8)
+
+</return>
+</function>
+
<function name="g_win32_get_package_installation_directory">
<description>
Try to determine the installation directory for a software package.
@@ -57332,10 +57441,10 @@ warning is printed if non-NULL is passed as @package.
The original intended use of @package was for a short identifier of
the package, typically the same identifier as used for
-<literal>GETTEXT_PACKAGE</literal> in software configured using GNU
+`GETTEXT_PACKAGE` in software configured using GNU
autotools. The function first looks in the Windows Registry for the
-value <literal>#InstallationDirectory</literal> in the key
-<literal>#HKLM\Software\ package</literal>, and if that value
+value `#InstallationDirectory` in the key
+`#HKLM\Software\ package`, and if that value
exists and is a string, returns that.
It is strongly recommended that packagers of GLib-using libraries
@@ -57555,7 +57664,7 @@ Variables of this type should only contain the value
<function name="gchar">
<description>
-Corresponds to the standard C <type>char</type> type.
+Corresponds to the standard C char type.
</description>
<parameters>
@@ -57589,7 +57698,7 @@ that the data pointed to will not be altered by the function.
<function name="gdouble">
<description>
-Corresponds to the standard C <type>double</type> type.
+Corresponds to the standard C double type.
Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
</description>
@@ -57600,7 +57709,7 @@ Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
<function name="gfloat">
<description>
-Corresponds to the standard C <type>float</type> type.
+Corresponds to the standard C float type.
Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
</description>
@@ -57611,7 +57720,7 @@ Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
<function name="gint">
<description>
-Corresponds to the standard C <type>int</type> type.
+Corresponds to the standard C int type.
Values of this type can range from #G_MININT to #G_MAXINT.
</description>
@@ -57680,7 +57789,7 @@ Values of this type can range from #G_MININT8 (= -128) to
<function name="gintptr">
<description>
-Corresponds to the C99 type <type>intptr_t</type>,
+Corresponds to the C99 type intptr_t,
a signed integer type that can hold any pointer.
To print or scan values of this type, use
@@ -57731,15 +57840,15 @@ Since: 2.6
</description>
<parameters>
<parameter name="required_major">
-<parameter_description> the required major version.
+<parameter_description> the required major version
</parameter_description>
</parameter>
<parameter name="required_minor">
-<parameter_description> the required minor version.
+<parameter_description> the required minor version
</parameter_description>
</parameter>
<parameter name="required_micro">
-<parameter_description> the required micro version.
+<parameter_description> the required micro version
</parameter_description>
</parameter>
</parameters>
@@ -57810,7 +57919,7 @@ by a \004 character
<function name="glong">
<description>
-Corresponds to the standard C <type>long</type> type.
+Corresponds to the standard C long type.
Values of this type can range from #G_MINLONG to #G_MAXLONG.
</description>
@@ -57822,7 +57931,7 @@ Values of this type can range from #G_MINLONG to #G_MAXLONG.
<function name="goffset">
<description>
A signed integer type that is used for file offsets,
-corresponding to the C99 type <type>off64_t</type>.
+corresponding to the C99 type off64_t.
Values of this type can range from #G_MINOFFSET to
#G_MAXOFFSET.
@@ -57840,8 +57949,7 @@ Since: 2.14
<function name="gpointer">
<description>
An untyped pointer.
-#gpointer looks better and is easier to use
-than <type>void*</type>.
+#gpointer looks better and is easier to use than void*.
</description>
<parameters>
@@ -57851,7 +57959,7 @@ than <type>void*</type>.
<function name="gshort">
<description>
-Corresponds to the standard C <type>short</type> type.
+Corresponds to the standard C short type.
Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
</description>
@@ -57863,10 +57971,10 @@ Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
<function name="gsize">
<description>
An unsigned integer type of the result of the sizeof operator,
-corresponding to the <type>size_t</type> type defined in C99.
+corresponding to the size_t type defined in C99.
This type is wide enough to hold the numeric value of a pointer,
-so it is usually 32bit wide on a 32bit platform and 64bit wide
-on a 64bit platform. Values of this type can range from 0 to
+so it 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.
To print or scan values of this type, use
@@ -57881,7 +57989,7 @@ To print or scan values of this type, use
<function name="gssize">
<description>
A signed variant of #gsize, corresponding to the
-<type>ssize_t</type> defined on most platforms.
+ssize_t defined on most platforms.
Values of this type can range from #G_MINSSIZE
to #G_MAXSSIZE.
@@ -57896,7 +58004,7 @@ To print or scan values of this type, use
<function name="guchar">
<description>
-Corresponds to the standard C <type>unsigned char</type> type.
+Corresponds to the standard C unsigned char type.
</description>
<parameters>
@@ -57906,7 +58014,7 @@ Corresponds to the standard C <type>unsigned char</type> type.
<function name="guint">
<description>
-Corresponds to the standard C <type>unsigned int</type> type.
+Corresponds to the standard C unsigned int type.
Values of this type can range from 0 to #G_MAXUINT.
</description>
@@ -57945,7 +58053,7 @@ To print or scan values of this type, use
<function name="guint64">
<description>
-An unsigned integer guaranteed to be 64 bits on all platforms.
+An unsigned integer guaranteed to be 64-bits on all platforms.
Values of this type can range from 0 to #G_MAXUINT64
(= 18,446,744,073,709,551,615).
@@ -57971,7 +58079,7 @@ Values of this type can range from 0 to #G_MAXUINT8 (= 255).
<function name="guintptr">
<description>
-Corresponds to the C99 type <type>uintptr_t</type>,
+Corresponds to the C99 type uintptr_t,
an unsigned integer type that can hold any pointer.
To print or scan values of this type, use
@@ -57987,7 +58095,7 @@ Since: 2.18
<function name="gulong">
<description>
-Corresponds to the standard C <type>unsigned long</type> type.
+Corresponds to the standard C unsigned long type.
Values of this type can range from 0 to #G_MAXULONG.
</description>
@@ -58051,7 +58159,7 @@ To print/scan values of this type as integer, use
<function name="gushort">
<description>
-Corresponds to the standard C <type>unsigned short</type> type.
+Corresponds to the standard C unsigned short type.
Values of this type can range from 0 to #G_MAXUSHORT.
</description>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
