diff options
Diffstat (limited to 'gir')
| -rw-r--r-- | gir/gio-2.0.c | 10080 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 10843 | ||||
| -rw-r--r-- | gir/gmodule-2.0.c | 275 | ||||
| -rw-r--r-- | gir/gobject-2.0.c | 1777 | ||||
| -rw-r--r-- | gir/win32-1.0.gir | 19 |
5 files changed, 15177 insertions, 7817 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 3f3b2222..0cc13e84 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -56,10 +56,17 @@ /** * GActionEntry: * @name: the name of the action - * @activate: the callback to connect to the "activate" signal of the action - * @parameter_type: the type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or %NULL for no parameter) - * @state: the initial state for this action, given in GVariant text format. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary. - * @change_state: the callback to connect to the "change-state" signal of the action + * @activate: the callback to connect to the "activate" signal of the + * action + * @parameter_type: the type of the parameter that must be passed to the + * activate function for this action, given as a single + * GVariant type string (or %NULL for no parameter) + * @state: the initial state for this action, given in GVariant text + * format. The state is parsed with no extra type information, + * so type tags must be added to the string if they are + * necessary. + * @change_state: the callback to connect to the "change-state" signal + * of the action * * This struct defines a single action. It is for use with * g_action_map_add_action_entries(). @@ -156,7 +163,8 @@ * @get_enabled: the virtual function pointer for g_action_get_enabled() * @get_state: the virtual function pointer for g_action_get_state() * @change_state: the virtual function pointer for g_action_change_state() - * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one. + * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an + * 'activate' signal but that implementations of it may have one. * * The virtual function table for #GAction. * @@ -177,6 +185,16 @@ /** + * GAppInfoMonitor: + * + * The only thing you can do with this is to get it via + * g_app_info_monitor_get() and connect to the "changed" signal. + * + * Since: 2.40 + */ + + +/** * GApplication::activate: * @application: the application * @@ -188,13 +206,71 @@ /** * GApplication::command-line: * @application: the application - * @command_line: a #GApplicationCommandLine representing the passed commandline + * @command_line: a #GApplicationCommandLine representing the + * passed commandline * * The ::command-line signal is emitted on the primary instance when * a commandline is not handled locally. See g_application_run() and * the #GApplicationCommandLine documentation for more information. * - * Returns: An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status(). + * Returns: An integer that is set as the exit status for the calling + * process. See g_application_command_line_set_exit_status(). + */ + + +/** + * GApplication::handle-local-options: + * @application: the application + * @options: the options dictionary + * + * 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 */ @@ -231,18 +307,42 @@ /** * GApplicationClass: * @startup: invoked on the primary instance immediately after registration - * @shutdown: invoked only on the registered primary instance immediately after the main loop terminates + * @shutdown: invoked only on the registered primary instance immediately + * after the main loop terminates * @activate: invoked on the primary instance when an activation occurs * @open: invoked on the primary instance when there are files to open - * @command_line: invoked on the primary instance when a command-line is not handled locally - * @local_command_line: invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information. - * @before_emit: invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance - * @after_emit: invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance - * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions - * @quit_mainloop: Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32 - * @run_mainloop: Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore - * @dbus_register: invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the #GDBusConnection to to session bus, and the object path that #GApplication will use to export is D-Bus API. If this function returns %TRUE, registration will proceed; otherwise registration will abort. Since: 2.34 - * @dbus_unregister: invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the @dbus_register vfunc. Since: 2.34 + * @command_line: invoked on the primary instance when a command-line is + * not handled locally + * @local_command_line: invoked (locally) when the process has been invoked + * via commandline execution (as opposed to, say, D-Bus activation - which + * is not currently supported by GApplication). The virtual function has + * the chance to inspect (and possibly replace) the list of command line + * arguments. See g_application_run() for more information. + * @before_emit: invoked on the primary instance before 'activate', 'open', + * 'command-line' or any action invocation, gets the 'platform data' from + * the calling instance + * @after_emit: invoked on the primary instance after 'activate', 'open', + * 'command-line' or any action invocation, gets the 'platform data' from + * the calling instance + * @add_platform_data: invoked (locally) to add 'platform data' to be sent to + * the primary instance when activating, opening or invoking actions + * @quit_mainloop: Used to be invoked on the primary instance when the use + * count of the application drops to zero (and after any inactivity + * timeout, if requested). Not used anymore since 2.32 + * @run_mainloop: Used to be invoked on the primary instance from + * g_application_run() if the use-count is non-zero. Since 2.32, + * GApplication is iterating the main context directly and is not + * using @run_mainloop anymore + * @dbus_register: invoked locally during registration, if the application is + * using its D-Bus backend. You can use this to export extra objects on the + * bus, that need to exist before the application tries to own the bus name. + * The function is passed the #GDBusConnection to to session bus, and the + * object path that #GApplication will use to export is D-Bus API. + * If this function returns %TRUE, registration will proceed; otherwise + * registration will abort. Since: 2.34 + * @dbus_unregister: invoked locally during unregistration, if the application + * is using its D-Bus backend. Use this to undo anything done by the + * @dbus_register vfunc. Since: 2.34 * * Virtual function table for #GApplication. * @@ -253,14 +353,21 @@ /** * GApplicationCommandLineClass: * - * The <structname>GApplicationCommandLineClass</structname> structure - * contains private data only + * The #GApplicationCommandLineClass-struct + * contains private data only. * * Since: 2.28 */ /** + * GBytesIcon:bytes: + * + * The bytes containing the icon. + */ + + +/** * GCancellable::cancelled: * @cancellable: a #GCancellable. * @@ -273,16 +380,14 @@ * * 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 @@ -290,13 +395,13 @@ * like this. * * An example of how to us this: - * |[ - * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/ - * if (g_cancellable_set_error_if_cancelled (cancellable)) + * |[<!-- 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; @@ -305,12 +410,12 @@ * 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); * ]| * @@ -370,7 +475,7 @@ /** * GDBusAuthObserver::allow-mechanism: * @observer: The #GDBusAuthObserver emitting the signal. - * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>. + * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. * * Emitted to check if @mechanism is allowed to be used. * @@ -415,28 +520,23 @@ /** * GDBusConnection::closed: - * @connection: The #GDBusConnection emitting the signal. - * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection. - * @error: (allow-none): A #GError with more details about the event or %NULL. + * @connection: the #GDBusConnection emitting the signal + * @remote_peer_vanished: %TRUE if @connection is closed because the + * remote peer closed its end of the connection + * @error: (allow-none): a #GError with more details about the event or %NULL * * 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 - * @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 - * @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 g_dbus_connection_close() is called. In this case + * @remote_peer_vanished is set to %FALSE and @error is %NULL. + * + * - If the remote peer closes the connection. In this case + * @remote_peer_vanished is set to %TRUE and @error is set. + * + * - 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 @@ -488,11 +588,11 @@ * GDBusConnection:exit-on-close: * * A boolean specifying whether the process will be terminated (by - * calling <literal>raise(SIGTERM)</literal>) if the connection - * is closed by the remote peer. + * calling `raise(SIGTERM)`) if the connection is closed by the + * remote peer. * - * Note that #GDBusConnection objects returned by g_bus_get_finish() and - * g_bus_get_sync() will (usually) have this property set to %TRUE. + * Note that #GDBusConnection objects returned by g_bus_get_finish() + * and g_bus_get_sync() will (usually) have this property set to %TRUE. * * Since: 2.26 */ @@ -583,11 +683,11 @@ * * 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 @@ -755,7 +855,7 @@ * 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 @@ -777,7 +877,7 @@ * 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 @@ -916,9 +1016,9 @@ * 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. * @@ -952,8 +1052,8 @@ * @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 */ @@ -1024,27 +1124,23 @@ * Ensure that interactions with this proxy conform to the given * interface. This is mainly to ensure that malformed data received * from the other peer is ignored. The given #GDBusInterfaceInfo is - * said to be the <emphasis>expected interface</emphasis>. + * said to be the "expected interface". * * The checks performed are: - * <itemizedlist> - * <listitem><para> - * When completing a method call, if the type signature of - * the reply message isn't what's expected, the reply is - * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. - * </para></listitem> - * <listitem><para> - * Received signals that have a type signature mismatch are dropped and - * a warning is logged via g_warning(). - * </para></listitem> - * <listitem><para> - * Properties received via the initial <literal>GetAll()</literal> call - * or via the <literal>::PropertiesChanged</literal> signal (on the - * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface) or - * set using g_dbus_proxy_set_cached_property() with a type signature - * mismatch are ignored and a warning is logged via g_warning(). - * </para></listitem> - * </itemizedlist> + * - When completing a method call, if the type signature of + * the reply message isn't what's expected, the reply is + * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT. + * + * - Received signals that have a type signature mismatch are dropped and + * a warning is logged via g_warning(). + * + * - Properties received via the initial `GetAll()` call or via the + * `::PropertiesChanged` signal (on the + * [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) + * interface) or set using g_dbus_proxy_set_cached_property() + * with a type signature mismatch are ignored and a warning is + * logged via g_warning(). + * * Note that these checks are never done on methods, signals and * properties that are not referenced in the given * #GDBusInterfaceInfo, since extending a D-Bus interface on the @@ -1120,16 +1216,17 @@ * * 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 * that it's suitable to call g_dbus_connection_register_object() or * similar from the signal handler. * - * Returns: %TRUE to claim @connection, %FALSE to let other handlers run. + * Returns: %TRUE to claim @connection, %FALSE to let other handlers + * run. * Since: 2.26 */ @@ -1440,15 +1537,15 @@ /** * GInetSocketAddress: * - * An IPv4 or IPv6 socket address, corresponding to a <type>struct - * sockaddr_in</type> or <type>struct sockaddr_in6</type>. + * An IPv4 or IPv6 socket address, corresponding to a struct + * sockaddr_in or struct sockaddr_in6. */ /** * GInetSocketAddress:flowinfo: * - * The <literal>sin6_flowinfo</literal> field, for IPv6 addresses. + * The `sin6_flowinfo` field, for IPv6 addresses. * * Since: 2.32 */ @@ -1457,7 +1554,7 @@ /** * GInetSocketAddress:scope_id: * - * The <literal>sin6_scope_id</literal> field, for IPv6 addresses. + * The `sin6_scope_id` field, for IPv6 addresses. * * Since: 2.32 */ @@ -1675,7 +1772,8 @@ * GMountOperation::show-processes: * @op: a #GMountOperation. * @message: string containing a message to display to the user. - * @processes: (element-type GPid): an array of #GPid for processes blocking the operation. + * @processes: (element-type GPid): an array of #GPid for processes + * blocking the operation. * @choices: an array of strings for each possible choice. * * Emitted when one or more processes are blocking an operation @@ -1699,8 +1797,11 @@ * GMountOperation::show-unmount-progress: * @op: a #GMountOperation: * @message: string containing a mesage to display to the user - * @time_left: the estimated time left before the operation completes, in microseconds, or -1 - * @bytes_left: the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed + * @time_left: the estimated time left before the operation completes, + * in microseconds, or -1 + * @bytes_left: the amount of bytes to be written before the operation + * completes (or -1 if such amount is not known), or zero if the operation + * is completed * * Emitted when an unmount operation has been busy for more than some time * (typically 1.5 seconds). @@ -1813,10 +1914,9 @@ * connected to a functioning router that has lost its own upstream * connectivity. Some hosts might only be accessible when a VPN is * active. Other hosts might only be accessible when the VPN is - * <emphasis>not</emphasis> active. Thus, it is best to use - * g_network_monitor_can_reach() or - * g_network_monitor_can_reach_async() to test for reachability on a - * host-by-host basis. (On the other hand, when the property is + * not active. Thus, it is best to use g_network_monitor_can_reach() + * or g_network_monitor_can_reach_async() to test for reachability + * on a host-by-host basis. (On the other hand, when the property is * %FALSE, the application can reasonably expect that no remote * hosts at all are reachable, and should indicate this to the user * in its UI.) @@ -1836,6 +1936,16 @@ /** + * GNotification: + * + * This structure type is private and should only be accessed using the + * public APIs. + * + * Since: 2.40 + */ + + +/** * GPermission: * * #GPermission is an opaque data structure and can only be accessed @@ -1868,6 +1978,89 @@ /** + * GPropertyAction: + * + * This type is opaque. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:enabled: + * + * If @action is currently enabled. + * + * If the action is disabled then calls to g_action_activate() and + * g_action_change_state() have no effect. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:name: + * + * The name of the action. This is mostly meaningful for identifying + * the action once it has been added to a #GActionMap. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:object: + * + * The object to wrap a property on. + * + * The object must be a non-%NULL #GObject with properties. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:parameter-type: + * + * The type of the parameter that must be given when activating the + * action. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:property-name: + * + * The name of the property to wrap on the object. + * + * The property must exist on the passed-in object and it must be + * readable and writable (and not construct-only). + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:state: + * + * The state of the action, or %NULL if the action is stateless. + * + * Since: 2.38 + */ + + +/** + * GPropertyAction:state-type: + * + * The #GVariantType of the state that the action has, or %NULL if the + * action is stateless. + * + * Since: 2.38 + */ + + +/** * GProxyAddress: * * A #GInetSocketAddress representing a connection via a proxy server @@ -1897,6 +2090,25 @@ /** + * GProxyAddressEnumerator:default-port: + * + * The default port to use if #GProxyAddressEnumerator:uri does not + * specify one. + * + * Since: 2.38 + */ + + +/** + * GProxyAddressEnumerator:proxy-resolver: + * + * The proxy resolver to use. + * + * Since: 2.36 + */ + + +/** * GRemoteActionGroupInterface: * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full() * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full() @@ -1927,7 +2139,8 @@ /** * GSettings::change-event: * @settings: the object on which the signal was emitted - * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL + * @keys: (array length=n_keys) (element-type GQuark) (allow-none): + * an array of #GQuarks for the changed keys, or %NULL * @n_keys: the length of the @keys array, or 0 * * The "change-event" signal is emitted once per change event that @@ -1946,7 +2159,8 @@ * for each affected key. If any other connected handler returns * %TRUE then this default functionality will be suppressed. * - * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * Returns: %TRUE to stop other handlers from being invoked for the + * event. FALSE to propagate the event further. */ @@ -1989,7 +2203,8 @@ * connected handler returns %TRUE then this default functionality * will be suppressed. * - * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * Returns: %TRUE to stop other handlers from being invoked for the + * event. FALSE to propagate the event further. */ @@ -2053,7 +2268,8 @@ * 'settings-schema' property if you wish to pass in a * #GSettingsSchema. * - * Deprecated: 2.32:Use the 'schema-id' property instead. In a future version, this property may instead refer to a #GSettingsSchema. + * Deprecated: 2.32: Use the 'schema-id' property instead. In a future + * version, this property may instead refer to a #GSettingsSchema. */ @@ -2106,6 +2322,14 @@ * @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 */ @@ -2123,13 +2347,12 @@ * * 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, @@ -2143,11 +2366,10 @@ * 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 */ @@ -2168,7 +2390,7 @@ /** * GSimpleAction:name: * - * The name of the action. This is mostly meaningful for identifying + * The name of the action. This is mostly meaningful for identifying * the action once it has been added to a #GSimpleActionGroup. * * Since: 2.28 @@ -2213,9 +2435,62 @@ /** + * GSimpleProxyResolver:default-proxy: + * + * The default proxy URI that will be used for any URI that doesn't + * match #GSimpleProxyResolver:ignore-hosts, and doesn't match any + * of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). + * + * Note that as a special case, if this URI starts with + * "socks://", #GSimpleProxyResolver will treat it as referring + * to all three of the socks5, socks4a, and socks4 proxy types. + */ + + +/** + * GSimpleProxyResolver:ignore-hosts: + * + * A list of hostnames and IP addresses that the resolver should + * allow direct connections to. + * + * Entries can be in one of 4 formats: + * + * - A hostname, such as "example.com", ".example.com", or + * "*.example.com", any of which match "example.com" or + * any subdomain of it. + * + * - An IPv4 or IPv6 address, such as "192.168.1.1", + * which matches only that address. + * + * - A hostname or IP address followed by a port, such as + * "example.com:80", which matches whatever the hostname or IP + * address would match, but only for URLs with the (explicitly) + * indicated port. In the case of an IPv6 address, the address + * part must appear in brackets: "[::1]:443" + * + * - An IP address range, given by a base address and prefix length, + * such as "fe80::/10", which matches any address in that range. + * + * Note that when dealing with Unicode hostnames, the matching is + * done against the ASCII form of the name. + * + * Also note that hostname exclusions apply only to connections made + * to hosts identified by name, and IP address exclusions apply only + * to connections made to hosts identified by address. That is, if + * example.com has an address of 192.168.1.1, and the :ignore-hosts list + * contains only "192.168.1.1", then a connection to "example.com" + * (eg, via a #GNetworkAddress) will use the proxy, and a connection to + * "192.168.1.1" (eg, via a #GInetSocketAddress) will not. + * + * These rules match the "ignore-hosts"/"noproxy" rules most + * commonly used by other applications. + */ + + +/** * GSocket:broadcast: * - * Whether the socket should allow sending to and receiving from broadcast addresses. + * Whether the socket should allow sending to broadcast addresses. * * Since: 2.32 */ @@ -2260,7 +2535,7 @@ /** * GSocketAddress: * - * A socket endpoint address, corresponding to <type>struct sockaddr</type> + * A socket endpoint address, corresponding to struct sockaddr * or one of its subtypes. */ @@ -2277,79 +2552,40 @@ * 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 - * connected. - * </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_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(). + * + * - %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 @@ -2366,10 +2602,20 @@ /** + * GSocketClient:proxy-resolver: + * + * The proxy resolver to use + * + * Since: 2.36 + */ + + +/** * GSocketService::incoming: * @service: the #GSocketService * @connection: a new #GSocketConnection object - * @source_object: (allow-none): the source_object passed to g_socket_listener_add_address() + * @source_object: (allow-none): the source_object passed to + * g_socket_listener_add_address() * * The ::incoming signal is emitted when a new incoming connection * to @service needs to be handled. The handler must initiate the @@ -2392,6 +2638,41 @@ /** + * GTask: + * + * The opaque object representing a synchronous or asynchronous task + * and its result. + */ + + +/** + * GTaskThreadFunc: + * @task: the #GTask + * @source_object: (type GObject): @task's source object + * @task_data: @task's task data + * @cancellable: @task's #GCancellable, or %NULL + * + * The prototype for a task function to be run in a thread via + * g_task_run_in_thread() or g_task_run_in_thread_sync(). + * + * If the return-on-cancel flag is set on @task, and @cancellable gets + * cancelled, then the #GTask will be completed immediately (as though + * g_task_return_error_if_cancelled() had been called), without + * waiting for the task function to complete. However, the task + * function will continue running in its thread in the background. The + * function therefore needs to be careful about how it uses + * externally-visible state in this case. See + * g_task_set_return_on_cancel() for more details. + * + * Other than in that case, @task will be completed when the + * #GTaskThreadFunc returns, not when it calls a + * `g_task_return_` function. + * + * Since: 2.36 + */ + + +/** * GTestDBus: * * The #GTestDBus structure contains only private data and @@ -2404,7 +2685,7 @@ /** * GTestDBus:flags: * - * #GTestDBusFlags specifying the behaviour of the dbus session + * #GTestDBusFlags specifying the behaviour of the D-Bus session. * * Since: 2.34 */ @@ -2433,7 +2714,7 @@ * * For example, if the icon name was "gnome-dev-cdrom-audio", the array * would become - * |[ + * |[<!-- language="C" --> * { * "gnome-dev-cdrom-audio", * "gnome-dev-cdrom", @@ -2524,7 +2805,7 @@ * but cannot be read. * * PKCS#8 format is supported since 2.32; earlier releases only - * support PKCS#1. You can use the <literal>openssl rsa</literal> + * support PKCS#1. You can use the `openssl rsa` * tool to convert PKCS#8 keys to PKCS#1. * * Since: 2.28 @@ -2535,14 +2816,14 @@ * GTlsCertificate:private-key-pem: * * The PEM (ASCII) encoded representation of the certificate's - * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE - * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN - * PRIVATE KEY</literal>"). This property (or the + * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE + * KEY`") or unencrypted PKCS#8 format ("`BEGIN + * PRIVATE KEY`"). This property (or the * #GTlsCertificate:private-key property) can be set when * constructing a key (eg, from a file), but cannot be read. * * PKCS#8 format is supported since 2.32; earlier releases only - * support PKCS#1. You can use the <literal>openssl rsa</literal> + * support PKCS#1. You can use the `openssl rsa` * tool to convert PKCS#8 keys to PKCS#1. * * Since: 2.28 @@ -2671,7 +2952,10 @@ * need to worry about this, and can simply block in the signal * handler until the UI thread returns an answer. * - * Returns: %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it. + * Returns: %TRUE to accept @peer_cert (which will also + * immediately end the signal emission). %FALSE to allow the signal + * emission to continue, which will cause the handshake to fail if + * no one else overrides it. * Since: 2.28 */ @@ -2820,9 +3104,15 @@ /** * GTlsInteractionClass: - * @ask_password: ask for a password synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument should have been filled in by using g_tls_password_set_value() or a similar function. + * @ask_password: ask for a password synchronously. If the implementation + * returns %G_TLS_INTERACTION_HANDLED, then the password argument should + * have been filled in by using g_tls_password_set_value() or a similar + * function. * @ask_password_async: ask for a password asynchronously. - * @ask_password_finish: complete operation to ask for a password asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument of the async method should have been filled in by using g_tls_password_set_value() or a similar function. + * @ask_password_finish: complete operation to ask for a password asynchronously. + * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the + * password argument of the async method should have been filled in by using + * g_tls_password_set_value() or a similar function. * * The class for #GTlsInteraction. Derived classes implement the various * virtual interaction methods to handle TLS interactions. @@ -2929,7 +3219,7 @@ * GUnixSocketAddress: * * A UNIX-domain (local) socket address, corresponding to a - * <type>struct sockaddr_un</type>. + * struct sockaddr_un. */ @@ -2938,7 +3228,9 @@ * * Whether or not this is an abstract address * - * Deprecated: Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses. + * Deprecated: Use #GUnixSocketAddress:address-type, which + * distinguishes between zero-padded and non-zero-padded + * abstract addresses. */ @@ -3190,14 +3482,14 @@ * SECTION:extensionpoints * @short_description: Extension Points * @include: gio.h - * @see_also: <link linkend="extending-gio">Extending GIO</link> + * @see_also: [Extending GIO][extending-gio] * * #GIOExtensionPoint provides a mechanism for modules to extend the * functionality of the library or application that loaded it in an * organized fashion. * * An extension point is identified by a name, and it may optionally - * require that any implementation must by of a certain type (or derived + * require that any implementation must be of a certain type (or derived * thereof). Use g_io_extension_point_register() to register an * extension point, and g_io_extension_point_set_required_type() to * set a required type. @@ -3207,16 +3499,16 @@ * of an extension point has a name, and a priority. Use * g_io_extension_point_implement() to implement an extension point. * - * |[ + * |[<!-- language="C" --> * GIOExtensionPoint *ep; * - * /* Register an extension point */ + * // Register an extension point * ep = g_io_extension_point_register ("my-extension-point"); * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); * ]| * - * |[ - * /* Implement an extension point */ + * |[<!-- language="C" --> + * // Implement an extension point * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE); * g_io_extension_point_implement ("my-extension-point", * my_example_impl_get_type (), @@ -3232,14 +3524,14 @@ * * To avoid opening all modules just to find out what extension * points they implement, GIO makes use of a caching mechanism, - * see <link linkend="gio-querymodules">gio-querymodules</link>. + * see [gio-querymodules][gio-querymodules]. * You are expected to run this command after installing a * GIO module. * - * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be - * used to specify additional directories to automatically load modules + * The `GIO_EXTRA_MODULES` environment variable can be used to + * specify additional directories to automatically load modules * from. This environment variable has the same syntax as the - * <envar>PATH</envar>. If two modules have the same base name in different + * `PATH`. If two modules have the same base name in different * directories, then the latter one will be ignored. If additional * directories are specified GIO will load modules from the built-in * directory last. @@ -3250,6 +3542,7 @@ * SECTION:gaction * @title: GAction * @short_description: An action interface + * @include: gio/gio.h * * #GAction represents a single named action. * @@ -3269,7 +3562,7 @@ * * #GAction is merely the interface to the concept of an action, as * described above. Various implementations of actions exist, including - * #GSimpleAction and #GtkAction. + * #GSimpleAction. * * In all cases, the implementing class is responsible for storing the * name of the action, the parameter type, the enabled state, the @@ -3287,6 +3580,7 @@ * SECTION:gactiongroup * @title: GActionGroup * @short_description: A group of actions + * @include: gio/gio.h * @see_also: #GAction * * #GActionGroup represents a group of actions. Actions can be used to @@ -3324,7 +3618,7 @@ * with actions. 'Internal' APIs (ie: ones meant only to be accessed by * the action group implementation) are found on subclasses. This is * why you will find - for example - g_action_group_get_action_enabled() - * but not an equivalent <function>set()</function> call. + * but not an equivalent set() call. * * Signals are emitted on the action group in response to state changes * on individual actions. @@ -3340,6 +3634,7 @@ /** * SECTION:gactiongroupexporter * @title: GActionGroup exporter + * @include: gio/gio.h * @short_description: Export GActionGroups on D-Bus * @see_also: #GActionGroup, #GDBusActionGroup * @@ -3355,6 +3650,7 @@ /** * SECTION:gactionmap * @title: GActionMap + * @include: gio/gio.h * @short_description: Interface for action containers * * The GActionMap interface is implemented by #GActionGroup @@ -3375,6 +3671,7 @@ * SECTION:gappinfo * @short_description: Application information and launch contexts * @include: gio/gio.h + * @see_also: #GAppInfoMonitor * * #GAppInfo and #GAppLaunchContext are used for describing and launching * applications installed on the system. @@ -3382,15 +3679,13 @@ * As of GLib 2.20, URIs will always be converted to POSIX paths * (using g_file_get_path()) when using g_app_info_launch() even if * the application requested an URI and not a POSIX path. For example - * for an desktop-file based application with Exec key <literal>totem - * %U</literal> and a single URI, - * <literal>sftp://foo/file.avi</literal>, then - * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be - * passed. This will only work if a set of suitable GIO extensions - * (such as gvfs 2.26 compiled with FUSE support), is available and - * operational; if this is not the case, the URI will be passed - * unmodified to the application. Some URIs, such as - * <literal>mailto:</literal>, of course cannot be mapped to a POSIX + * for an desktop-file based application with Exec key `totem + * \%U` and a single URI, `sftp://foo/file.avi`, then + * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will + * only work if a set of suitable GIO extensions (such as gvfs 2.26 + * compiled with FUSE support), is available and operational; if this + * is not the case, the URI will be passed unmodified to the application. + * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX * path (in gvfs there's no FUSE mount for it); such URIs will be * passed unmodified to the application. * @@ -3403,14 +3698,14 @@ * equal to the result of g_file_get_uri(). The following snippet * illustrates this: * - * <programlisting> + * |[ * GFile *f; * char *uri; * * file = g_file_new_for_commandline_arg (uri_from_commandline); * * uri = g_file_get_uri (file); - * strcmp (uri, uri_from_commandline) == 0; // FALSE + * strcmp (uri, uri_from_commandline) == 0; * g_free (uri); * * if (g_file_has_uri_scheme (file, "cdda")) @@ -3418,14 +3713,40 @@ * // do something special with uri * } * g_object_unref (file); - * </programlisting> + * ]| + * + * This code will work when both `cdda://sr0/Track 1.wav` and + * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the + * application. It should be noted that it's generally not safe + * for applications to rely on the format of a particular URIs. + * Different launcher applications (e.g. file managers) may have + * different ideas of what a given URI means. + */ + + +/** + * SECTION:gappinfomonitor + * @short_description: Monitor application information for changes * - * This code will work when both <literal>cdda://sr0/Track - * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track - * 1.wav</literal> is passed to the application. It should be noted - * that it's generally not safe for applications to rely on the format - * of a particular URIs. Different launcher applications (e.g. file - * managers) may have different ideas of what a given URI means. + * #GAppInfoMonitor is a very simple object used for monitoring the app + * info database for changes (ie: newly installed or removed + * applications). + * + * Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect + * to the "changed" signal. + * + * In the usual case, applications should try to make note of the change + * (doing things like invalidating caches) but not act on it. In + * particular, applications should avoid making calls to #GAppInfo APIs + * in response to the change signal, deferring these until the time that + * the data is actually required. The exception to this case is when + * application information is actually being displayed on the screen + * (eg: during a search or when the list of all applications is shown). + * The reason for this is that changes to the list of installed + * applications often come in groups (like during system updates) and + * rescanning the list on every change is pointless and expensive. + * + * Since: 2.40 */ @@ -3433,6 +3754,7 @@ * SECTION:gapplication * @title: GApplication * @short_description: Core application class + * @include: gio/gio.h * * A #GApplication is the foundation of an application. It wraps some * low-level platform-specific services and is intended to act as the @@ -3441,41 +3763,40 @@ * this class outside of a higher level framework. * * GApplication provides convenient life cycle management by maintaining - * a <firstterm>use count</firstterm> for the primary application instance. - * The use count can be changed using g_application_hold() and - * g_application_release(). If it drops to zero, the application exits. - * Higher-level classes such as #GtkApplication employ the use count to - * ensure that the application stays alive as long as it has any opened - * windows. + * a "use count" for the primary application instance. The use count can + * be changed using g_application_hold() and g_application_release(). If + * it drops to zero, the application exits. Higher-level classes such as + * #GtkApplication employ the use count to ensure that the application + * stays alive as long as it has any opened windows. * * Another feature that GApplication (optionally) provides is process - * uniqueness. Applications can make use of this functionality by - * providing a unique application ID. If given, only one application - * with this ID can be running at a time per session. The session + * uniqueness. Applications can make use of this functionality by + * providing a unique application ID. If given, only one application + * with this ID can be running at a time per session. The session * concept is platform-dependent, but corresponds roughly to a graphical - * desktop login. When your application is launched again, its + * desktop login. When your application is launched again, its * arguments are passed through platform communication to the already - * running program. The already running instance of the program is - * called the <firstterm>primary instance</firstterm>; for non-unique - * applications this is the always the current instance. - * On Linux, the D-Bus session bus is used for communication. + * running program. The already running instance of the program is + * called the "primary instance"; for non-unique applications this is + * the always the current instance. On Linux, the D-Bus session bus + * is used for communication. * * The use of #GApplication differs from some other commonly-used - * uniqueness libraries (such as libunique) in important ways. The - * application is not expected to manually register itself and check if - * it is the primary instance. Instead, the <code>main()</code> - * function of a #GApplication should do very little more than - * instantiating the application instance, possibly connecting signal - * handlers, then calling g_application_run(). All checks for - * uniqueness are done internally. If the application is the primary - * instance then the startup signal is emitted and the mainloop runs. - * If the application is not the primary instance then a signal is sent - * to the primary instance and g_application_run() promptly returns. - * See the code examples below. + * uniqueness libraries (such as libunique) in important ways. The + * application is not expected to manually register itself and check + * if it is the primary instance. Instead, the main() function of a + * #GApplication should do very little more than instantiating the + * application instance, possibly connecting signal handlers, then + * calling g_application_run(). All checks for uniqueness are done + * internally. If the application is the primary instance then the + * startup signal is emitted and the mainloop runs. If the application + * is not the primary instance then a signal is sent to the primary + * instance and g_application_run() promptly returns. See the code + * examples below. * * If used, the expected form of an application identifier is very close * to that of of a - * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>. + * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface). * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator". * For details on valid application identifiers, see g_application_id_is_valid(). * @@ -3502,23 +3823,26 @@ * for remote access to exported #GMenuModels. * * There is a number of different entry points into a GApplication: - * <itemizedlist> - * <listitem>via 'Activate' (i.e. just starting the application)</listitem> - * <listitem>via 'Open' (i.e. opening some files)</listitem> - * <listitem>by handling a command-line</listitem> - * <listitem>via activating an action</listitem> - * </itemizedlist> + * + * - via 'Activate' (i.e. just starting the application) + * + * - via 'Open' (i.e. opening some files) + * + * - by handling a command-line + * + * - via activating an action + * * The #GApplication::startup signal lets you handle the application * initialization for all of these in a single place. * - * Regardless of which of these entry points is used to start the application, - * GApplication passes some <firstterm id="platform-data">platform - * data</firstterm> from the launching instance to the primary instance, - * in the form of a #GVariant dictionary mapping strings to variants. - * To use platform data, override the @before_emit or @after_emit virtual - * functions in your #GApplication subclass. When dealing with - * #GApplicationCommandLine objects, the platform data is directly - * available via g_application_command_line_get_cwd(), + * Regardless of which of these entry points is used to start the + * application, GApplication passes some "platform data from the + * launching instance to the primary instance, in the form of a + * #GVariant dictionary mapping strings to variants. To use platform + * data, override the @before_emit or @after_emit virtual functions + * in your #GApplication subclass. When dealing with + * #GApplicationCommandLine objects, the platform data is + * directly available via g_application_command_line_get_cwd(), * g_application_command_line_get_environ() and * g_application_command_line_get_platform_data(). * @@ -3537,37 +3861,14 @@ * vfunc, to parse them in either the primary instance or the local instance, * respectively. * - * <example id="gapplication-example-open"><title>Opening files with a GApplication</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-open.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-actions"><title>A GApplication with actions</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-actions.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-menu"><title>A GApplication with menus</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-dbushooks.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> + * For an example of opening files with a GApplication, see + * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). + * + * For an example of using actions with GApplication, see + * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). + * + * For an example of using extra D-Bus hooks with GApplication, see + * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). */ @@ -3575,6 +3876,7 @@ * SECTION:gapplicationcommandline * @title: GApplicationCommandLine * @short_description: A command-line invocation of an application + * @include: gio/gio.h * @see_also: #GApplication * * #GApplicationCommandLine represents a command-line invocation of @@ -3590,7 +3892,8 @@ * The GApplicationCommandLine object can provide the @argc and @argv * parameters for use with the #GOptionContext command-line parsing API, * with the g_application_command_line_get_arguments() function. See - * <xref linkend="gapplication-example-cmdline3"/> for an example. + * [gapplication-example-cmdline3.c][gapplication-example-cmdline3] + * for an example. * * The exit status of the originally-invoked process may be set and * messages can be printed to stdout or stderr of that process. The @@ -3600,64 +3903,136 @@ * * The main use for #GApplicationCommandLine (and the * #GApplication::command-line signal) is 'Emacs server' like use cases: - * You can set the <envar>EDITOR</envar> environment variable to have - * e.g. git use your favourite editor to edit commit messages, and if you - * already have an instance of the editor running, the editing will happen + * You can set the `EDITOR` environment variable to have e.g. git use + * your favourite editor to edit commit messages, and if you already + * have an instance of the editor running, the editing will happen * in the running instance, instead of opening a new one. An important * aspect of this use case is that the process that gets started by git * does not return until the editing is done. * - * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title> - * <para> - * A simple example where the commandline is completely handled - * in the #GApplication::command-line handler. The launching instance exits - * once the signal handler in the primary instance has returned, and the - * return value of the signal handler becomes the exit status of the launching - * instance. - * </para> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title> - * <para> - * An example of split commandline handling. Options that start with - * <literal>--local-</literal> are handled locally, all other options are - * passed to the #GApplication::command-line handler which runs in the primary + * Normally, the commandline is completely handled in the + * #GApplication::command-line handler. The launching instance exits + * once the signal handler in the primary instance has returned, and + * the return value of the signal handler becomes the exit status + * of the launching instance. + * |[<!-- language="C" --> + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * gchar **argv; + * gint argc; + * gint i; + * + * argv = g_application_command_line_get_arguments (cmdline, &argc); + * + * g_application_command_line_print (cmdline, + * "This text is written back\n" + * "to stdout of the caller\n"); + * + * for (i = 0; i < argc; i++) + * g_print ("argument %d: %s\n", i, argv[i]); + * + * g_strfreev (argv); + * + * return 0; + * } + * ]| + * The complete example can be found here: + * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) + * + * In more complicated cases, the handling of the comandline can be + * split between the launcher and the primary instance. + * |[<!-- language="C" --> + * static gboolean + * test_local_cmdline (GApplication *application, + * gchar ***arguments, + * gint *exit_status) + * { + * gint i, j; + * gchar **argv; + * + * argv = *arguments; + * + * i = 1; + * while (argv[i]) + * { + * if (g_str_has_prefix (argv[i], "--local-")) + * { + * g_print ("handling argument %s locally\n", argv[i]); + * g_free (argv[i]); + * for (j = i; argv[j]; j++) + * argv[j] = argv[j + 1]; + * } + * else + * { + * g_print ("not handling argument %s locally\n", argv[i]); + * i++; + * } + * } + * + * *exit_status = 0; + * + * return FALSE; + * } + * + * static void + * test_application_class_init (TestApplicationClass *class) + * { + * G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline; + * + * ... + * } + * ]| + * In this example of split commandline handling, options that start + * with `--local-` are handled locally, all other options are passed + * to the #GApplication::command-line handler which runs in the primary * instance. - * </para> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> - * - * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title> - * <para> - * An example of deferred commandline handling. Here, the commandline is - * not completely handled before the #GApplication::command-line handler - * returns. Instead, we keep a reference to the GApplicationCommandLine - * object and handle it later(in this example, in an idle). Note that it - * is necessary to hold the application until you are done with the - * commandline. - * </para> - * <para> - * This example also shows how to use #GOptionContext for parsing the - * commandline arguments. Note that it is necessary to disable the - * built-in help-handling of #GOptionContext, since it calls exit() - * after printing help, which is not what you want to happen in - * the primary instance. - * </para> - * <programlisting> - * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c"> - * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback> - * </xi:include> - * </programlisting> - * </example> + * + * The complete example can be found here: + * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) + * + * If handling the commandline requires a lot of work, it may + * be better to defer it. + * |[<!-- language="C" --> + * static gboolean + * my_cmdline_handler (gpointer data) + * { + * GApplicationCommandLine *cmdline = data; + * + * // do the heavy lifting in an idle + * + * g_application_command_line_set_exit_status (cmdline, 0); + * g_object_unref (cmdline); // this releases the application + * + * return G_SOURCE_REMOVE; + * } + * + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * // keep the application running until we are done with this commandline + * g_application_hold (application); + * + * g_object_set_data_full (G_OBJECT (cmdline), + * "application", application, + * (GDestroyNotify)g_application_release); + * + * g_object_ref (cmdline); + * g_idle_add (my_cmdline_handler, cmdline); + * + * return 0; + * } + * ]| + * In this example the commandline is not completely handled before + * the #GApplication::command-line handler returns. Instead, we keep + * a reference to the #GApplicationCommandLine object and handle it + * later (in this example, in an idle). Note that it is necessary to + * hold the application until you are done with the commandline. + * + * The complete example can be found here: + * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c) */ @@ -3682,7 +4057,7 @@ * * A typical implementation might look something like this: * - * |[ + * |[<!-- language="C" --> * enum { * NOT_INITIALIZED, * INITIALIZING, @@ -3698,13 +4073,13 @@ * * for (l = self->priv->init_results; l != NULL; l = l->next) * { - * GSimpleAsyncResult *simple = l->data; - * - * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); + * GTask *task = l->data; * - * g_simple_async_result_complete (simple); - * g_object_unref (simple); + * if (self->priv->success) + * g_task_return_boolean (task, TRUE); + * else + * g_task_return_new_error (task, ...); + * g_object_unref (task); * } * * g_list_free (self->priv->init_results); @@ -3719,31 +4094,28 @@ * gpointer user_data) * { * Foo *self = FOO (initable); - * GSimpleAsyncResult *simple; + * GTask *task; * - * simple = g_simple_async_result_new (G_OBJECT (initable) - * callback, - * user_data, - * foo_init_async); + * task = g_task_new (initable, cancellable, callback, user_data); * * switch (self->priv->state) * { * case NOT_INITIALIZED: * _foo_get_ready (self); * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); + * task); * self->priv->state = INITIALIZING; * break; * case INITIALIZING: * self->priv->init_results = g_list_append (self->priv->init_results, - * simple); + * task); * break; * case INITIALIZED: * if (!self->priv->success) - * g_simple_async_result_set_error (simple, ...); - * - * g_simple_async_result_complete_in_idle (simple); - * g_object_unref (simple); + * g_task_return_new_error (task, ...); + * else + * g_task_return_boolean (task, TRUE); + * g_object_unref (task); * break; * } * } @@ -3753,14 +4125,9 @@ * GAsyncResult *result, * GError **error) * { - * g_return_val_if_fail (g_simple_async_result_is_valid (result, - * G_OBJECT (initable), foo_init_async), FALSE); - * - * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result), - * error)) - * return FALSE; + * g_return_val_if_fail (g_task_is_valid (result, initable), FALSE); * - * return TRUE; + * return g_task_propagate_boolean (G_TASK (result), error); * } * * static void @@ -3780,7 +4147,7 @@ * SECTION:gasyncresult * @short_description: Asynchronous Function Results * @include: gio/gio.h - * @see_also: #GSimpleAsyncResult + * @see_also: #GTask * * Provides a base class for implementing asynchronous function results. * @@ -3809,10 +4176,10 @@ * however, the "_finish()" function may be called at most once. * * Example of a typical asynchronous operation flow: - * |[ + * |[<!-- language="C" --> * void _theoretical_frobnitz_async (Theoretical *t, * GCancellable *c, - * GAsyncReadyCallback *cb, + * GAsyncReadyCallback cb, * gpointer u); * * gboolean _theoretical_frobnitz_finish (Theoretical *t, @@ -3833,26 +4200,36 @@ * else * g_printf ("Uh oh!\n"); * - * /<!-- -->* ... *<!-- -->/ + * ... * * } * * int main (int argc, void *argv[]) * { - * /<!-- -->* ... *<!-- -->/ + * ... * * _theoretical_frobnitz_async (theoretical_data, * NULL, * frobnitz_result_func, * NULL); * - * /<!-- -->* ... *<!-- -->/ + * ... * } * ]| * * The callback for an asynchronous operation is called only once, and is * always called, even in the case of a cancelled operation. On cancellation * the result is a %G_IO_ERROR_CANCELLED error. + * + * ## I/O Priority # {#io-priority} + * + * Many I/O-related asynchronous operations have a priority parameter, + * which is used in certain cases to determine the order in which + * operations are executed. They are not used to determine system-wide + * I/O scheduling. Priorities are integers, with lower numbers indicating + * higher priority. It is recommended to choose priorities between + * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT + * as a default. */ @@ -3903,6 +4280,19 @@ /** + * SECTION:gbytesicon + * @short_description: An icon stored in memory as a GBytes + * @include: gio/gio.h + * @see_also: #GIcon, #GLoadableIcon, #GBytes + * + * #GBytesIcon specifies an image held in memory in a common format (usually + * png) to be used as icon. + * + * Since: 2.38 + */ + + +/** * SECTION:gcancellable * @short_description: Thread-safe Operation Cancellation Stack * @include: gio/gio.h @@ -3929,7 +4319,9 @@ * @include: gio/gio.h * * A content type is a platform specific string that defines the type - * of a file. On UNIX it is a <ulink url="http://www.wikipedia.org/wiki/Internet_media_type">mime type</ulink> like "text/plain" or "image/png". + * of a file. On UNIX it is a + * [mime type](http://www.wikipedia.org/wiki/Internet_media_type) + * like "text/plain" or "image/png". * On Win32 it is an extension string like ".doc", ".txt" or a perceived * string like "audio". Such strings can be looked up in the registry at * HKEY_CLASSES_ROOT. @@ -4000,17 +4392,20 @@ * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and * g_unix_connection_receive_credentials() for details. * - * On Linux, the native credential type is a <type>struct ucred</type> - * - see the - * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry> - * man page for details. This corresponds to + * On Linux, the native credential type is a struct ucred - see the + * unix(7) man page for details. This corresponds to * %G_CREDENTIALS_TYPE_LINUX_UCRED. * - * On FreeBSD, the native credential type is a <type>struct cmsgcred</type>. - * This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. + * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native + * credential type is a struct cmsgcred. This corresponds + * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. * - * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>. + * On OpenBSD, the native credential type is a struct sockpeercred. * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. + * + * On Solaris (including OpenSolaris and its derivatives), the native + * credential type is a ucred_t. This corresponds to + * %G_CREDENTIALS_TYPE_SOLARIS_UCRED. */ @@ -4040,7 +4435,8 @@ * SECTION:gdbusactiongroup * @title: GDBusActionGroup * @short_description: A D-Bus GActionGroup implementation - * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link> + * @include: gio/gio.h + * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter] * * #GDBusActionGroup is an implementation of the #GActionGroup * interface that can be used as a proxy for an action group @@ -4056,7 +4452,7 @@ * * Routines for working with D-Bus addresses. A D-Bus address is a string * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses - * is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>. + * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses). */ @@ -4071,10 +4467,13 @@ * signals you are interested in. Note that new signals may be added * in the future * + * ## Controlling Authentication # {#auth-observer} + * * For example, if you only want to allow D-Bus connections from * processes owned by the same uid as the server, you would use a * signal handler like the following: - * <example id="auth-observer"><title>Controlling Authentication</title><programlisting> + * + * |[ * static gboolean * on_authorize_authenticated_peer (GDBusAuthObserver *observer, * GIOStream *stream, @@ -4095,7 +4494,7 @@ * * return authorized; * } - * </programlisting></example> + * ]| */ @@ -4113,14 +4512,10 @@ * an D-Bus client, it is often easier to use the g_bus_own_name(), * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. * - * As an exception to the usual GLib rule that a particular object must not be - * used by two threads at the same time, #GDBusConnection's methods may be - * called from any thread<footnote> - * <para> - * This is so that g_bus_get() and g_bus_get_sync() can safely return the - * same #GDBusConnection when called from any thread. - * </para> - * </footnote>. + * As an exception to the usual GLib rule that a particular object must not + * be used by two threads at the same time, #GDBusConnection's methods may be + * called from any thread. This is so that g_bus_get() and g_bus_get_sync() + * can safely return the same #GDBusConnection when called from any thread. * * Most of the ways to obtain a #GDBusConnection automatically initialize it * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and @@ -4138,13 +4533,25 @@ * #GError, the only valid thing you can do with that #GDBusConnection is to * free it with g_object_unref(). * - * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * ## An example D-Bus server # {#gdbus-server} + * + * Here is an example for a D-Bus server: + * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c) + * + * ## An example for exporting a subtree # {#gdbus-subtree-server} + * + * Here is an example for exporting a subtree: + * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c) * - * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * ## An example for file descriptor passing # {#gdbus-unix-fd-client} * - * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * Here is an example for passing UNIX file descriptors: + * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c) * - * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * ## An example for exporting a GObject # {#gdbus-export} + * + * Here is an example for exporting a #GObject: + * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c) */ @@ -4172,8 +4579,8 @@ * automatically map from D-Bus errors to #GError and back. This * is typically done in the function returning the #GQuark for the * error domain: - * <example id="error-registration"><title>Error Registration</title><programlisting> - * /<!-- -->* foo-bar-error.h: *<!-- -->/ + * |[<!-- language="C" --> + * // foo-bar-error.h: * * #define FOO_BAR_ERROR (foo_bar_error_quark ()) * GQuark foo_bar_error_quark (void); @@ -4183,10 +4590,10 @@ * FOO_BAR_ERROR_FAILED, * FOO_BAR_ERROR_ANOTHER_ERROR, * FOO_BAR_ERROR_SOME_THIRD_ERROR, - * FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/ + * FOO_BAR_N_ERRORS / *< skip >* / * } FooBarError; * - * /<!-- -->* foo-bar-error.c: *<!-- -->/ + * // foo-bar-error.c: * * static const GDBusErrorEntry foo_bar_error_entries[] = * { @@ -4195,7 +4602,7 @@ * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, * }; * - * /<!-- -->* Ensure that every error code has an associated D-Bus error name *<!-- -->/ + * // Ensure that every error code has an associated D-Bus error name * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); * * GQuark @@ -4208,12 +4615,15 @@ * G_N_ELEMENTS (foo_bar_error_entries)); * return (GQuark) quark_volatile; * } - * </programlisting></example> + * ]| * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and - * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>. - * If the other peer is using GDBus, the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead + * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError. + * + * If the other peer is using GDBus, and has registered the association with + * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark + * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover - * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error(). + * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). * * Note that errors in the %G_DBUS_ERROR error domain is intended only * for returning errors from a remote message bus process. Errors @@ -4253,7 +4663,7 @@ * used when registering objects with g_dbus_connection_register_object(). * * The format of D-Bus introspection XML is specified in the - * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>. + * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) */ @@ -4261,7 +4671,8 @@ * SECTION:gdbusmenumodel * @title: GDBusMenuModel * @short_description: A D-Bus GMenuModel implementation - * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link> + * @include: gio/gio.h + * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter] * * #GDBusMenuModel is an implementation of #GMenuModel that can be used * as a proxy for a menu model that is exported over D-Bus with @@ -4302,7 +4713,8 @@ * * Convenience API for owning bus names. * - * <example id="gdbus-owning-names"><title>Simple application owning a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * A simple example for owning a name can be found in + * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c) */ @@ -4314,7 +4726,8 @@ * * Convenience API for watching bus names. * - * <example id="gdbus-watching-names"><title>Simple application watching a name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * A simple example for watching a name can be found in + * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c) */ @@ -4336,8 +4749,8 @@ * @include: gio/gio.h * * The #GDBusObjectManager type is the base type for service- and - * client-side implementations of the standardized <ulink - * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> + * client-side implementations of the standardized + * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface. * * See #GDBusObjectManagerClient for the client-side implementation @@ -4352,8 +4765,8 @@ * * #GDBusObjectManagerClient is used to create, monitor and delete object * proxies for remote objects exported by a #GDBusObjectManagerServer (or any - * code implementing the <ulink - * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> + * code implementing the + * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface). * * Once an instance of this type has been created, you can connect to @@ -4393,18 +4806,17 @@ * is set to the new name owner (this includes emission of the * #GObject::notify signal). Furthermore, you are guaranteed that * #GDBusObjectManagerClient:name-owner will alternate between a name owner - * (e.g. <literal>:1.42</literal>) and %NULL even in the case where + * (e.g. `:1.42`) and %NULL even in the case where * the name of interest is atomically replaced * * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy * instances. All signals (including the - * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal> - * signal) delivered to #GDBusProxy instances are guaranteed to - * originate from the name owner. This guarantee along with the - * behavior described above, means that certain race conditions - * including the <emphasis><quote>half the proxy is from the old owner - * and the other half is from the new owner</quote></emphasis> problem - * cannot happen. + * org.freedesktop.DBus.Properties::PropertiesChanged signal) + * delivered to #GDBusProxy instances are guaranteed to originate + * from the name owner. This guarantee along with the behavior + * described above, means that certain race conditions including the + * "half the proxy is from the old owner and the other half is from + * the new owner" problem cannot happen. * * To avoid having the application connect to signals on the returned * #GDBusObjectProxy and #GDBusProxy objects, the @@ -4420,7 +4832,7 @@ * #GDBusObjectManagerClient::interface-proxy-signal. * * Note that all callbacks and signals are 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 the #GDBusObjectManagerClient object was constructed * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects * originating from the #GDBusObjectManagerClient object will be created in @@ -4435,8 +4847,8 @@ * @include: gio/gio.h * * #GDBusObjectManagerServer is used to export #GDBusObject instances using - * the standardized <ulink - * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink> + * the standardized + * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface. For example, remote D-Bus clients can get all objects * and properties in a single call. Additionally, any change in the * object hierarchy is broadcast using signals. This means that D-Bus @@ -4506,21 +4918,20 @@ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). * * The generic #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals are not very convenient to work - * with. Therefore, the recommended way of working with proxies is to - * subclass #GDBusProxy, and have more natural properties and signals - * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/> - * for how this can easily be done using the - * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command> - * tool. + * #GDBusProxy::g-signal signals are not very convenient to work with. + * Therefore, the recommended way of working with proxies is to subclass + * #GDBusProxy, and have more natural properties and signals in your derived + * class. This [example][gdbus-example-gdbus-codegen] shows how this can + * easily be done using the [gdbus-codegen][gdbus-codegen] tool. * * A #GDBusProxy instance can be used from multiple threads but note * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed * and #GObject::notify) are 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] * of the thread where the instance was constructed. * - * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * An example using a proxy for a well-known name can be found in + * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c) */ @@ -4538,14 +4949,15 @@ * To just export an object on a well-known name on a message bus, such as the * session or system bus, you should instead use g_bus_own_name(). * - * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> + * An example of peer-to-peer communication with G-DBus can be found + * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). */ /** * SECTION:gdbusutils * @title: D-Bus Utilities - * @short_description: Various utilities related to D-Bus. + * @short_description: Various utilities related to D-Bus * @include: gio/gio.h * * Various utility routines related to D-Bus. @@ -4561,9 +4973,9 @@ * #GDesktopAppInfo is an implementation of #GAppInfo based on * desktop files. * - * Note that <filename><gio/gdesktopappinfo.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific + * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -4579,7 +4991,7 @@ * #GDrive is a container class for #GVolume objects that stem from * the same piece of media. As such, #GDrive abstracts a drive with * (or without) removable media and provides operations for querying - * whether media is available, determing whether media change is + * whether media is available, determining whether media change is * automatically detected and ejecting the media. * * If the #GDrive reports that media isn't automatically detected, one @@ -4645,13 +5057,11 @@ * (see #GInputStream and #GOutputStream). * * To construct a #GFile, you can use: - * <simplelist> - * <member>g_file_new_for_path() if you have a path.</member> - * <member>g_file_new_for_uri() if you have a URI.</member> - * <member>g_file_new_for_commandline_arg() for a command line argument.</member> - * <member>g_file_new_tmp() to create a temporary file from a template.</member> - * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member> - * </simplelist> + * - g_file_new_for_path() if you have a path. + * - g_file_new_for_uri() if you have a URI. + * - g_file_new_for_commandline_arg() for a command line argument. + * - g_file_new_tmp() to create a temporary file from a template. + * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). * * One way to think of a #GFile is as an abstraction of a pathname. For * normal files the system pathname is what is stored internally, but as @@ -4700,20 +5110,19 @@ * Some #GFile operations do not have synchronous analogs, as they may * take a very long time to finish, and blocking may leave an application * unusable. Notable cases include: - * <simplelist> - * <member>g_file_mount_mountable() to mount a mountable file.</member> - * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member> - * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member> - * </simplelist> + * - g_file_mount_mountable() to mount a mountable file. + * - g_file_unmount_mountable_with_operation() to unmount a mountable file. + * - g_file_eject_mountable_with_operation() to eject a mountable file. + * + * ## Entity Tags # {#gfile-etag} * - * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm> * One notable feature of #GFiles are entity tags, or "etags" for * short. Entity tags are somewhat like a more abstract version of the - * traditional mtime, and can be used to quickly determine if the file has - * been modified from the version on the file system. See the HTTP 1.1 - * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink> + * traditional mtime, and can be used to quickly determine if the file + * has been modified from the version on the file system. See the + * HTTP 1.1 + * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) * for HTTP Etag headers, which are a very similar concept. - * </para> */ @@ -4726,7 +5135,7 @@ * File attributes in GIO consist of a list of key-value pairs. * * Keys are strings that contain a key namespace and a key name, separated - * by a colon, e.g. "namespace:keyname". Namespaces are included to sort + * by a colon, e.g. "namespace::keyname". Namespaces are included to sort * key-value pairs by namespaces for relevance. Keys can be retrived * using wildcards, e.g. "standard::*" will return all of the keys in the * "standard" namespace. @@ -4745,70 +5154,62 @@ * and other possible implementation details (e.g., on a UNIX system, a file * attribute key will be registered for the user id for a given file). * - * <para> - * <table> - * <title>GFileAttributes Default Namespaces</title> - * <tgroup cols='2' align='left'><thead> - * <row><entry>Namspace</entry><entry>Description</entry></row> - * </thead> - * <tbody> - * <row><entry>"standard"</entry><entry>The "Standard" namespace. General file - * information that any application may need should be put in this namespace. - * Examples include the file's name, type, and size.</entry></row> - * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link> - * namespace. Currently, the only key in this namespace is "value", which contains - * the value of the current entity tag.</entry></row> - * <row><entry>"id"</entry><entry>The "Identification" namespace. This - * namespace is used by file managers and applications that list directories - * to check for loops and to uniquely identify files.</entry></row> - * <row><entry>"access"</entry><entry>The "Access" namespace. Used to check - * if a user has the proper privilidges to access files and perform - * file operations. Keys in this namespace are made to be generic - * and easily understood, e.g. the "can_read" key is %TRUE if - * the current user has permission to read the file. UNIX permissions and - * NTFS ACLs in Windows should be mapped to these values.</entry></row> - * <row><entry>"mountable"</entry><entry>The "Mountable" namespace. Includes - * simple boolean keys for checking if a file or path supports mount operations, e.g. - * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE.</entry></row> - * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file - * access, changed, created times. </entry></row> - * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific - * information and may not be available for all files. Examples include - * the UNIX "UID", "GID", etc.</entry></row> - * <row><entry>"dos"</entry><entry>The "DOS" namespace. Includes DOS-specific - * information and may not be available for all files. Examples include - * "is_system" for checking if a file is marked as a system file, and "is_archive" - * for checking if a file is marked as an archive file.</entry></row> - * <row><entry>"owner"</entry><entry>The "Owner" namespace. Includes information - * about who owns a file. May not be available for all file systems. Examples include - * "user" for getting the user name of the file owner. This information is often mapped from - * some backend specific data such as a unix UID.</entry></row> - * <row><entry>"thumbnail"</entry><entry>The "Thumbnail" namespace. Includes - * information about file thumbnails and their location within the file system. Examples of - * keys in this namespace include "path" to get the location of a thumbnail, and "failed" - * to check if thumbnailing of the file failed.</entry></row> - * <row><entry>"filesystem"</entry><entry>The "Filesystem" namespace. Gets information - * about the file system where a file is located, such as its type, how much - * space is left available, and the overall size of the file system.</entry></row> - * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace - * contain information about the current GVFS backend in use. </entry></row> - * <row><entry>"xattr"</entry><entry>The "xattr" namespace. Gets information - * about extended user attributes. See attr(5). The "user." prefix of the - * extended user attribute name is stripped away when constructing keys in - * this namespace, e.g. "xattr::mime_type" for the extended attribute with - * the name "user.mime_type". Note that this information is only available - * if GLib has been built with extended attribute support.</entry></row> - * <row><entry>"xattr-sys"</entry><entry>The "xattr-sys" namespace. - * Gets information about extended attributes which are not user-specific. - * See attr(5). Note that this information is only available if GLib - * has been built with extended attribute support.</entry></row> - * <row><entry>"selinux"</entry><entry>The "SELinux" namespace. Includes - * information about the SELinux context of files. Note that this information - * is only available if GLib has been built with SELinux support.</entry></row> - * </tbody> - * </tgroup> - * </table> - * </para> + * ## Default Namespaces + * + * - `"standard"`: The "Standard" namespace. General file information that + * any application may need should be put in this namespace. Examples + * include the file's name, type, and size. + * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key + * in this namespace is "value", which contains the value of the current + * entity tag. + * - `"id"`: The "Identification" namespace. This namespace is used by file + * managers and applications that list directories to check for loops and + * to uniquely identify files. + * - `"access"`: The "Access" namespace. Used to check if a user has the + * proper privileges to access files and perform file operations. Keys in + * this namespace are made to be generic and easily understood, e.g. the + * "can_read" key is %TRUE if the current user has permission to read the + * file. UNIX permissions and NTFS ACLs in Windows should be mapped to + * these values. + * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys + * for checking if a file or path supports mount operations, e.g. mount, + * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. + * - `"time"`: The "Time" namespace. Includes file access, changed, created + * times. + * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and + * may not be available for all files. Examples include the UNIX "UID", + * "GID", etc. + * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may + * not be available for all files. Examples include "is_system" for checking + * if a file is marked as a system file, and "is_archive" for checking if a + * file is marked as an archive file. + * - `"owner"`: The "Owner" namespace. Includes information about who owns a + * file. May not be available for all file systems. Examples include "user" + * for getting the user name of the file owner. This information is often + * mapped from some backend specific data such as a UNIX UID. + * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file + * thumbnails and their location within the file system. Examples of keys in + * this namespace include "path" to get the location of a thumbnail, "failed" + * to check if thumbnailing of the file failed, and "is-valid" to check if + * the thumbnail is outdated. + * - `"filesystem"`: The "Filesystem" namespace. Gets information about the + * file system where a file is located, such as its type, how much space is + * left available, and the overall size of the file system. + * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information + * about the current GVFS backend in use. + * - `"xattr"`: The "xattr" namespace. Gets information about extended + * user attributes. See attr(5). The "user." prefix of the extended user + * attribute name is stripped away when constructing keys in this namespace, + * e.g. "xattr::mime_type" for the extended attribute with the name + * "user.mime_type". Note that this information is only available if + * GLib has been built with extended attribute support. + * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about + * extended attributes which are not user-specific. See attr(5). Note + * that this information is only available if GLib has been built with + * extended attribute support. + * - `"selinux"`: The "SELinux" namespace. Includes information about the + * SELinux context of files. Note that this information is only available + * if GLib has been built with SELinux support. * * Please note that these are not all of the possible namespaces. * More namespaces can be added from GIO modules or by individual applications. @@ -4817,76 +5218,10 @@ * <!-- TODO: Implementation note about using extended attributes on supported * file systems --> * - * <para><table> - * <title>GFileAttributes Built-in Keys and Value Types</title> - * <tgroup cols='3' align='left'><thead> - * <row><entry>Enum Value</entry><entry>Namespace:Key</entry><entry>Value Type</entry></row> - * </thead><tbody> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32 (#GFileType)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object (#GIcon)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object (#GIcon)</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_USED</entry><entry>filesystem::used</entry><entry>uint64</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row> - * <row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row> - * </tbody></tgroup></table></para> + * ## Default Keys + * + * For a list of the built-in keys and their types, see the + * [GFileInfo][GFileInfo] documentation. * * Note that there are no predefined keys in the "xattr" and "xattr-sys" * namespaces. Keys for the "xattr" namespace are constructed by stripping @@ -4894,8 +5229,8 @@ * "xattr::". Keys for the "xattr-sys" namespace are constructed by * concatenating "xattr-sys::" with the extended attribute name. All extended * attribute values are returned as hex-encoded strings in which bytes outside - * the ASCII range are encoded as hexadecimal escape sequences of the form - * \x<replaceable>nn</replaceable>. + * the ASCII range are encoded as escape sequences of the form \x`nn` + * where `nn` is a 2-digit hexadecimal number. */ @@ -4908,9 +5243,9 @@ * #GFileDescriptorBased is implemented by streams (implementations of * #GInputStream or #GOutputStream) that are based on file descriptors. * - * Note that <filename><gio/gfiledescriptorbased.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific + * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. * * Since: 2.24 */ @@ -4921,7 +5256,7 @@ * @short_description: Enumerated Files Routines * @include: gio/gio.h * - * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s, + * #GFileEnumerator allows you to operate on a set of #GFiles, * returning a #GFileInfo structure for each file enumerated (e.g. * g_file_enumerate_children() will return a #GFileEnumerator for each * of the children within a directory). @@ -4929,9 +5264,20 @@ * To get the next file's information from a #GFileEnumerator, use * g_file_enumerator_next_file() or its asynchronous version, * g_file_enumerator_next_files_async(). Note that the asynchronous - * version will return a list of #GFileInfo<!---->s, whereas the + * version will return a list of #GFileInfos, whereas the * synchronous will only return the next file in the enumerator. * + * The ordering of returned files is unspecified for non-Unix + * platforms; for more information, see g_dir_read_name(). On Unix, + * when operating on local files, returned files will be sorted by + * inode number. Effectively you can assume that the ordering of + * returned files will be stable between successive calls (and + * applications) assuming the directory is unchanged. + * + * If your application needs a specific ordering, such as by name or + * modification time, you will have to implement that in your + * application code. + * * To close a #GFileEnumerator, use g_file_enumerator_close(), or * its asynchronous version, g_file_enumerator_close_async(). Once * a #GFileEnumerator is closed, no further actions may be performed @@ -4954,14 +5300,14 @@ * SECTION:gfileinfo * @short_description: File Information and Attributes * @include: gio/gio.h - * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link> + * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute] * * Functionality for manipulating basic metadata for files. #GFileInfo * implements methods for getting information that all files should * contain, and allows for manipulation of extended attributes. * - * See <link linkend="gio-GFileAttribute">GFileAttribute</link> for more - * information on how GIO handles file attributes. + * See [GFileAttribute][gio-GFileAttribute for more information on how + * GIO handles file attributes. * * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its * async variant). To obtain a #GFileInfo for a file input or output @@ -5045,9 +5391,9 @@ * * To get informed about changes to the file or directory you are * monitoring, connect to the #GFileMonitor::changed signal. The - * signal will be emitted in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link> of the thread that the monitor was created in + * signal will be emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that the monitor was created in * (though if the global default main context is blocked, this may * cause notifications to be blocked even if the thread-default * context is still running). @@ -5129,18 +5475,29 @@ * * To check if two #GIcons are equal, see g_icon_equal(). * - * For serializing a #GIcon, use g_icon_to_string() and - * g_icon_new_for_string(). + * For serializing a #GIcon, use g_icon_serialize() and + * g_icon_deserialize(). + * + * If you want to consume #GIcon (for example, in a toolkit) you must + * be prepared to handle at least the three following cases: + * #GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make + * sense to have fast-paths for other cases (like handling #GdkPixbuf + * directly, for example) but all compliant #GIcon implementations + * outside of GIO must implement #GLoadableIcon. * * If your application or library provides one or more #GIcon - * implementations you need to ensure that each #GType is registered - * with the type system prior to calling g_icon_new_for_string(). + * implementations you need to ensure that your new implementation also + * implements #GLoadableIcon. Additionally, you must provide an + * implementation of g_icon_serialize() that gives a result that is + * understood by g_icon_deserialize(), yielding one of the built-in icon + * types. */ /** * SECTION:ginetaddress * @short_description: An IPv4/IPv6 address + * @include: gio/gio.h * * #GInetAddress represents an IPv4 or IPv6 internet address. Use * g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to @@ -5158,6 +5515,7 @@ /** * SECTION:ginetaddressmask * @short_description: An IPv4/IPv6 address mask + * @include: gio/gio.h * * #GInetAddressMask represents a range of IPv4 or IPv6 addresses * described by a base address and a length indicating how many bits @@ -5169,6 +5527,7 @@ /** * SECTION:ginetsocketaddress * @short_description: Internet GSocketAddress + * @include: gio/gio.h * * An IPv4 or IPv6 socket address; that is, the combination of a * #GInetAddress and a port number. @@ -5249,17 +5608,11 @@ * @short_description: I/O Scheduler * @include: gio/gio.h * + * As of GLib 2.36, #GIOScheduler is deprecated in favor of + * #GThreadPool and #GTask. + * * Schedules asynchronous I/O operations. #GIOScheduler integrates * into the main event loop (#GMainLoop) and uses threads. - * - * <para id="io-priority"><indexterm><primary>I/O priority</primary></indexterm> - * Each I/O operation has a priority, and the scheduler uses the priorities - * to determine the order in which operations are executed. They are - * <emphasis>not</emphasis> used to determine system-wide I/O scheduling. - * Priorities are integers, with lower numbers indicating higher priority. - * It is recommended to choose priorities between %G_PRIORITY_LOW and - * %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a default. - * </para> */ @@ -5290,9 +5643,9 @@ * To close a stream use g_io_stream_close() which will close the common * stream object and also the individual substreams. You can also close * the substreams themselves. In most cases this only marks the - * substream as closed, so further I/O on it fails. However, some streams - * may support "half-closed" states where one direction of the stream - * is actually shut down. + * substream as closed, so further I/O on it fails but common state in the + * #GIOStream may still be open. However, some streams may support + * "half-closed" states where one direction of the stream is actually shut down. * * Since: 2.22 */ @@ -5332,8 +5685,8 @@ * #GMemoryOutputStream is a class for using arbitrary * memory chunks as output for GIO streaming output operations. * - * As of GLib 2.34, #GMemoryOutputStream implements - * #GPollableOutputStream. + * As of GLib 2.34, #GMemoryOutputStream trivially implements + * #GPollableOutputStream: it always polls as ready. */ @@ -5341,6 +5694,7 @@ * SECTION:gmenu * @title: GMenu * @short_description: A simple implementation of GMenuModel + * @include: gio/gio.h * * #GMenu is a simple implementation of #GMenuModel. * You populate a #GMenu by adding #GMenuItem instances to it. @@ -5357,6 +5711,7 @@ * SECTION:gmenuexporter * @title: GMenuModel exporter * @short_description: Export GMenuModels on D-Bus + * @include: gio/gio.h * @see_also: #GMenuModel, #GDBusMenuModel * * These functions support exporting a #GMenuModel on D-Bus. @@ -5372,6 +5727,7 @@ * SECTION:gmenumodel * @title: GMenuModel * @short_description: An abstract class representing the contents of a menu + * @include: gio/gio.h * @see_also: #GActionGroup * * #GMenuModel represents the contents of a menu -- an ordered list of @@ -5389,39 +5745,35 @@ * it (or, in the case of the 'root' menu, is defined by the context * in which it is used). * - * As an example, consider the visible portions of the menu in - * <xref linkend="menu-example"/>. + * As an example, consider the visible portions of this menu: + * + * ## An example menu # {#menu-example} * - * <figure id="menu-example"> - * <title>An example menu</title> - * <graphic fileref="menu-example.png" format="PNG"></graphic> - * </figure> + *  * * There are 8 "menus" visible in the screenshot: one menubar, two * submenus and 5 sections: - * <itemizedlist> - * <listitem>the toplevel menubar (containing 4 items)</listitem> - * <listitem>the View submenu (containing 3 sections)</listitem> - * <listitem>the first section of the View submenu (containing 2 items)</listitem> - * <listitem>the second section of the View submenu (containing 1 item)</listitem> - * <listitem>the final section of the View submenu (containing 1 item)</listitem> - * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem> - * <listitem>the Sources section (containing 2 items)</listitem> - * <listitem>the Markup section (containing 2 items)</listitem> - * </itemizedlist> - * - * <xref linkend="menu-model"/> illustrates the conceptual connection between + * + * - the toplevel menubar (containing 4 items) + * - the View submenu (containing 3 sections) + * - the first section of the View submenu (containing 2 items) + * - the second section of the View submenu (containing 1 item) + * - the final section of the View submenu (containing 1 item) + * - the Highlight Mode submenu (containing 2 sections) + * - the Sources section (containing 2 items) + * - the Markup section (containing 2 items) + * + * The [example][menu-model] illustrates the conceptual connection between * these 8 menus. Each large block in the figure represents a menu and the * smaller blocks within the large block represent items in that menu. Some * items contain references to other menus. * - * <figure id="menu-model"> - * <title>A menu model</title> - * <graphic fileref="menu-model.png" format="PNG"></graphic> - * </figure> + * ## A menu example # {#menu-model} * - * Notice that the separators visible in <xref linkend="menu-example"/> - * appear nowhere in <xref linkend="menu-model"/>. This is because + *  + * + * Notice that the separators visible in the [example][menu-example] + * appear nowhere in the [menu model][menu-model]. This is because * separators are not explicitly represented in the menu model. Instead, * a separator is inserted between any two non-empty sections of a menu. * Section items can have labels just like any other item. In that case, @@ -5432,12 +5784,10 @@ * outside the application. Examples include global menus, jumplists, * dash boards, etc. To support such uses, it is necessary to 'export' * information about actions and their representation in menus, which - * is exactly what the - * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link> - * and the - * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link> - * do for #GActionGroup and #GMenuModel. The client-side counterparts - * to make use of the exported information are #GDBusActionGroup and + * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] + * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for + * #GActionGroup and #GMenuModel. The client-side counterparts to + * make use of the exported information are #GDBusActionGroup and * #GDBusMenuModel. * * The API of #GMenuModel is very generic, with iterators for the @@ -5462,48 +5812,37 @@ * While a wide variety of stateful actions is possible, the following * is the minimum that is expected to be supported by all users of exported * menu information: - * <itemizedlist> - * <listitem>an action with no parameter type and no state</listitem> - * <listitem>an action with no parameter type and boolean state</listitem> - * <listitem>an action with string parameter type and string state</listitem> - * </itemizedlist> - * - * <formalpara><title>Stateless</title> - * <para> + * - an action with no parameter type and no state + * - an action with no parameter type and boolean state + * - an action with string parameter type and string state + * + * ## Stateless + * * A stateless action typically corresponds to an ordinary menu item. - * </para> - * <para> + * * Selecting such a menu item will activate the action (with no parameter). - * </para> - * </formalpara> * - * <formalpara><title>Boolean State</title> - * <para> + * ## Boolean State + * * An action with a boolean state will most typically be used with a "toggle" * or "switch" menu item. The state can be set directly, but activating the * action (with no parameter) results in the state being toggled. - * </para> - * <para> + * * Selecting a toggle menu item will activate the action. The menu item should * be rendered as "checked" when the state is true. - * </para> - * </formalpara> * - * <formalpara><title>String Parameter and State</title> - * <para> + * ## String Parameter and State + * * Actions with string parameters and state will most typically be used to * represent an enumerated choice over the items available for a group of * radio menu items. Activating the action with a string parameter is * equivalent to setting that parameter as the state. - * </para> - * <para> + * * Radio menu items, in addition to being associated with the action, will * have a target value. Selecting that menu item will result in activation * of the action with the target value as the parameter. The menu item should * be rendered as "selected" when the state of the action is equal to the * target value of the menu item. - * </para> - * </formalpara> */ @@ -5523,7 +5862,7 @@ * * Unmounting a #GMount instance is an asynchronous operation. For * more information about asynchronous operations, see #GAsyncResult - * and #GSimpleAsyncResult. To unmount a #GMount instance, first call + * and #GTask. To unmount a #GMount instance, first call * g_mount_unmount_with_operation() with (at least) the #GMount instance and a * #GAsyncReadyCallback. The callback will be fired when the * operation has resolved (either with success or failure), and a @@ -5573,6 +5912,32 @@ /** + * SECTION:gnetworking + * @title: gnetworking.h + * @short_description: System networking includes + * @include: gio/gnetworking.h + * + * The `<gio/gnetworking.h>` header can be included to get + * various low-level networking-related system headers, automatically + * taking care of certain portability issues for you. + * + * This can be used, for example, if you want to call setsockopt() + * on a #GSocket. + * + * Note that while WinSock has many of the same APIs as the + * traditional UNIX socket API, most of them behave at least slightly + * differently (particularly with respect to error handling). If you + * want your code to work under both UNIX and Windows, you will need + * to take these differences into account. + * + * Also, under GNU libc, certain non-portable functions are only visible + * in the headers if you define %_GNU_SOURCE before including them. Note + * that this symbol must be defined before including any headers, or it + * may not take effect. + */ + + +/** * SECTION:gnetworkmonitor * @title: GNetworkMonitor * @short_description: Network status monitor @@ -5580,7 +5945,7 @@ * * #GNetworkMonitor provides an easy-to-use cross-platform API * for monitoring network connectivity. On Linux, the implementation - * is based on the kernels netlink interface. + * is based on the kernel's netlink interface. */ @@ -5602,6 +5967,37 @@ /** + * SECTION:gnotification + * @short_description: User Notifications (pop up messages) + * @include: gio/gio.h + * + * #GNotification is a mechanism for creating a notification to be shown + * to the user -- typically as a pop-up notification presented by the + * desktop environment shell. + * + * The key difference between #GNotification and other similar APIs is + * that, if supported by the desktop environment, notifications sent + * with #GNotification will persist after the application has exited, + * and even across system reboots. + * + * Since the user may click on a notification while the application is + * not running, applications using #GNotification should be able to be + * started as a D-Bus service, using #GApplication. + * + * User interaction with a notification (either the default action, or + * buttons) must be associated with actions on the application (ie: + * "app." actions). It is not possible to route user interaction + * through the notification itself, because the object will not exist if + * the application is autostarted as a result of a notification being + * clicked. + * + * A notification can be sent with g_application_send_notification(). + * + * Since: 2.40 + */ + + +/** * SECTION:goutputstream * @short_description: Base class for implementing streaming output * @include: gio/gio.h @@ -5620,7 +6016,9 @@ /** * SECTION:gpermission * @title: GPermission - * @short_description: An object representing the permission to perform a certain action + * @short_description: An object representing the permission + * to perform a certain action + * @include: gio/gio.h * * A #GPermission represents the status of the caller's permission to * perform a certain action. @@ -5672,7 +6070,7 @@ /** * SECTION:gpollableutils - * @short_description: #GPollableInputStream / #GPollableOutputStream utilities + * @short_description: Utilities for pollable streams * @include: gio/gio.h * * Utility functions for #GPollableInputStream and @@ -5681,8 +6079,71 @@ /** + * SECTION:gpropertyaction + * @title: GPropertyAction + * @short_description: A GAction reflecting a GObject property + * @include: gio/gio.h + * + * A #GPropertyAction is a way to get a #GAction with a state value + * reflecting and controlling the value of a #GObject property. + * + * The state of the action will correspond to the value of the property. + * Changing it will change the property (assuming the requested value + * matches the requirements as specified in the #GParamSpec). + * + * Only the most common types are presently supported. Booleans are + * mapped to booleans, strings to strings, signed/unsigned integers to + * int32/uint32 and floats and doubles to doubles. + * + * If the property is an enum then the state will be string-typed and + * conversion will automatically be performed between the enum value and + * "nick" string as per the #GEnumValue table. + * + * Flags types are not currently supported. + * + * Properties of object types, boxed types and pointer types are not + * supported and probably never will be. + * + * Properties of #GVariant types are not currently supported. + * + * If the property is boolean-valued then the action will have a NULL + * parameter type, and activating the action (with no parameter) will + * toggle the value of the property. + * + * In all other cases, the parameter type will correspond to the type of + * the property. + * + * The general idea here is to reduce the number of locations where a + * particular piece of state is kept (and therefore has to be synchronised + * between). #GPropertyAction does not have a separate state that is kept + * in sync with the property value -- its state is the property value. + * + * For example, it might be useful to create a #GAction corresponding to + * the "visible-child-name" property of a #GtkStack so that the current + * page can be switched from a menu. The active radio indication in the + * menu is then directly determined from the active page of the + * #GtkStack. + * + * An anti-example would be binding the "active-id" property on a + * #GtkComboBox. This is because the state of the combobox itself is + * probably uninteresting and is actually being used to control + * something else. + * + * Another anti-example would be to bind to the "visible-child-name" + * property of a #GtkStack if this value is actually stored in + * #GSettings. In that case, the real source of the value is + * #GSettings. If you want a #GAction to control a setting stored in + * #GSettings, see g_settings_create_action() instead, and possibly + * combine its use with g_settings_bind(). + * + * Since: 2.38 + */ + + +/** * SECTION:gproxy * @short_description: Interface for proxy handling + * @include: gio/gio.h * * A #GProxy handles connecting to a remote host via a given type of * proxy server. It is implemented by the 'gio-proxy' extension point. @@ -5698,6 +6159,7 @@ /** * SECTION:gproxyaddress * @short_description: An internet address with proxy information + * @include: gio/gio.h * * Support for proxied #GInetSocketAddress. */ @@ -5717,17 +6179,18 @@ /** * SECTION:gremoteactiongroup * @title: GRemoteActionGroup - * @short_description: a #GActionGroup that interacts with other processes + * @short_description: A GActionGroup that interacts with other processes + * @include: gio/gio.h * * The GRemoteActionGroup interface is implemented by #GActionGroup * instances that either transmit action invocations to other processes * or receive action invocations in the local process from other * processes. * - * The interface has <literal>_full</literal> variants of the two + * The interface has `_full` variants of the two * methods on #GActionGroup used to activate actions: * g_action_group_activate_action() and - * g_action_group_change_action_state(). These variants allow a + * g_action_group_change_action_state(). These variants allow a * "platform data" #GVariant to be specified: a dictionary providing * context for the action invocation (for example: timestamps, startup * notification IDs, etc). @@ -5737,7 +6200,7 @@ * * Additionally, g_dbus_connection_export_action_group() will check if * the exported #GActionGroup implements #GRemoteActionGroup and use the - * <literal>_full</literal> variants of the calls if available. This + * `_full` variants of the calls if available. This * provides a mechanism by which to receive platform data for action * invocations that arrive by way of D-Bus. * @@ -5766,12 +6229,13 @@ * @short_description: Resource framework * @include: gio/gio.h * - * Applications and libraries often contain binary or textual data that is really part of the - * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images, - * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or + * Applications and libraries often contain binary or textual data that is + * really part of the application, rather than user data. For instance + * #GtkBuilder .ui files, splashscreen images, GMenu markup xml, CSS files, + * icons, etc. These are often shipped as files in `$datadir/appname`, or * manually included as literal strings in the code. * - * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program + * The #GResource API and the [glib-compile-resources][glib-compile-resources] program * provide a convenient and efficient alternative to this which has some nice properties. You * maintain the files as normal files, so its easy to edit them, but during the build the files * are combined into a binary bundle that is linked into the executable. This means that loading @@ -5784,27 +6248,28 @@ * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. * * Resource files can also be marked to be preprocessed, by setting the value of the - * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options. + * `preprocess` attribute to a comma-separated list of preprocessing options. * The only options currently supported are: * - * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip - * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar> - * environment variable must be set to the full path to the xmllint executable, or xmllint - * must be in the PATH; otherwise the preprocessing step is skipped. + * `xml-stripblanks` which will use the xmllint command + * to strip ignorable whitespace from the xml file. For this to work, + * the `XMLLINT` environment variable must be set to the full path to + * the xmllint executable, or xmllint must be in the `PATH`; otherwise + * the preprocessing step is skipped. * - * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert + * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata - * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be + * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will * abort. * - * Resource bundles are created by the <link linkend="glib-compile-resources">glib-compile-resources</link> program + * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program * which takes an xml file that describes the bundle, and a set of files that the xml references. These * are combined into a binary resource bundle. * - * <example id="resource-example"><title>Example resource description</title> - * <programlisting><![CDATA[ + * An example resource description: + * |[ * <?xml version="1.0" encoding="UTF-8"?> * <gresources> * <gresource prefix="/org/gtk/Example"> @@ -5813,19 +6278,19 @@ * <file preprocess="xml-stripblanks">menumarkup.xml</file> * </gresource> * </gresources> - * ]]></programlisting></example> + * ]| * * This will create a resource bundle with the following files: - * <programlisting><![CDATA[ + * |[ * /org/gtk/Example/data/splashscreen.png * /org/gtk/Example/dialog.ui * /org/gtk/Example/menumarkup.xml - * ]]></programlisting> + * ]| * * Note that all resources in the process share the same namespace, so use java-style * path prefixes (like in the above example) to avoid conflicts. * - * You can then use <link linkend="glib-compile-resources">glib-compile-resources</link> to compile the xml to a + * You can then use [glib-compile-resources][glib-compile-resources] to compile the xml to a * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and * --generate-header arguments to create a source file and header to link directly into your application. * @@ -5857,12 +6322,25 @@ * * #GSeekable is implemented by streams (implementations of * #GInputStream or #GOutputStream) that support seeking. + * + * Seekable streams largely fall into two categories: resizable and + * fixed-size. + * + * #GSeekable on fixed-sized streams is approximately the same as POSIX + * lseek() on a block device (for example: attmepting to seek past the + * end of the device is an error). Fixed streams typically cannot be + * truncated. + * + * #GSeekable on resizable streams is approximately the same as POSIX + * lseek() on a normal file. Seeking past the end and writing data will + * usually cause the stream to resize by introducing zero bytes. */ /** * SECTION:gsettings * @short_description: High-level API for application settings + * @include: gio/gio.h * * The #GSettings class provides a convenient API for storing and retrieving * application settings. @@ -5912,40 +6390,39 @@ * Similar to GConf, the default values in GSettings schemas can be * localized, but the localized values are stored in gettext catalogs * and looked up with the domain that is specified in the - * <tag class="attribute">gettext-domain</tag> attribute of the - * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag> - * elements and the category that is specified in the l10n attribute of the - * <tag class="starttag">key</tag> element. + * gettext-domain attribute of the <schemalist> or <schema> + * elements and the category that is specified in the l10n attribute of + * the <key> element. * * GSettings uses schemas in a compact binary form that is created - * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link> - * utility. The input is a schema description in an XML format that can be - * described by the following DTD: - * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]| - * - * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename> - * - * At runtime, schemas are identified by their id (as specified - * in the <tag class="attribute">id</tag> attribute of the - * <tag class="starttag">schema</tag> element). The - * convention for schema ids is to use a dotted name, similar in - * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular, - * if the settings are for a specific service that owns a D-Bus bus name, - * the D-Bus bus name and schema id should match. For schemas which deal - * with settings not associated with one named application, the id should - * not use StudlyCaps, e.g. "org.gnome.font-rendering". - * - * In addition to #GVariant types, keys can have types that have enumerated - * types. These can be described by a <tag class="starttag">choice</tag>, - * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see - * <xref linkend="schema-enumerated"/>. The underlying type of - * such a key is string, but you can use g_settings_get_enum(), - * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags() - * access the numeric values corresponding to the string value of enum - * and flags keys. - * - * <example id="schema-default-values"><title>Default values</title> - * <programlisting><![CDATA[ + * by the [glib-compile-schemas][glib-compile-schemas] + * utility. The input is a schema description in an XML format. + * + * A DTD for the gschema XML format can be found here: + * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd) + * + * The [glib-compile-schemas][glib-compile-schemas] tool expects schema + * files to have the extension `.gschema.xml`. + * + * At runtime, schemas are identified by their id (as specified in the + * id attribute of the <schema> element). The convention for schema + * ids is to use a dotted name, similar in style to a D-Bus bus name, + * e.g. "org.gnome.SessionManager". In particular, if the settings are + * for a specific service that owns a D-Bus bus name, the D-Bus bus name + * and schema id should match. For schemas which deal with settings not + * associated with one named application, the id should not use + * StudlyCaps, e.g. "org.gnome.font-rendering". + * + * In addition to #GVariant types, keys can have types that have + * enumerated types. These can be described by a <choice>, + * <enum> or <flags> element, as seen in the + * [example][schema-enumerated]. The underlying type of such a key + * is string, but you can use g_settings_get_enum(), g_settings_set_enum(), + * g_settings_get_flags(), g_settings_set_flags() access the numeric values + * corresponding to the string value of enum and flags keys. + * + * An example for default value: + * |[ * <schemalist> * <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> * @@ -5963,10 +6440,10 @@ * * </schema> * </schemalist> - * ]]></programlisting></example> + * ]| * - * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title> - * <programlisting><![CDATA[ + * An example for ranges, choices and enumerated types: + * |[ * <schemalist> * * <enum id="org.gtk.Test.myenum"> @@ -6009,51 +6486,42 @@ * </key> * </schema> * </schemalist> - * ]]></programlisting></example> - * - * <refsect2> - * <title>Vendor overrides</title> - * <para> - * Default values are defined in the schemas that get installed by - * an application. Sometimes, it is necessary for a vendor or distributor - * to adjust these defaults. Since patching the XML source for the schema - * is inconvenient and error-prone, - * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads - * so-called 'vendor override' files. These are keyfiles in the same - * directory as the XML schema sources which can override default values. - * The schema id serves as the group name in the key file, and the values - * are expected in serialized GVariant form, as in the following example: - * <informalexample><programlisting> + * ]| + * + * ## Vendor overrides + * + * Default values are defined in the schemas that get installed by + * an application. Sometimes, it is necessary for a vendor or distributor + * to adjust these defaults. Since patching the XML source for the schema + * is inconvenient and error-prone, + * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor + * override' files. These are keyfiles in the same directory as the XML + * schema sources which can override default values. The schema id serves + * as the group name in the key file, and the values are expected in + * serialized GVariant form, as in the following example: + * |[ * [org.gtk.Example] * key1='string' * key2=1.5 - * </programlisting></informalexample> - * </para> - * <para> - * glib-compile-schemas expects schema files to have the extension - * <filename>.gschema.override</filename> - * </para> - * </refsect2> - * - * <refsect2> - * <title>Binding</title> - * <para> - * A very convenient feature of GSettings lets you bind #GObject properties - * directly to settings, using g_settings_bind(). Once a GObject property - * has been bound to a setting, changes on either side are automatically - * propagated to the other side. GSettings handles details like - * mapping between GObject and GVariant types, and preventing infinite - * cycles. - * </para> - * <para> - * This makes it very easy to hook up a preferences dialog to the - * underlying settings. To make this even more convenient, GSettings - * looks for a boolean property with the name "sensitivity" and - * automatically binds it to the writability of the bound setting. - * If this 'magic' gets in the way, it can be suppressed with the - * #G_SETTINGS_BIND_NO_SENSITIVITY flag. - * </para> - * </refsect2> + * ]| + * + * glib-compile-schemas expects schema files to have the extension + * `.gschema.override`. + * + * ## Binding + * + * A very convenient feature of GSettings lets you bind #GObject properties + * directly to settings, using g_settings_bind(). Once a GObject property + * has been bound to a setting, changes on either side are automatically + * propagated to the other side. GSettings handles details like mapping + * between GObject and GVariant types, and preventing infinite cycles. + * + * This makes it very easy to hook up a preferences dialog to the + * underlying settings. To make this even more convenient, GSettings + * looks for a boolean property with the name "sensitivity" and + * automatically binds it to the writability of the bound setting. + * If this 'magic' gets in the way, it can be suppressed with the + * #G_SETTINGS_BIND_NO_SENSITIVITY flag. */ @@ -6083,19 +6551,19 @@ * g_settings_backend_create_tree() is a convenience function to create * suitable trees. * - * <note><para> - * The #GSettingsBackend API is exported to allow third-party + * The GSettingsBackend API is exported to allow third-party * implementations, but does not carry the same stability guarantees * as the public GIO API. For this reason, you have to define the - * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including - * <filename>gio/gsettingsbackend.h</filename> - * </para></note> + * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including + * `gio/gsettingsbackend.h`. */ /** * SECTION:gsettingsschema - * @short_description: introspecting and controlling the loading of GSettings schemas + * @short_description: Introspecting and controlling the loading + * of GSettings schemas + * @include: gio/gio.h * * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a * mechanism for advanced control over the loading of schemas and a @@ -6115,7 +6583,7 @@ * * Consider the following example: * - * |[ + * |[<!-- language="C" --> * typedef struct * { * ... @@ -6172,7 +6640,7 @@ * ships a gschemas.compiled file as part of itself, and then simply do * the following: * - * |[ + * |[<!-- language="C" --> * { * GSettings *settings; * gint some_value; @@ -6196,6 +6664,7 @@ * SECTION:gsimpleaction * @title: GSimpleAction * @short_description: A simple GAction implementation + * @include: gio/gio.h * * A #GSimpleAction is the obvious simple implementation of the #GAction * interface. This is the easiest way to create an action for purposes of @@ -6209,6 +6678,7 @@ * SECTION:gsimpleactiongroup * @title: GSimpleActionGroup * @short_description: A simple GActionGroup implementation + * @include: gio/gio.h * * #GSimpleActionGroup is a hash table filled with #GAction objects, * implementing the #GActionGroup and #GActionMap interfaces. @@ -6219,14 +6689,14 @@ * SECTION:gsimpleasyncresult * @short_description: Simple asynchronous results implementation * @include: gio/gio.h - * @see_also: #GAsyncResult + * @see_also: #GAsyncResult, #GTask * - * Implements #GAsyncResult for simple cases. Most of the time, this - * will be all an application needs, and will be used transparently. - * Because of this, #GSimpleAsyncResult is used throughout GIO for - * handling asynchronous functions. + * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of + * #GTask, which provides a simpler API. * - * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error + * #GSimpleAsyncResult implements #GAsyncResult. + * + * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error * reporting, operation cancellation and the final state of an operation, * completely transparent to the application. Results can be returned * as a pointer e.g. for functions that return data that is collected @@ -6264,12 +6734,12 @@ * cause a leak if cancelled before being run). * * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, - * or it can use #GThread<!-- -->s. + * or it can use #GThreads. * g_simple_async_result_complete() will finish an I/O task directly * from the point where it is called. g_simple_async_result_complete_in_idle() - * will finish it from an idle handler in the <link - * linkend="g-main-context-push-thread-default">thread-default main - * context</link>. g_simple_async_result_run_in_thread() will run the + * will finish it from an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * . g_simple_async_result_run_in_thread() will run the * job in a separate thread and then deliver the result to the * thread-default main context. * @@ -6291,14 +6761,13 @@ * #GAsyncResult. A typical implementation of an asynchronous operation * using GSimpleAsyncResult looks something like this: * - * |[ + * |[<!-- language="C" --> * static void * baked_cb (Cake *cake, * gpointer user_data) * { - * /* In this example, this callback is not given a reference to the cake, so - * * the GSimpleAsyncResult has to take a reference to it. - * */ + * // In this example, this callback is not given a reference to the cake, + * // so the GSimpleAsyncResult has to take a reference to it. * GSimpleAsyncResult *result = user_data; * * if (cake == NULL) @@ -6312,12 +6781,11 @@ * g_object_unref); * * - * /* In this example, we assume that baked_cb is called as a callback from - * * the mainloop, so it's safe to complete the operation synchronously here. - * * If, however, _baker_prepare_cake () might call its callback without - * * first returning to the mainloop — inadvisable, but some APIs do so — - * * we would need to use g_simple_async_result_complete_in_idle(). - * */ + * // In this example, we assume that baked_cb is called as a callback from + * // the mainloop, so it's safe to complete the operation synchronously here. + * // If, however, _baker_prepare_cake () might call its callback without + * // first returning to the mainloop — inadvisable, but some APIs do so — + * // we would need to use g_simple_async_result_complete_in_idle(). * g_simple_async_result_complete (result); * g_object_unref (result); * } @@ -6356,9 +6824,8 @@ * g_object_unref); * g_simple_async_result_complete_in_idle (simple); * g_object_unref (simple); - * /* Drop the reference returned by _baker_get_cached_cake(); the - * * GSimpleAsyncResult has taken its own reference. - * */ + * // Drop the reference returned by _baker_get_cached_cake(); + * // the GSimpleAsyncResult has taken its own reference. * g_object_unref (cake); * return; * } @@ -6395,6 +6862,7 @@ * SECTION:gsimplepermission * @title: GSimplePermission * @short_description: A GPermission that doesn't change value + * @include: gio/gio.h * * #GSimplePermission is a trivial implementation of #GPermission that * represents a permission that is either always or never allowed. The @@ -6405,10 +6873,29 @@ /** + * SECTION:gsimpleproxyresolver + * @short_description: Simple proxy resolver implementation + * @include: gio/gio.h + * @see_also: g_socket_client_set_proxy_resolver() + * + * #GSimpleProxyResolver is a simple #GProxyResolver implementation + * that handles a single default proxy, multiple URI-scheme-specific + * proxies, and a list of hosts that proxies should not be used for. + * + * #GSimpleProxyResolver is never the default proxy resolver, but it + * can be used as the base class for another proxy resolver + * implementation, or it can be created and used manually, such as + * with g_socket_client_set_proxy_resolver(). + * + * Since: 2.36 + */ + + +/** * SECTION:gsocket * @short_description: Low-level socket object * @include: gio/gio.h - * @see_also: #GInitable + * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h] * * A #GSocket is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. @@ -6443,7 +6930,7 @@ * reasons. For instance, on Windows a socket is always seen as writable * until a write returns %G_IO_ERROR_WOULD_BLOCK. * - * #GSocket<!-- -->s can be either connection oriented or datagram based. + * #GSockets can be either connection oriented or datagram based. * For connection oriented types you must first establish a connection by * either connecting to an address or accepting a connection from another * address. For connectionless socket types the target/source address is @@ -6463,12 +6950,13 @@ /** * SECTION:gsocketaddress - * @short_description: Abstract base class representing endpoints for socket communication + * @short_description: Abstract base class representing endpoints + * for socket communication + * @include: gio/gio.h * - * #GSocketAddress is the equivalent of <type>struct sockaddr</type> - * in the BSD sockets API. This is an abstract class; use - * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress - * for UNIX domain sockets. + * #GSocketAddress is the equivalent of struct sockaddr in the BSD + * sockets API. This is an abstract class; use #GInetSocketAddress + * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. */ @@ -6499,6 +6987,7 @@ /** * SECTION:gsocketconnectable * @short_description: Interface for potential socket endpoints + * @include: gio/gio.h * * Objects that describe one or more potential socket endpoints * implement #GSocketConnectable. Callers can then use @@ -6506,7 +6995,7 @@ * to try out each socket address in turn until one succeeds, as shown * in the sample code below. * - * |[ + * |[<!-- language="C" --> * MyConnectionType * * connect_to_host (const char *hostname, * guint16 port, @@ -6519,14 +7008,13 @@ * GSocketAddress *sockaddr; * GError *conn_error = NULL; * - * addr = g_network_address_new ("www.gnome.org", 80); + * addr = g_network_address_new (hostname, port); * enumerator = g_socket_connectable_enumerate (addr); * g_object_unref (addr); * - * /<!-- -->* Try each sockaddr until we succeed. Record the first - * * connection error, but not any further ones (since they'll probably - * * be basically the same as the first). - * *<!-- -->/ + * // Try each sockaddr until we succeed. Record the first connection error, + * // but not any further ones (since they'll probably be basically the same + * // as the first). * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error)) * { * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error); @@ -6538,18 +7026,15 @@ * { * if (conn_error) * { - * /<!-- -->* We couldn't connect to the first address, but we succeeded - * * in connecting to a later address. - * *<!-- -->/ + * // We couldn't connect to the first address, but we succeeded + * // in connecting to a later address. * g_error_free (conn_error); * } * return conn; * } * else if (error) * { - * /<!-- -->* Either the initial lookup failed, or else the caller - * * cancelled us. - * *<!-- -->/ + * /// Either initial lookup failed, or else the caller cancelled us. * if (conn_error) * g_error_free (conn_error); * return NULL; @@ -6583,6 +7068,10 @@ * custom socket connection types for specific combination of socket * family/type/protocol using g_socket_connection_factory_register_type(). * + * To close a #GSocketConnection, use g_io_stream_close(). Closing both + * substreams of the #GIOStream separately will not close the underlying + * #GSocket. + * * Since: 2.22 */ @@ -6591,6 +7080,7 @@ * SECTION:gsocketcontrolmessage * @title: GSocketControlMessage * @short_description: A GSocket control message + * @include: gio/gio.h * @see_also: #GSocket. * * A #GSocketControlMessage is a special-purpose utility message that @@ -6599,7 +7089,7 @@ * * The message can represent some sort of special instruction to or * information from the socket or can represent a special kind of - * transfer to the peer (for example, sending a file description over + * transfer to the peer (for example, sending a file descriptor over * a UNIX socket). * * These messages are sent with g_socket_send_message() and received @@ -6622,6 +7112,7 @@ * SECTION:gsocketlistener * @title: GSocketListener * @short_description: Helper for accepting network client connections + * @include: gio/gio.h * @see_also: #GThreadedSocketService, #GSocketService. * * A #GSocketListener is an object that keeps track of a set @@ -6640,6 +7131,7 @@ * SECTION:gsocketservice * @title: GSocketService * @short_description: Make it easy to implement a network service + * @include: gio/gio.h * @see_also: #GThreadedSocketService, #GSocketListener. * * A #GSocketService is an object that represents a service that @@ -6662,9 +7154,9 @@ * If you are interested in writing connection handlers that contain * blocking code then see #GThreadedSocketService. * - * The socket service runs on the main loop of the <link - * linkend="g-main-context-push-thread-default-context">thread-default - * context</link> of the thread it is created in, and is not + * The socket service runs on the main loop of the + * [thread-default context][g-main-context-push-thread-default-context] + * of the thread it is created in, and is not * threadsafe in general. However, the calls to start and stop the * service are thread-safe so these can be used from threads that * handle incoming clients. @@ -6687,7 +7179,7 @@ * then connect to whatever host was pointed to by that record. * * You can use g_resolver_lookup_service() or - * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s + * g_resolver_lookup_service_async() to find the #GSrvTargets * for a given service. However, if you are simply planning to connect * to the remote service, you can use #GNetworkService's * #GSocketConnectable interface and not need to worry about @@ -6696,9 +7188,595 @@ /** + * SECTION:gsubprocess + * @title: GSubprocess + * @short_description: Child processes + * @include: gio/gio.h + * @see_also: #GSubprocessLauncher + * + * #GSubprocess allows the creation of and interaction with child + * processes. + * + * Processes can be communicated with using standard GIO-style APIs (ie: + * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for + * process termination (ie: cancellable and with an asynchronous + * variant). + * + * There is an API to force a process to terminate, as well as a + * race-free API for sending UNIX signals to a subprocess. + * + * One major advantage that GIO brings over the core GLib library is + * comprehensive API for asynchronous I/O, such + * g_output_stream_splice_async(). This makes GSubprocess + * significantly more powerful and flexible than equivalent APIs in + * some other languages such as the `subprocess.py` + * included with Python. For example, using #GSubprocess one could + * create two child processes, reading standard output from the first, + * processing it, and writing to the input stream of the second, all + * without blocking the main loop. + * + * A powerful g_subprocess_communicate() API is provided similar to the + * `communicate()` method of `subprocess.py`. This enables very easy + * interaction with a subprocess that has been opened with pipes. + * + * #GSubprocess defaults to tight control over the file descriptors open + * in the child process, avoiding dangling-fd issues that are caused by + * a simple fork()/exec(). The only open file descriptors in the + * spawned process are ones that were explicitly specified by the + * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was + * specified). + * + * #GSubprocess will quickly reap all child processes as they exit, + * avoiding "zombie processes" remaining around for long periods of + * time. g_subprocess_wait() can be used to wait for this to happen, + * but it will happen even without the call being explicitly made. + * + * As a matter of principle, #GSubprocess has no API that accepts + * shell-style space-separated strings. It will, however, match the + * typical shell behaviour of searching the PATH for executables that do + * not contain a directory separator in their name. + * + * #GSubprocess attempts to have a very simple API for most uses (ie: + * spawning a subprocess with arguments and support for most typical + * kinds of input and output redirection). See g_subprocess_new(). The + * #GSubprocessLauncher API is provided for more complicated cases + * (advanced types of redirection, environment variable manipulation, + * change of working directory, child setup functions, etc). + * + * A typical use of #GSubprocess will involve calling + * g_subprocess_new(), followed by g_subprocess_wait_async() or + * g_subprocess_wait(). After the process exits, the status can be + * checked using functions such as g_subprocess_get_if_exited() (which + * are similar to the familiar WIFEXITED-style POSIX macros). + * + * Since: 2.40 + */ + + +/** + * SECTION:gsubprocesslauncher + * @title: GSubprocess Launcher + * @short_description: Environment options for launching a child process + * @include: gio/gio.h + * + * This class contains a set of options for launching child processes, + * such as where its standard input and output will be directed, the + * argument list, the environment, and more. + * + * While the #GSubprocess class has high level functions covering + * popular cases, use of this class allows access to more advanced + * options. It can also be used to launch multiple subprocesses with + * a similar configuration. + * + * Since: 2.40 + */ + + +/** + * SECTION:gtask + * @short_description: Cancellable synchronous or asynchronous task + * and result + * @include: gio/gio.h + * @see_also: #GAsyncResult + * + * A #GTask represents and manages a cancellable "task". + * + * ## Asynchronous operations + * + * The most common usage of #GTask is as a #GAsyncResult, to + * manage data during an asynchronous operation. You call + * g_task_new() in the "start" method, followed by + * g_task_set_task_data() and the like if you need to keep some + * additional data associated with the task, and then pass the + * task object around through your asynchronous operation. + * Eventually, you will call a method such as + * g_task_return_pointer() or g_task_return_error(), which will + * save the value you give it and then invoke the task's callback + * function (waiting until the next iteration of the main + * loop first, if necessary). The caller will pass the #GTask back + * to the operation's finish function (as a #GAsyncResult), and + * you can use g_task_propagate_pointer() or the like to extract + * the return value. + * + * Here is an example for using GTask as a GAsyncResult: + * |[<!-- language="C" --> + * typedef struct { + * CakeFrostingType frosting; + * char *message; + * } DecorationData; + * + * static void + * decoration_data_free (DecorationData *decoration) + * { + * g_free (decoration->message); + * g_slice_free (DecorationData, decoration); + * } + * + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * GTask *task = user_data; + * DecorationData *decoration = g_task_get_task_data (task); + * GError *error = NULL; + * + * if (cake == NULL) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * g_object_unref (task); + * return; + * } + * + * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) + * { + * g_object_unref (cake); + * // g_task_return_error() takes ownership of error + * g_task_return_error (task, error); + * g_object_unref (task); + * return; + * } + * + * g_task_return_pointer (task, cake, g_object_unref); + * g_object_unref (task); + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GTask *task; + * DecorationData *decoration; + * Cake *cake; + * + * task = g_task_new (self, cancellable, callback, user_data); + * if (radius < 3) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, + * "%ucm radius cakes are silly", + * radius); + * g_object_unref (task); + * return; + * } + * + * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); + * if (cake != NULL) + * { + * // _baker_get_cached_cake() returns a reffed cake + * g_task_return_pointer (task, cake, g_object_unref); + * g_object_unref (task); + * return; + * } + * + * decoration = g_slice_new (DecorationData); + * decoration->frosting = frosting; + * decoration->message = g_strdup (message); + * g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); + * + * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * ]| + * + * ## Chained asynchronous operations + * + * #GTask also tries to simplify asynchronous operations that + * internally chain together several smaller asynchronous + * operations. g_task_get_cancellable(), g_task_get_context(), + * and g_task_get_priority() allow you to get back the task's + * #GCancellable, #GMainContext, and [I/O priority][io-priority] + * when starting a new subtask, so you don't have to keep track + * of them yourself. g_task_attach_source() simplifies the case + * of waiting for a source to fire (automatically using the correct + * #GMainContext and priority). + * + * Here is an example for chained asynchronous operations: + * |[<!-- language="C" --> + * typedef struct { + * Cake *cake; + * CakeFrostingType frosting; + * char *message; + * } BakingData; + * + * static void + * decoration_data_free (BakingData *bd) + * { + * if (bd->cake) + * g_object_unref (bd->cake); + * g_free (bd->message); + * g_slice_free (BakingData, bd); + * } + * + * static void + * decorated_cb (Cake *cake, + * GAsyncResult *result, + * gpointer user_data) + * { + * GTask *task = user_data; + * GError *error = NULL; + * + * if (!cake_decorate_finish (cake, result, &error)) + * { + * g_object_unref (cake); + * g_task_return_error (task, error); + * g_object_unref (task); + * return; + * } + * + * // baking_data_free() will drop its ref on the cake, so we have to + * // take another here to give to the caller. + * g_task_return_pointer (result, g_object_ref (cake), g_object_unref); + * g_object_unref (task); + * } + * + * static void + * decorator_ready (gpointer user_data) + * { + * GTask *task = user_data; + * BakingData *bd = g_task_get_task_data (task); + * + * cake_decorate_async (bd->cake, bd->frosting, bd->message, + * g_task_get_cancellable (task), + * decorated_cb, task); + * } + * + * static void + * baked_cb (Cake *cake, + * gpointer user_data) + * { + * GTask *task = user_data; + * BakingData *bd = g_task_get_task_data (task); + * GError *error = NULL; + * + * if (cake == NULL) + * { + * g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + * "Go to the supermarket"); + * g_object_unref (task); + * return; + * } + * + * bd->cake = cake; + * + * // Bail out now if the user has already cancelled + * if (g_task_return_error_if_cancelled (task)) + * { + * g_object_unref (task); + * return; + * } + * + * if (cake_decorator_available (cake)) + * decorator_ready (task); + * else + * { + * GSource *source; + * + * source = cake_decorator_wait_source_new (cake); + * // Attach @source to @task's GMainContext and have it call + * // decorator_ready() when it is ready. + * g_task_attach_source (task, source, + * G_CALLBACK (decorator_ready)); + * g_source_unref (source); + * } + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * gint priority, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * GTask *task; + * BakingData *bd; + * + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_priority (task, priority); + * + * bd = g_slice_new0 (BakingData); + * bd->frosting = frosting; + * bd->message = g_strdup (message); + * g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); + * + * _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * ]| + * + * ## Asynchronous operations from synchronous ones + * + * You can use g_task_run_in_thread() to turn a synchronous + * operation into an asynchronous one, by running it in a thread + * which will then dispatch the result back to the caller's + * #GMainContext when it completes. + * + * Running a task in a thread: + * |[<!-- language="C" --> + * typedef struct { + * guint radius; + * CakeFlavor flavor; + * CakeFrostingType frosting; + * char *message; + * } CakeData; + * + * static void + * cake_data_free (CakeData *cake_data) + * { + * g_free (cake_data->message); + * g_slice_free (CakeData, cake_data); + * } + * + * static void + * bake_cake_thread (GTask *task, + * gpointer source_object, + * gpointer task_data, + * GCancellable *cancellable) + * { + * Baker *self = source_object; + * CakeData *cake_data = task_data; + * Cake *cake; + * GError *error = NULL; + * + * cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + * cake_data->frosting, cake_data->message, + * cancellable, &error); + * if (cake) + * g_task_return_pointer (task, cake, g_object_unref); + * else + * g_task_return_error (task, error); + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * CakeData *cake_data; + * GTask *task; + * + * cake_data = g_slice_new (CakeData); + * cake_data->radius = radius; + * cake_data->flavor = flavor; + * cake_data->frosting = frosting; + * cake_data->message = g_strdup (message); + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_run_in_thread (task, bake_cake_thread); + * } + * + * Cake * + * baker_bake_cake_finish (Baker *self, + * GAsyncResult *result, + * GError **error) + * { + * g_return_val_if_fail (g_task_is_valid (result, self), NULL); + * + * return g_task_propagate_pointer (G_TASK (result), error); + * } + * ]| + * + * ## Adding cancellability to uncancellable tasks + * + * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() + * can be used to turn an uncancellable operation into a + * cancellable one. If you call g_task_set_return_on_cancel(), + * passing %TRUE, then if the task's #GCancellable is cancelled, + * it will return control back to the caller immediately, while + * allowing the task thread to continue running in the background + * (and simply discarding its result when it finally does finish). + * Provided that the task thread is careful about how it uses + * locks and other externally-visible resources, this allows you + * to make "GLib-friendly" asynchronous and cancellable + * synchronous variants of blocking APIs. + * + * Cancelling a task: + * |[<!-- language="C" --> + * static void + * bake_cake_thread (GTask *task, + * gpointer source_object, + * gpointer task_data, + * GCancellable *cancellable) + * { + * Baker *self = source_object; + * CakeData *cake_data = task_data; + * Cake *cake; + * GError *error = NULL; + * + * cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + * cake_data->frosting, cake_data->message, + * &error); + * if (error) + * { + * g_task_return_error (task, error); + * return; + * } + * + * // If the task has already been cancelled, then we don't want to add + * // the cake to the cake cache. Likewise, we don't want to have the + * // task get cancelled in the middle of updating the cache. + * // g_task_set_return_on_cancel() will return %TRUE here if it managed + * // to disable return-on-cancel, or %FALSE if the task was cancelled + * // before it could. + * if (g_task_set_return_on_cancel (task, FALSE)) + * { + * // If the caller cancels at this point, their + * // GAsyncReadyCallback won't be invoked until we return, + * // so we don't have to worry that this code will run at + * // the same time as that code does. But if there were + * // other functions that might look at the cake cache, + * // then we'd probably need a GMutex here as well. + * baker_add_cake_to_cache (baker, cake); + * g_task_return_pointer (task, cake, g_object_unref); + * } + * } + * + * void + * baker_bake_cake_async (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GAsyncReadyCallback callback, + * gpointer user_data) + * { + * CakeData *cake_data; + * GTask *task; + * + * cake_data = g_slice_new (CakeData); + * + * ... + * + * task = g_task_new (self, cancellable, callback, user_data); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_set_return_on_cancel (task, TRUE); + * g_task_run_in_thread (task, bake_cake_thread); + * } + * + * Cake * + * baker_bake_cake_sync (Baker *self, + * guint radius, + * CakeFlavor flavor, + * CakeFrostingType frosting, + * const char *message, + * GCancellable *cancellable, + * GError **error) + * { + * CakeData *cake_data; + * GTask *task; + * Cake *cake; + * + * cake_data = g_slice_new (CakeData); + * + * ... + * + * task = g_task_new (self, cancellable, NULL, NULL); + * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + * g_task_set_return_on_cancel (task, TRUE); + * g_task_run_in_thread_sync (task, bake_cake_thread); + * + * cake = g_task_propagate_pointer (task, error); + * g_object_unref (task); + * return cake; + * } + * ]| + * + * ## Porting from GSimpleAsyncResult + * + * #GTask's API attempts to be simpler than #GSimpleAsyncResult's + * in several ways: + * - You can save task-specific data with g_task_set_task_data(), and + * retrieve it later with g_task_get_task_data(). This replaces the + * abuse of g_simple_async_result_set_op_res_gpointer() for the same + * purpose with #GSimpleAsyncResult. + * - In addition to the task data, #GTask also keeps track of the + * [priority][io-priority], #GCancellable, and + * #GMainContext associated with the task, so tasks that consist of + * a chain of simpler asynchronous operations will have easy access + * to those values when starting each sub-task. + * - g_task_return_error_if_cancelled() provides simplified + * handling for cancellation. In addition, cancellation + * overrides any other #GTask return value by default, like + * #GSimpleAsyncResult does when + * g_simple_async_result_set_check_cancellable() is called. + * (You can use g_task_set_check_cancellable() to turn off that + * behavior.) On the other hand, g_task_run_in_thread() + * guarantees that it will always run your + * `task_func`, even if the task's #GCancellable + * is already cancelled before the task gets a chance to run; + * you can start your `task_func` with a + * g_task_return_error_if_cancelled() check if you need the + * old behavior. + * - The "return" methods (eg, g_task_return_pointer()) + * automatically cause the task to be "completed" as well, and + * there is no need to worry about the "complete" vs "complete + * in idle" distinction. (#GTask automatically figures out + * whether the task's callback can be invoked directly, or + * if it needs to be sent to another #GMainContext, or delayed + * until the next iteration of the current #GMainContext.) + * - The "finish" functions for #GTask-based operations are generally + * much simpler than #GSimpleAsyncResult ones, normally consisting + * of only a single call to g_task_propagate_pointer() or the like. + * Since g_task_propagate_pointer() "steals" the return value from + * the #GTask, it is not necessary to juggle pointers around to + * prevent it from being freed twice. + * - With #GSimpleAsyncResult, it was common to call + * g_simple_async_result_propagate_error() from the + * `_finish()` wrapper function, and have + * virtual method implementations only deal with successful + * returns. This behavior is deprecated, because it makes it + * difficult for a subclass to chain to a parent class's async + * methods. Instead, the wrapper function should just be a + * simple wrapper, and the virtual method should call an + * appropriate `g_task_propagate_` function. + * Note that wrapper methods can now use + * g_async_result_legacy_propagate_error() to do old-style + * #GSimpleAsyncResult error-returning behavior, and + * g_async_result_is_tagged() to check if a result is tagged as + * having come from the `_async()` wrapper + * function (for "short-circuit" results, such as when passing + * 0 to g_input_stream_read_async()). + */ + + +/** * SECTION:gtcpconnection * @title: GTcpConnection * @short_description: A TCP GSocketConnection + * @include: gio/gio.h * @see_also: #GSocketConnection. * * This is the subclass of #GSocketConnection that is created @@ -6711,7 +7789,9 @@ /** * SECTION:gtcpwrapperconnection * @title: GTcpWrapperConnection - * @short_description: wrapper for non-GSocketConnection-based, GSocket-based GIOStreams + * @short_description: Wrapper for non-GSocketConnection-based, + * GSocket-based GIOStreams + * @include: gio/gio.h * @see_also: #GSocketConnection. * * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is @@ -6729,7 +7809,78 @@ * @short_description: D-Bus testing helper * @include: gio/gio.h * - * Helper to test D-Bus code wihtout messing up with user' session bus. + * A helper class for testing code which uses D-Bus without touching the user's + * session bus. + * + * Note that #GTestDBus modifies the user’s environment, calling setenv(). + * This is not thread-safe, so all #GTestDBus calls should be completed before + * threads are spawned, or should have appropriate locking to ensure no access + * conflicts to environment variables shared between #GTestDBus and other + * threads. + * + * ## Creating unit tests using GTestDBus + * + * Testing of D-Bus services can be tricky because normally we only ever run + * D-Bus services over an existing instance of the D-Bus daemon thus we + * usually don't activate D-Bus services that are not yet installed into the + * target system. The #GTestDBus object makes this easier for us by taking care + * of the lower level tasks such as running a private D-Bus daemon and looking + * up uninstalled services in customizable locations, typically in your source + * code tree. + * + * The first thing you will need is a separate service description file for the + * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory + * is a good place to put this file. + * + * The service file should list your service along with an absolute path to the + * uninstalled service executable in your source tree. Using autotools we would + * achieve this by adding a file such as `my-server.service.in` in the services + * directory and have it processed by configure. + * |[ + * [D-BUS Service] + * Name=org.gtk.GDBus.Examples.ObjectManager + * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server + * ]| + * You will also need to indicate this service directory in your test + * fixtures, so you will need to pass the path while compiling your + * test cases. Typically this is done with autotools with an added + * preprocessor flag specified to compile your tests such as: + * |[ + * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" + * ]| + * Once you have a service definition file which is local to your source tree, + * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. + * + * An example of a test fixture for D-Bus services can be found + * here: + * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c) + * + * Note that these examples only deal with isolating the D-Bus aspect of your + * service. To successfully run isolated unit tests on your service you may need + * some additional modifications to your test case fixture. For example; if your + * service uses GSettings and installs a schema then it is important that your test service + * not load the schema in the ordinary installed location (chances are that your service + * and schema files are not yet installed, or worse; there is an older version of the + * schema file sitting in the install location). + * + * Most of the time we can work around these obstacles using the + * environment. Since the environment is inherited by the D-Bus daemon + * created by #GTestDBus and then in turn inherited by any services the + * D-Bus daemon activates, using the setup routine for your fixture is + * a practical place to help sandbox your runtime environment. For the + * rather typical GSettings case we can work around this by setting + * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas + * in the above fixture_setup() routine. + * + * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved + * by compiling the schemas locally as a step before running test cases, an autotools setup might + * do the following in the directory holding schemas: + * |[ + * all-am: + * $(GLIB_COMPILE_SCHEMAS) . + * + * CLEANFILES += gschemas.compiled + * ]| */ @@ -6753,6 +7904,7 @@ * SECTION:gthreadedsocketservice * @title: GThreadedSocketService * @short_description: A threaded GSocketService + * @include: gio/gio.h * @see_also: #GSocketService. * * A #GThreadedSocketService is a simple subclass of #GSocketService @@ -6810,8 +7962,6 @@ * @title: GTlsBackend * @short_description: TLS backend implementation * @include: gio/gio.h - * - * */ @@ -6819,6 +7969,7 @@ * SECTION:gtlscertificate * @title: GTlsCertificate * @short_description: TLS certificate + * @include: gio/gio.h * @see_also: #GTlsConnection * * A certificate used for TLS authentication and encryption. @@ -6877,7 +8028,7 @@ * @include: gio/gio.h * * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load - * their certificate information from a file. It is in interface which + * their certificate information from a file. It is an interface which * TLS library specific subtypes implement. * * Since: 2.30 @@ -6947,9 +8098,9 @@ * It contains functions to do some of the UNIX socket specific * functionality like passing file descriptors. * - * Note that <filename><gio/gunixconnection.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixconnection.h>` belongs to the UNIX-specific + * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` + * pkg-config file when using it. * * Since: 2.22 */ @@ -6990,9 +8141,9 @@ * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message() * and received using g_socket_receive_message(). * - * Note that <filename><gio/gunixfdlist.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7013,9 +8164,9 @@ * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and * g_unix_connection_receive_fd(). * - * Note that <filename><gio/gunixfdmessage.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7031,9 +8182,9 @@ * asynchronous I/O. If it refers to a regular file, it will fall back * to doing asynchronous I/O in another thread.) * - * Note that <filename><gio/gunixinputstream.h></filename> belongs - * to the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7044,9 +8195,9 @@ * * Routines for managing mounted UNIX mount points and paths. * - * Note that <filename><gio/gunixmounts.h></filename> belongs to the - * UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config + * file when using it. */ @@ -7062,9 +8213,9 @@ * asynchronous I/O. If it refers to a regular file, it will fall back * to doing asynchronous I/O in another thread.) * - * Note that <filename><gio/gunixoutputstream.h></filename> belongs - * to the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file + * when using it. */ @@ -7084,9 +8235,9 @@ * errors. You can use g_unix_socket_address_abstract_names_supported() * to see if abstract names are supported. * - * Note that <filename><gio/gunixsocketaddress.h></filename> belongs to - * the UNIX-specific GIO interfaces, thus you have to use the - * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO + * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file + * when using it. */ @@ -7110,9 +8261,9 @@ * * Mounting a #GVolume instance is an asynchronous operation. For more * information about asynchronous operations, see #GAsyncResult and - * #GSimpleAsyncResult. To mount a #GVolume, first call - * g_volume_mount() with (at least) the #GVolume instance, optionally - * a #GMountOperation object and a #GAsyncReadyCallback. + * #GTask. To mount a #GVolume, first call g_volume_mount() with (at + * least) the #GVolume instance, optionally a #GMountOperation object + * and a #GAsyncReadyCallback. * * Typically, one will only want to pass %NULL for the * #GMountOperation if automounting all volumes when a desktop session @@ -7127,18 +8278,18 @@ * successfully. If an @error is present when g_volume_mount_finish() * is called, then it will be filled with any error information. * - * <para id="volume-identifier"> + * ## Volume Identifiers # {#volume-identifier} + * * It is sometimes necessary to directly access the underlying * operating system object behind a volume (e.g. for passing a volume * to an application via the commandline). For this purpose, GIO * allows to obtain an 'identifier' for the volume. There can be * different kinds of identifiers, such as Hal UDIs, filesystem labels, - * traditional Unix devices (e.g. <filename>/dev/sda2</filename>), - * uuids. GIO uses predefind strings as names for the different kinds - * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, - * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier() - * to obtain an identifier for a volume. - * </para> + * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined + * strings as names for the different kinds of identifiers: + * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. + * Use g_volume_get_identifier() to obtain an identifier for a volume. + * * * Note that #G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available * when the gvfs hal volume monitor is in use. Other volume monitors @@ -7158,10 +8309,10 @@ * on the computer. In other words, what a file selector or file manager * would show in a sidebar. * - * #GVolumeMonitor is not <link - * linkend="g-main-context-push-thread-default">thread-default-context - * aware</link>, and so should not be used other than from the main - * thread, with no thread-default-context active. + * #GVolumeMonitor is not + * [thread-default-context aware][g-main-context-push-thread-default], + * and so should not be used other than from the main thread, with no + * thread-default-context active. */ @@ -7174,9 +8325,9 @@ * #GWin32InputStream implements #GInputStream for reading from a * Windows file handle. * - * Note that <filename><gio/gwin32inputstream.h></filename> belongs - * to the Windows-specific GIO interfaces, thus you have to use the - * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO + * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file + * when using it. */ @@ -7189,9 +8340,9 @@ * #GWin32OutputStream implements #GOutputStream for writing to a * Windows file handle. * - * Note that <filename><gio/gwin32outputstream.h></filename> belongs - * to the Windows-specific GIO interfaces, thus you have to use the - * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it. + * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO + * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file + * when using it. */ @@ -8661,8 +9812,10 @@ /** * _g_io_module_get_default: * @extension_point: the name of an extension point - * @envvar: (allow-none): the name of an environment variable to override the default implementation. - * @verify_func: (allow-none): a function to call to verify that a given implementation is usable in the current environment. + * @envvar: (allow-none): the name of an environment variable to + * override the default implementation. + * @verify_func: (allow-none): a function to call to verify that + * a given implementation is usable in the current environment. * * Retrieves the default object implementing @extension_point. * @@ -8680,7 +9833,37 @@ * The result is cached after it is generated the first time, and * the function is thread-safe. * - * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations. + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. + */ + + +/** + * _g_io_module_get_default_type: + * @extension_point: the name of an extension point + * @envvar: (allow-none): the name of an environment variable to + * override the default implementation. + * @is_supported_offset: a vtable offset, or zero + * + * Retrieves the default class implementing @extension_point. + * + * If @envvar is not %NULL, and the environment variable with that + * name is set, then the implementation it specifies will be tried + * first. After that, or if @envvar is not set, all other + * implementations will be tried in order of decreasing priority. + * + * If @is_supported_offset is non-zero, then it is the offset into the + * class vtable at which there is a function that takes no arguments and + * returns a boolean. This function will be called on each candidate + * implementation to check if it is actually usable or not. + * + * The result is cached after it is generated the first time, and + * the function is thread-safe. + * + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. */ @@ -8695,6 +9878,8 @@ * the parameter type given at construction time). If the parameter * type was %NULL then @parameter must also be %NULL. * + * If the @parameter GVariant is floating, it is consumed. + * * Since: 2.28 */ @@ -9058,7 +10243,8 @@ * The caller is responsible for freeing the list with g_strfreev() when * it is no longer required. * - * Returns: (transfer full): a %NULL-terminated array of the names of the actions in the groupb + * Returns: (transfer full): a %NULL-terminated array of the names of the + * actions in the groupb * Since: 2.28 */ @@ -9125,7 +10311,8 @@ /** * g_action_map_add_action_entries: * @action_map: a #GActionMap - * @entries: a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to + * the first item in an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated * @user_data: the user data for signal connections * @@ -9134,9 +10321,7 @@ * * 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, @@ -9167,8 +10352,7 @@ * * return G_ACTION_GROUP (group); * } - * </programlisting> - * </example> + * ]| * * Since: 2.32 */ @@ -9202,6 +10386,82 @@ /** + * g_action_name_is_valid: + * @action_name: an potential action name + * + * Checks if @action_name is valid. + * + * @action_name is valid if it consists only of alphanumeric characters, + * plus '-' and '.'. The empty string is not a valid action name. + * + * It is an error to call this function with a non-utf8 @action_name. + * @action_name must not be %NULL. + * + * Returns: %TRUE if @action_name is valid + * Since: 2.38 + */ + + +/** + * g_action_parse_detailed_name: + * @detailed_name: a detailed action name + * @action_name: (out): the action name + * @target_value: (out): the target value, or %NULL for no target + * @error: a pointer to a %NULL #GError, or %NULL + * + * Parses a detailed action name into its separate name and target + * components. + * + * Detailed action names can have three formats. + * + * The first format is used to represent an action name with no target + * value and consists of just an action name containing no whitespace + * nor the characters ':', '(' or ')'. For example: "app.action". + * + * The second format is used to represent an action with a target value + * that is a non-empty string consisting only of alphanumerics, plus '-' + * and '.'. In that case, the action name and target value are + * separated by a double colon ("::"). For example: + * "app.action::target". + * + * The third format is used to represent an action with any type of + * target value, including strings. The target value follows the action + * name, surrounded in parens. For example: "app.action(42)". The + * target value is parsed using g_variant_parse(). If a tuple-typed + * value is desired, it must be specified in the same way, resulting in + * two sets of parens, for example: "app.action((1,2,3))". A string + * target can be specified this way as well: "app.action('target')". + * For strings, this third format must be used if * target value is + * empty or contains characters other than alphanumerics, '-' and '.'. + * + * Returns: %TRUE if successful, else %FALSE with @error set + * Since: 2.38 + */ + + +/** + * g_action_print_detailed_name: + * @action_name: a valid action name + * @target_value: (allow-none): a #GVariant target value, or %NULL + * + * Formats a detailed action name from @action_name and @target_value. + * + * It is an error to call this function with an invalid action name. + * + * This function is the opposite of + * g_action_parse_detailed_action_name(). It will produce a string that + * can be parsed back to the @action_name and @target_value by that + * function. + * + * See that function for the types of strings that will be printed by + * this function. + * + * Returns: a detailed format string + * Since: 2.38 + */ + + +/** * g_app_info_add_supports_type: * @appinfo: a #GAppInfo. * @content_type: a string. @@ -9232,7 +10492,8 @@ * * Checks if a supported content type can be removed from an application. * - * Returns: %TRUE if it is possible to remove supported content types from a given @appinfo, %FALSE if not. + * Returns: %TRUE if it is possible to remove supported + * content types from a given @appinfo, %FALSE if not. */ @@ -9246,8 +10507,8 @@ * 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. * @@ -9256,16 +10517,15 @@ /** - * g_app_info_delete: + * g_app_info_delete: (virtual do_delete) * @appinfo: a #GAppInfo * * 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 * Returns: %TRUE if @appinfo has been deleted * Since: 2.20 */ @@ -9286,7 +10546,7 @@ * @appinfo1: the first #GAppInfo. * @appinfo2: the second #GAppInfo. * - * Checks if two #GAppInfo<!-- -->s are equal. + * Checks if two #GAppInfos are equal. * * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. */ @@ -9299,13 +10559,12 @@ * 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. * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s. + * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos. */ @@ -9318,7 +10577,8 @@ * g_app_info_get_recommended_for_type() and * g_app_info_get_fallback_for_type(). * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. */ @@ -9329,7 +10589,8 @@ * Gets the commandline with which the application will be * started. * - * Returns: a string containing the @appinfo's commandline, or %NULL if this information is not available + * Returns: a string containing the @appinfo's commandline, + * or %NULL if this information is not available * Since: 2.20 */ @@ -9337,11 +10598,13 @@ /** * g_app_info_get_default_for_type: * @content_type: the content type to find a #GAppInfo for - * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs + * @must_support_uris: if %TRUE, the #GAppInfo is expected to + * support URIs * * Gets the default #GAppInfo for a given content type. * - * Returns: (transfer full): #GAppInfo for given @content_type or %NULL on error. + * Returns: (transfer full): #GAppInfo for given @content_type or + * %NULL on error. */ @@ -9364,7 +10627,8 @@ * * Gets a human-readable description of an installed application. * - * Returns: a string containing a description of the application @appinfo, or %NULL if none. + * Returns: a string containing a description of the + * application @appinfo, or %NULL if none. */ @@ -9375,7 +10639,8 @@ * Gets the display name of the application. The display name is often more * descriptive to the user than the name itself. * - * Returns: the display name of the application for @appinfo, or the name if no display name is available. + * Returns: the display name of the application for @appinfo, or the name if + * no display name is available. * Since: 2.24 */ @@ -9386,7 +10651,8 @@ * * Gets the executable's name for the installed application. * - * Returns: a string containing the @appinfo's application binaries name + * Returns: a string containing the @appinfo's application + * binaries name */ @@ -9398,7 +10664,8 @@ * those applications which claim to support the given content type * by MIME type subclassing and not directly. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ @@ -9409,7 +10676,8 @@ * * Gets the icon for the application. * - * Returns: (transfer none): the default #GIcon for @appinfo or %NULL if there is no default icon. + * Returns: (transfer none): the default #GIcon for @appinfo or %NULL + * if there is no default icon. */ @@ -9450,7 +10718,8 @@ * the last one for which g_app_info_set_as_last_used_for_type() has been * called. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ @@ -9466,7 +10735,8 @@ * g_app_info_add_supports_type(), but only those exported directly by * the application. * - * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): a list of content types. + * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): + * a list of content types. * Since: 2.34 */ @@ -9495,17 +10765,16 @@ * 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. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ @@ -9549,6 +10818,24 @@ /** + * g_app_info_monitor_get: + * + * Gets the #GAppInfoMonitor for the current thread-default main + * context. + * + * The #GAppInfoMonitor will emit a "changed" signal in the + * thread-default main context whenever the list of installed + * applications (as reported by g_app_info_get_all()) may have changed. + * + * You must only call g_object_unref() on the return value from under + * the same main context as you created it. + * + * Returns: (transfer full): a reference to a #GAppInfoMonitor + * Since: 2.40 + */ + + +/** * g_app_info_remove_supports_type: * @appinfo: a #GAppInfo. * @content_type: a string. @@ -9652,7 +10939,7 @@ * * 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. * * Returns: a display string for the display. */ @@ -9665,9 +10952,10 @@ * 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`. * - * Returns: (array zero-terminated=1) (transfer full): the child's environment + * Returns: (array zero-terminated=1) (transfer full): the + * child's environment * Since: 2.32 */ @@ -9679,14 +10967,13 @@ * @files: (element-type GFile): a #GList of of #GFile objects * * 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"). * - * Returns: a startup notification ID for the application, or %NULL if not supported. + * Returns: a startup notification ID for the application, or %NULL if + * not supported. */ @@ -9751,18 +11038,129 @@ /** + * g_application_add_main_option_entries: + * @application: a #GApplication + * @entries: a %NULL-terminated list of #GOptionEntrys + * + * 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 + */ + + +/** + * g_application_add_option_group: + * @application: the #GApplication + * @group: a #GOptionGroup + * + * 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 + */ + + +/** + * g_application_command_line_create_file_for_arg: + * @cmdline: a #GApplicationCommandLine + * @arg: an argument from @cmdline + * + * Creates a #GFile corresponding to a filename that was given as part + * of the invocation of @cmdline. + * + * This differs from g_file_new_for_commandline_arg() in that it + * resolves relative pathnames using the current working directory of + * the invoking process rather than the local process. + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 + */ + + +/** * g_application_command_line_get_arguments: * @cmdline: a #GApplicationCommandLine * @argc: (out) (allow-none): the length of the arguments array, or %NULL * * 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(). * - * Returns: (array length=argc) (transfer full): the string array containing the arguments (the argv) + * Returns: (array length=argc) (transfer full): the string array + * containing the arguments (the argv) * Since: 2.28 */ @@ -9805,7 +11203,8 @@ * See g_application_command_line_getenv() if you are only interested * in the value of a single environment variable. * - * Returns: (array zero-terminated=1) (transfer none): the environment strings, or %NULL if they were not sent + * Returns: (array zero-terminated=1) (transfer none): the environment + * strings, or %NULL if they were not sent * Since: 2.28 */ @@ -9834,6 +11233,25 @@ /** + * g_application_command_line_get_options_dict: + * @cmdline: a #GApplicationCommandLine + * + * 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. + * + * Returns: (transfer none): a #GVariantDict with the options + * Since: 2.40 + */ + + +/** * g_application_command_line_get_platform_data: * @cmdline: #GApplicationCommandLine * @@ -9852,6 +11270,26 @@ /** + * g_application_command_line_get_stdin: + * @cmdline: a #GApplicationCommandLine + * + * Gets the stdin of the invoking process. + * + * The #GInputStream can be used to read data passed to the standard + * input of the invoking process. + * This doesn't work on all platforms. Presently, it is only available + * on UNIX when using a DBus daemon capable of passing file descriptors. + * If stdin is not available then %NULL will be returned. In the + * future, support may be expanded to other platforms. + * + * You must only call this function once per commandline invocation. + * + * Returns: (transfer full): a #GInputStream for stdin + * Since: 2.34 + */ + + +/** * g_application_command_line_getenv: * @cmdline: a #GApplicationCommandLine * @name: the environment variable to get @@ -10098,27 +11536,51 @@ * * 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. * * Returns: %TRUE if @application_id is valid */ /** + * g_application_mark_busy: + * @application: a #GApplication + * + * Increases the busy count of @application. + * + * Use this function to indicate that the application is busy, for instance + * while a long running operation is pending. + * + * The busy state will be exposed to other processes, so a session shell will + * use that information to indicate the state to the user (e.g. with a + * spinner). + * + * To cancel the busy indication, use g_application_unmark_busy(). + * + * Since: 2.38 + */ + + +/** * g_application_new: * @application_id: (allow-none): the application id * @flags: the application flags * * Creates a new #GApplication instance. * - * This function calls g_type_init() for you. - * * If non-%NULL, the application id must be valid. See * g_application_id_is_valid(). * @@ -10240,66 +11702,76 @@ * 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 * non-zero then the default main context is iterated until the use count * falls to zero, at which point 0 is returned. * - * If the %G_APPLICATION_IS_SERVICE flag is set, then the exiting at - * use count of zero is delayed for a while (ie: the instance stays - * around to provide its <emphasis>service</emphasis> to others). + * If the %G_APPLICATION_IS_SERVICE flag is set, then the service will + * run for as much as 10 seconds with a use count of zero while waiting + * for the message that caused the activation to arrive. After that, + * if the use count falls to zero the application will exit immediately, + * except in the case that g_application_set_inactivity_timeout() is in + * use. + * + * This function sets the prgname (g_set_prgname()), if not already set, + * to the basename of argv[0]. Since 2.38, if %G_APPLICATION_IS_SERVICE + * is specified, the prgname is set to the application ID. The main + * impact of this is is that the wmclass of windows created by Gtk+ will + * be set accordingly, which helps the window manager determine which + * application is showing the window. + * + * Since 2.40, applications that are not explicitly flagged as services + * or launchers (ie: neither %G_APPLICATION_IS_SERVICE or + * %G_APPLICATION_IS_LAUNCHER are given as flags) will check (from the + * default handler for local_command_line) if "--gapplication-service" + * was given in the command line. If this flag is present then normal + * commandline processing is interrupted and the + * %G_APPLICATION_IS_SERVICE flag is set. This provides a "compromise" + * solution whereby running an application directly from the commandline + * will invoke it in the normal way (which can be useful for debugging) + * while still allowing applications to be D-Bus activated in service + * mode. The D-Bus service file should invoke the executable with + * "--gapplication-service" as the sole commandline argument. This + * approach is suitable for use by most graphical applications but + * should not be used from applications like editors that need precise + * control over when processes invoked via the commandline will exit and + * what their exit status will be. * * Returns: the exit status * Since: 2.28 @@ -10307,6 +11779,43 @@ /** + * g_application_send_notification: + * @application: a #GApplication + * @id: (allow-none): id of the notification, or %NULL + * @notification: the #GNotification to send + * + * Sends a notification on behalf of @application to the desktop shell. + * There is no guarantee that the notification is displayed immediately, + * or even at all. + * + * Notifications may persist after the application exits. It will be + * D-Bus-activated when the notification or one of its actions is + * activated. + * + * Modifying @notification after this call has no effect. However, the + * object can be reused for a later call to this function. + * + * @id may be any string that uniquely identifies the event for the + * application. It does not need to be in any special format. For + * example, "new-message" might be appropriate for a notification about + * new messages. + * + * If a previous notification was sent with the same @id, it will be + * replaced with @notification and shown again as if it was a new + * notification. This works even for notifications sent from a previous + * execution of the application, as long as @id is the same string. + * + * @id may be %NULL, but it is impossible to replace or withdraw + * notifications without an id. + * + * If @notification is no longer relevant, it can be withdrawn with + * g_application_withdraw_notification(). + * + * Since: 2.40 + */ + + +/** * g_application_set_action_group: * @application: a #GApplication * @action_group: (allow-none): a #GActionGroup, or %NULL @@ -10315,7 +11824,11 @@ * Now there is #GActionMap for that. * * Since: 2.28 - * Deprecated: 2.32:Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead. + * Deprecated: 2.32: Use the #GActionMap interface instead. Never ever + * mix use of this API with use of #GActionMap on the same @application + * or things will go very badly wrong. This function is known to + * introduce buggy behaviour (ie: signals not emitted on changes to the + * action group), so you should really use #GActionMap instead. */ @@ -10386,9 +11899,48 @@ /** + * g_application_unmark_busy: + * @application: a #GApplication + * + * Decreases the busy count of @application. + * + * When the busy count reaches zero, the new state will be propagated + * to other processes. + * + * This function must only be called to cancel the effect of a previous + * call to g_application_mark_busy(). + * + * Since: 2.38 + */ + + +/** + * g_application_withdraw_notification: + * @application: a #GApplication + * @id: id of a previously sent notification + * + * Withdraws a notification that was sent with + * g_application_send_notification(). + * + * This call does nothing if a notification with @id doesn't exist or + * the notification was never sent. + * + * This function works even for notifications sent in previous + * executions of this application, as long @id is the same as it was for + * the sent notification. + * + * Note that notifications are dismissed when the user clicks on one + * of the buttons in a notification or triggers its default action, so + * there is no need to explicitly withdraw the notification in that case. + * + * Since: 2.40 + */ + + +/** * g_async_initable_init_async: * @initable: a #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -10435,12 +11987,14 @@ * g_async_initable_init_finish: * @initable: a #GAsyncInitable. * @res: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes asynchronous initialization and returns the result. * See g_async_initable_init_async(). * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. * Since: 2.22 */ @@ -10448,12 +12002,15 @@ /** * g_async_initable_new_async: * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function - * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties - * @...: the value of the first property, followed by other property value pairs, and ended by %NULL. + * @first_property_name: (allow-none): the name of the first property, or %NULL if no + * properties + * @...: the value of the first property, followed by other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GAsyncInitable object. This is * similar to g_object_new() but also initializes the object asynchronously. @@ -10475,7 +12032,8 @@ * Finishes the async construction for the various g_async_initable_new * calls, returning the created object or %NULL on error. * - * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref(). + * Returns: (type GObject.Object) (transfer full): a newly created #GObject, + * or %NULL on error. Free with g_object_unref(). * Since: 2.22 */ @@ -10483,11 +12041,13 @@ /** * g_async_initable_new_valist_async: * @object_type: a #GType supporting #GAsyncInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, followed by + * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function * * Helper function for constructing #GAsyncInitable object. This is @@ -10507,9 +12067,10 @@ * @object_type: a #GType supporting #GAsyncInitable. * @n_parameters: the number of parameters in @parameters * @parameters: the parameters to use to construct the object - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function * * Helper function for constructing #GAsyncInitable object. This is @@ -10529,7 +12090,8 @@ * * Gets the source object from a #GAsyncResult. * - * Returns: (transfer full): a new reference to the source object for the @res, or %NULL if there is none. + * Returns: (transfer full): a new reference to the source object for the @res, + * or %NULL if there is none. */ @@ -10551,7 +12113,8 @@ * Checks if @res has the given @source_tag (generally a function * pointer indicating the function @res was created by). * - * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if not. + * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if + * not. * Since: 2.34 */ @@ -10565,15 +12128,15 @@ * 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. * - * Returns: %TRUE if @error is has been filled in with an error from @res, %FALSE if not. + * Returns: %TRUE if @error is has been filled in with an error from + * @res, %FALSE if not. * Since: 2.34 */ @@ -10610,7 +12173,8 @@ * For the asynchronous, non-blocking, version of this function, see * g_buffered_input_stream_fill_async(). * - * Returns: the number of bytes read into @stream's buffer, up to @count, or -1 on error. + * Returns: the number of bytes read into @stream's buffer, up to @count, + * or -1 on error. */ @@ -10618,7 +12182,7 @@ * g_buffered_input_stream_fill_async: * @stream: a #GBufferedInputStream * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer @@ -10690,7 +12254,8 @@ /** * g_buffered_input_stream_peek: * @stream: a #GBufferedInputStream - * @buffer: (array length=count) (element-type guint8): a pointer to an allocated chunk of memory + * @buffer: (array length=count) (element-type guint8): a pointer to + * an allocated chunk of memory * @offset: a #gsize * @count: a #gsize * @@ -10710,7 +12275,8 @@ * buffer must not be modified and will become invalid when reading from * the stream or filling the buffer. * - * Returns: (array length=count) (element-type guint8) (transfer none): read-only buffer + * Returns: (array length=count) (element-type guint8) (transfer none): + * read-only buffer */ @@ -10755,7 +12321,8 @@ * * Checks if the buffer automatically grows as data is added. * - * Returns: %TRUE if the @stream's buffer automatically grows, %FALSE otherwise. + * Returns: %TRUE if the @stream's buffer automatically grows, + * %FALSE otherwise. */ @@ -10813,10 +12380,10 @@ /** * g_bus_get: - * @bus_type: A #GBusType. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * @bus_type: a #GBusType + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * * Asynchronously connects to the message bus specified by @bus_type. * @@ -10832,8 +12399,9 @@ /** * g_bus_get_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_bus_get() + * @error: return location for error or %NULL * * Finishes an operation started with g_bus_get(). * @@ -10846,16 +12414,17 @@ * Note that the returned #GDBusConnection object will (usually) have * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ /** * g_bus_get_sync: - * @bus_type: A #GBusType. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @bus_type: a #GBusType + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously connects to the message bus specified by @bus_type. * Note that the returned object may shared with other callers, @@ -10874,51 +12443,51 @@ * Note that the returned #GDBusConnection object will (usually) have * the #GDBusConnection:exit-on-close property set to %TRUE. * - * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ /** * g_bus_own_name: - * @bus_type: The type of bus to own a name on. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_handler: (allow-none): Handler to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL. - * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL. + * @bus_type: the type of bus to own a name on + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @bus_acquired_handler: (allow-none): handler to invoke when connected to the bus of type @bus_type or %NULL + * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL + * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL + * @user_data: user data to pass to handlers + * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL * * 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 @@ -10937,71 +12506,78 @@ * 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. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ /** * g_bus_own_name_on_connection: - * @connection: A #GDBusConnection. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL. - * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL. - * @user_data: User data to pass to handlers. - * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL. + * @connection: a #GDBusConnection + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL + * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL + * @user_data: user data to pass to handlers + * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL * * Like g_bus_own_name() but takes a #GDBusConnection instead of a * #GBusType. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name * Since: 2.26 */ /** - * g_bus_own_name_on_connection_with_closures: - * @connection: A #GDBusConnection. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection) + * @connection: a #GDBusConnection + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is + * acquired or %NULL + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost + * or %NULL * - * 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. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. - * Rename to: g_bus_own_name_on_connection + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ /** - * g_bus_own_name_with_closures: - * @bus_type: The type of bus to own a name on. - * @name: The well-known name to own. - * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * g_bus_own_name_with_closures: (rename-to g_bus_own_name) + * @bus_type: the type of bus to own a name on + * @name: the well-known name to own + * @flags: a set of flags from the #GBusNameOwnerFlags enumeration + * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to + * the bus of type @bus_type or %NULL + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is + * acquired or %NULL + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or + * %NULL * * Version of g_bus_own_name() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. - * Rename to: g_bus_own_name + * Returns: an identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ /** * g_bus_unown_name: - * @owner_id: An identifier obtained from g_bus_own_name() + * @owner_id: an identifier obtained from g_bus_own_name() * * Stops owning a name. * @@ -11032,9 +12608,9 @@ * 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 @@ -11053,13 +12629,14 @@ * 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. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ @@ -11077,46 +12654,74 @@ * Like g_bus_watch_name() but takes a #GDBusConnection instead of a * #GBusType. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ /** - * g_bus_watch_name_on_connection_with_closures: + * g_bus_watch_name_on_connection_with_closures: (rename-to g_bus_watch_name_on_connection) * @connection: A #GDBusConnection. * @name: The name (well-known or unique) to watch. * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known + * to not exist or %NULL. * * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. - * Rename to: g_bus_watch_name_on_connection + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ /** - * g_bus_watch_name_with_closures: + * g_bus_watch_name_with_closures: (rename-to g_bus_watch_name) * @bus_type: The type of bus to watch a name on. * @name: The name (well-known or unique) to watch. * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known + * to not exist or %NULL. * * Version of g_bus_watch_name() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. - * Rename to: g_bus_watch_name + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ /** + * g_bytes_icon_get_bytes: + * @icon: a #GIcon. + * + * Gets the #GBytes associated with the given @icon. + * + * Returns: (transfer none): a #GBytes, or %NULL. + * Since: 2.38 + */ + + +/** + * g_bytes_icon_new: + * @bytes: a #GBytes. + * + * Creates a new icon for a bytes. + * + * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given + * @bytes, or %NULL on error. + * Since: 2.38 + */ + + +/** * g_cancellable_cancel: * @cancellable: a #GCancellable object. * @@ -11158,7 +12763,13 @@ * * See #GCancellable::cancelled for details on how to use this. * - * Returns: The id of the signal handler or 0 if @cancellable has already been cancelled. + * Since GLib 2.40, the lock protecting @cancellable is not held when + * @callback is invoked. This lifts a restriction in place for + * earlier GLib versions which now makes it easier to write cleanup + * code that unconditionally invokes e.g. g_cancellable_cancel(). + * + * Returns: The id of the signal handler or 0 if @cancellable has already + * been cancelled. * Since: 2.22 */ @@ -11192,7 +12803,8 @@ * * Gets the top cancellable from the stack. * - * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL if the stack is empty. + * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL + * if the stack is empty. */ @@ -11214,7 +12826,8 @@ * * See also g_cancellable_make_pollfd(). * - * Returns: A valid file descriptor. %-1 if the file descriptor is not supported, or on errors. + * Returns: A valid file descriptor. %-1 if the file descriptor + * is not supported, or on errors. */ @@ -11224,7 +12837,8 @@ * * Checks if a cancellable job has been cancelled. * - * Returns: %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled. + * Returns: %TRUE if @cancellable is cancelled, + * FALSE if called with %NULL or if item is not cancelled. */ @@ -11252,7 +12866,8 @@ * readable status. Reading to unset the readable status is done * with g_cancellable_reset(). * - * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable. + * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on + * failure to prepare the cancellable. * Since: 2.22 */ @@ -11408,7 +13023,8 @@ * Checks if a content type can be executable. Note that for instance * things like text files can be executables (i.e. scripts and batch files). * - * Returns: %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise. + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. */ @@ -11419,7 +13035,8 @@ * * Compares two content types for equality. * - * Returns: %TRUE if the two strings are identical or equivalent, %FALSE otherwise. + * Returns: %TRUE if the two strings are identical or equivalent, + * %FALSE otherwise. */ @@ -11429,7 +13046,8 @@ * * Tries to find a content type based on the mime type name. * - * Returns: (allow-none): Newly allocated string with content type or %NULL. Free with g_free() + * Returns: (allow-none): Newly allocated string with content type + * or %NULL. Free with g_free() * Since: 2.18 */ @@ -11440,7 +13058,8 @@ * * Gets the human readable description of the content type. * - * Returns: a short description of the content type @type. Free the returned string with g_free() + * Returns: a short description of the content type @type. Free the + * returned string with g_free() */ @@ -11450,10 +13069,12 @@ * * 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. * - * Returns: (allow-none): the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free() + * Returns: (allow-none): the registered generic icon name for the given @type, + * or %NULL if unknown. Free with g_free() * Since: 2.34 */ @@ -11464,7 +13085,8 @@ * * Gets the icon for a content type. * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned object with g_object_unref() + * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned + * object with g_object_unref() */ @@ -11474,7 +13096,8 @@ * * Gets the mime type for the content type, if one is registered. * - * Returns: (allow-none): the registered mime type for the given @type, or %NULL if unknown. + * Returns: (allow-none): the registered mime type for the given @type, + * or %NULL if unknown. */ @@ -11484,7 +13107,8 @@ * * Gets the symbolic icon for a content type. * - * Returns: (transfer full): symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref() + * Returns: (transfer full): symbolic #GIcon corresponding to the content type. + * Free the returned object with g_object_unref() * Since: 2.34 */ @@ -11494,14 +13118,16 @@ * @filename: (allow-none): a string, or %NULL * @data: (allow-none) (array length=data_size): a stream of data, or %NULL * @data_size: the size of @data - * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL + * @result_uncertain: (allow-none) (out): return location for the certainty + * of the result, or %NULL * * Guesses the content type based on example data. If the function is * uncertain, @result_uncertain will be set to %TRUE. Either @filename * or @data may be %NULL, in which case the guess will be based solely * on the other argument. * - * Returns: a string indicating a guessed content type for the given data. Free with g_free() + * Returns: a string indicating a guessed content type for the + * given data. Free with g_free() */ @@ -11515,13 +13141,15 @@ * * 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 * g_mount_guess_content_type(). * - * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated array of zero or more content types. Free with g_strfreev() + * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated + * array of zero or more content types. Free with g_strfreev() * Since: 2.18 */ @@ -11533,7 +13161,8 @@ * * Determines if @type is a subset of @supertype. * - * Returns: %TRUE if @type is a kind of @supertype, %FALSE otherwise. + * Returns: %TRUE if @type is a kind of @supertype, + * %FALSE otherwise. */ @@ -11554,18 +13183,18 @@ * * 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). * - * Returns: (element-type utf8) (transfer full): #GList of the registered content types + * Returns: (element-type utf8) (transfer full): list of the registered + * content types */ /** * g_converter_convert: * @converter: a #GConverter. - * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert. + * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer + * containing the data to convert. * @inbuf_size: the number of bytes in @inbuf * @outbuf: a buffer to write converted data in. * @outbuf_size: the number of bytes in @outbuf, must be at least one @@ -11730,12 +13359,32 @@ * logged) to use this method if there is no #GCredentials support for * the OS or if @native_type isn't supported by the OS. * - * Returns: The pointer to native credentials or %NULL if the operation there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Do not free the returned data, it is owned by @credentials. + * Returns: The pointer to native credentials or %NULL if the + * operation there is no #GCredentials support for the OS or if + * @native_type isn't supported by the OS. Do not free the returned + * data, it is owned by @credentials. * Since: 2.26 */ /** + * g_credentials_get_unix_pid: + * @credentials: A #GCredentials + * @error: Return location for error or %NULL. + * + * Tries to get the UNIX process identifier from @credentials. This + * method is only available on UNIX platforms. + * + * This operation can fail if #GCredentials is not supported on the + * OS or if the native credentials type does not contain information + * about the UNIX process ID. + * + * Returns: The UNIX process ID, or -1 if @error is set. + * Since: 2.36 + */ + + +/** * g_credentials_get_unix_user: * @credentials: A #GCredentials * @error: Return location for error or %NULL. @@ -11763,7 +13412,8 @@ * This operation can fail if #GCredentials is not supported on the * the OS. * - * Returns: %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set. + * Returns: %TRUE if @credentials and @other_credentials has the same + * user, %FALSE otherwise or if @error is set. * Since: 2.26 */ @@ -11807,7 +13457,8 @@ * * This operation can fail if #GCredentials is not supported on the * OS or if the native credentials type does not contain information - * about the UNIX user. + * about the UNIX user. It can also fail if the OS does not allow the + * use of "spoofed" credentials. * * Returns: %TRUE if @uid was set, %FALSE if error is set. * Since: 2.26 @@ -11865,7 +13516,8 @@ * * Reads an unsigned 8-bit/1-byte value from @stream. * - * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 + * if an error occurred. */ @@ -11880,7 +13532,8 @@ * In order to get the correct byte order for this read operation, * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). * - * Returns: a signed 16-bit/2-byte value read from @stream or %0 if an error occurred. + * Returns: a signed 16-bit/2-byte value read from @stream or %0 if + * an error occurred. */ @@ -11899,7 +13552,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if an error occurred. + * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ @@ -11918,7 +13572,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a signed 64-bit/8-byte value read from @stream or %0 if an error occurred. + * Returns: a signed 64-bit/8-byte value read from @stream or %0 if + * an error occurred. */ @@ -11937,14 +13592,19 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a + * NUL terminated byte array with the line that was read in (without + * the newlines). Set @length to a #gsize to get the length of the + * read line. On an error, it will return %NULL and @error will be + * set. If there's no content to read, it will still return %NULL, + * but @error won't be set. */ /** * g_data_input_stream_read_line_async: * @stream: a given #GDataInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -11972,7 +13632,12 @@ * string encoding in g_data_input_stream_read_line() applies here as * well. * - * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL-terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a + * NUL-terminated byte array with the line that was read in + * (without the newlines). Set @length to a #gsize to get the + * length of the read line. On an error, it will return %NULL and + * @error will be set. If there's no content to read, it will + * still return %NULL, but @error won't be set. * Since: 2.20 */ @@ -11987,7 +13652,12 @@ * Finish an asynchronous call started by * g_data_input_stream_read_line_async(). * - * Returns: (transfer full): a string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full): a string with the line that was read in + * (without the newlines). Set @length to a #gsize to get the length + * of the read line. On an error, it will return %NULL and @error + * will be set. For UTF-8 conversion errors, the set error domain is + * %G_CONVERT_ERROR. If there's no content to read, it will still + * return %NULL, but @error won't be set. * Since: 2.30 */ @@ -12005,7 +13675,12 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set. + * Returns: (transfer full): a NUL terminated UTF-8 string with the + * line that was read in (without the newlines). Set @length to a + * #gsize to get the length of the read line. On an error, it will + * return %NULL and @error will be set. For UTF-8 conversion errors, + * the set error domain is %G_CONVERT_ERROR. If there's no content to + * read, it will still return %NULL, but @error won't be set. * Since: 2.30 */ @@ -12021,7 +13696,8 @@ * In order to get the correct byte order for this read operation, * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order(). * - * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if + * an error occurred. */ @@ -12040,7 +13716,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ @@ -12059,7 +13736,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if an error occurred. + * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if + * an error occurred. */ @@ -12083,7 +13761,10 @@ * g_data_input_stream_read_upto() instead, but note that that function * does not consume the stop character. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. */ @@ -12091,7 +13772,7 @@ * g_data_input_stream_read_until_async: * @stream: a given #GDataInputStream. * @stop_chars: characters to terminate the read. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -12127,7 +13808,10 @@ * g_data_input_stream_read_until_async(). * * Since: 2.20 - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. */ @@ -12135,7 +13819,8 @@ * g_data_input_stream_read_upto: * @stream: a #GDataInputStream * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is + * nul-terminated * @length: (out): a #gsize to get the length of the data read in * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @error: #GError for error reporting @@ -12144,14 +13829,17 @@ * 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 * specified. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error * Since: 2.26 */ @@ -12160,8 +13848,9 @@ * g_data_input_stream_read_upto_async: * @stream: a #GDataInputStream * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is + * nul-terminated + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -12170,8 +13859,8 @@ * 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 @@ -12195,11 +13884,14 @@ * 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. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error. + * Returns: (transfer full): a string with the data that was read + * before encountering any of the stop characters. Set @length to + * a #gsize to get the length of the string. This function will + * return %NULL on an error. * Since: 2.24 */ @@ -12386,16 +14078,36 @@ /** + * g_dbus_address_escape_value: + * @string: an unescaped string to be included in a D-Bus address + * as the value in a key-value pair + * + * 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 "/run/bus-for-:0", + * this function would return "/run/bus-for-%3A0", + * which could be used in a D-Bus address like + * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0". + * + * Returns: (transfer full): a copy of @string with all + * non-optionally-escaped bytes escaped + * Since: 2.36 + */ + + +/** * g_dbus_address_get_for_bus_sync: - * @bus_type: A #GBusType. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @bus_type: a #GBusType + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously looks up the D-Bus address for the well-known message * bus instance specified by @bus_type. This may involve using various * platform specific mechanisms. * - * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set. + * Returns: a valid D-Bus address string for @bus_type or %NULL if + * @error is set * Since: 2.26 */ @@ -12461,7 +14173,7 @@ * * Looks up the value of an annotation. * - * This cost of this function is O(n) in number of annotations. + * The cost of this function is O(n) in number of annotations. * * Returns: The value or %NULL if not found. Do not free, it is owned by @annotations. * Since: 2.26 @@ -12519,7 +14231,7 @@ /** * g_dbus_auth_observer_allow_mechanism: * @observer: A #GDBusAuthObserver. - * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>. + * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`. * * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer. * @@ -12553,10 +14265,11 @@ /** * g_dbus_connection_add_filter: - * @connection: A #GDBusConnection. - * @filter_function: A filter function. - * @user_data: User data to pass to @filter_function. - * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL. + * @connection: a #GDBusConnection + * @filter_function: a filter function + * @user_data: user data to pass to @filter_function + * @user_data_free_func: function to free @user_data with when filter + * is removed or %NULL * * Adds a message filter. Filters are handlers that are run on all * incoming and outgoing messages, prior to standard dispatch. Filters @@ -12579,25 +14292,31 @@ * message. Similary, if a filter consumes an outgoing message, the * message will not be sent to the other peer. * - * Returns: A filter identifier that can be used with g_dbus_connection_remove_filter(). + * Returns: a filter identifier that can be used with + * g_dbus_connection_remove_filter() * Since: 2.26 */ /** * g_dbus_connection_call: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL if + * @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request + * is satisfied or %NULL if you don't care about the result of the + * method invocation + * @user_data: the data to pass to @callback * * Asynchronously invokes the @method_name method on the * @interface_name D-Bus interface on the remote object at @@ -12615,7 +14334,7 @@ * * 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", @@ -12632,8 +14351,9 @@ * 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 @@ -12648,30 +14368,34 @@ /** * g_dbus_connection_call_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ /** * g_dbus_connection_call_sync: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL if + * @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously invokes the @method_name method on the * @interface_name D-Bus interface on the remote object at @@ -12690,7 +14414,7 @@ * * 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", @@ -12703,32 +14427,38 @@ * G_DBUS_CALL_FLAGS_NONE, * -1, * NULL, - * &error); + * &error); * ]| * * The calling thread is blocked until a reply is received. See * g_dbus_connection_call() for the asynchronous version of * this method. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ /** * g_dbus_connection_call_with_unix_fd_list: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @fd_list: (allow-none): A #GUnixFDList or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL if + * @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for the method + * or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @fd_list: (allow-none): a #GUnixFDList or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't * care about the result of the + * method invocation * @user_data: The data to pass to @callback. * * Like g_dbus_connection_call() but also takes a #GUnixFDList object. @@ -12741,49 +14471,56 @@ /** * g_dbus_connection_call_with_unix_fd_list_finish: - * @connection: A #GDBusConnection. - * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + * g_dbus_connection_call_with_unix_fd_list() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ /** * g_dbus_connection_call_with_unix_fd_list_sync: - * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to invoke method on. - * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. - * @reply_type: (allow-none): The expected type of the reply, or %NULL. - * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @fd_list: (allow-none): A #GUnixFDList or %NULL. - * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @bus_name: (allow-none): a unique or well-known bus name or %NULL + * if @connection is not a message bus connection + * @object_path: path of remote object + * @interface_name: D-Bus interface to invoke method on + * @method_name: the name of the method to invoke + * @parameters: (allow-none): a #GVariant tuple with parameters for + * the method or %NULL if not passing parameters + * @reply_type: (allow-none): the expected type of the reply, or %NULL + * @flags: flags from the #GDBusCallFlags enumeration + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @fd_list: (allow-none): a #GUnixFDList or %NULL + * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ /** * g_dbus_connection_close: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback * * Closes @connection. Note that this never causes the process to * exit (this might only happen if the other end of a shared message @@ -12798,16 +14535,16 @@ * %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 @@ -12816,42 +14553,45 @@ /** * g_dbus_connection_close_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_close() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_close(). * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_close_sync: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously closees @connection. The calling thread is blocked * until this is done. See g_dbus_connection_close() for the * asynchronous version of this method and more details about what it * does. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_emit_signal: - * @connection: A #GDBusConnection. - * @destination_bus_name: (allow-none): The unique bus name for the destination for the signal or %NULL to emit to all listeners. - * @object_path: Path of remote object. - * @interface_name: D-Bus interface to emit a signal on. - * @signal_name: The name of the signal to emit. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @destination_bus_name: (allow-none): the unique bus name for the destination + * for the signal or %NULL to emit to all listeners + * @object_path: path of remote object + * @interface_name: D-Bus interface to emit a signal on + * @signal_name: the name of the signal to emit + * @parameters: (allow-none): a #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters + * @error: Return location for error or %NULL * * Emits a signal. * @@ -12859,7 +14599,7 @@ * * This can only fail if @parameters is not compatible with the D-Bus protocol. * - * Returns: %TRUE unless @error is set. + * Returns: %TRUE unless @error is set * Since: 2.26 */ @@ -12910,7 +14650,7 @@ * The implemented D-Bus API should be considered private. * It is subject to change in the future. * - * An object path can only have one action group exported on it. If this + * An object path can only have one menu model exported on it. If this * constraint is violated, the export will fail and 0 will be * returned (with @error set accordingly). * @@ -12925,25 +14665,25 @@ /** * g_dbus_connection_flush: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the + * request is satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback * * 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 @@ -12952,72 +14692,75 @@ /** * g_dbus_connection_flush_finish: - * @connection: A #GDBusConnection. - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush(). - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_flush() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_flush(). * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_flush_sync: - * @connection: A #GDBusConnection. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously flushes @connection. The calling thread is blocked * until this is done. See g_dbus_connection_flush() for the * asynchronous version of this method and more details about what it * does. * - * Returns: %TRUE if the operation succeeded, %FALSE if @error is set. + * Returns: %TRUE if the operation succeeded, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_get_capabilities: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets the capabilities negotiated with the remote peer * - * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration. + * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration * Since: 2.26 */ /** * g_dbus_connection_get_exit_on_close: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets whether the process is terminated when @connection is * closed by the remote peer. See * #GDBusConnection:exit-on-close for more details. * - * Returns: Whether the process is terminated when @connection is closed by the remote peer. + * Returns: whether the process is terminated when @connection is + * closed by the remote peer * Since: 2.26 */ /** * g_dbus_connection_get_guid: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * The GUID of the peer performing the role of server when * authenticating. See #GDBusConnection:guid for more details. * - * Returns: The GUID. Do not free this string, it is owned by @connection. + * Returns: The GUID. Do not free this string, it is owned by + * @connection. * Since: 2.26 */ /** * g_dbus_connection_get_last_serial: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Retrieves the last serial number assigned to a #GDBusMessage on * the current thread. This includes messages sent via both low-level @@ -13025,14 +14768,15 @@ * high-level API such as g_dbus_connection_emit_signal(), * g_dbus_connection_call() or g_dbus_proxy_call(). * - * Returns: the last used serial or zero when no message has been sent within the current thread. + * Returns: the last used serial or zero when no message has been sent + * within the current thread * Since: 2.34 */ /** * g_dbus_connection_get_peer_credentials: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets the credentials of the authenticated peer. This will always * return %NULL unless @connection acted as a server @@ -13044,7 +14788,8 @@ * each application is a client. So this method will always return * %NULL for message bus clients. * - * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection. + * Returns: (transfer none): a #GCredentials or %NULL if not available. + * Do not free this object, it is owned by @connection. * Since: 2.26 */ @@ -13066,37 +14811,39 @@ /** * g_dbus_connection_get_unique_name: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets the unique name of @connection as assigned by the message * bus. This can also be used to figure out if @connection is a * message bus connection. * - * Returns: The unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection. + * Returns: the unique name or %NULL if @connection is not a message + * bus connection. Do not free this string, it is owned by + * @connection. * Since: 2.26 */ /** * g_dbus_connection_is_closed: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * Gets whether @connection is closed. * - * Returns: %TRUE if the connection is closed, %FALSE otherwise. + * Returns: %TRUE if the connection is closed, %FALSE otherwise * Since: 2.26 */ /** * g_dbus_connection_new: - * @stream: A #GIOStream. - * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * @stream: a #GIOStream + * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages * with the end represented by @stream. @@ -13125,24 +14872,26 @@ /** * g_dbus_connection_new_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback + * passed to g_dbus_connection_new(). + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_new(). * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_new_for_address: - * @address: A D-Bus address. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: A #GAsyncReadyCallback to call when the request is satisfied. - * @user_data: The data to pass to @callback. + * @address: a D-Bus address + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to @callback * * Asynchronously connects and sets up a D-Bus client connection for * exchanging D-Bus messages with an endpoint specified by @address @@ -13171,23 +14920,25 @@ /** * g_dbus_connection_new_for_address_finish: - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed + * to g_dbus_connection_new() + * @error: return location for error or %NULL * * Finishes an operation started with g_dbus_connection_new_for_address(). * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_new_for_address_sync: - * @address: A D-Bus address. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @address: a D-Bus address + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously connects and sets up a D-Bus client connection for * exchanging D-Bus messages with an endpoint specified by @address @@ -13205,19 +14956,20 @@ * If @observer is not %NULL it may be used to control the * authentication process. * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_new_sync: - * @stream: A #GIOStream. - * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL. - * @flags: Flags describing how to make the connection. - * @observer: (allow-none): A #GDBusAuthObserver or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @stream: a #GIOStream + * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL + * @flags: flags describing how to make the connection + * @observer: (allow-none): a #GDBusAuthObserver or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously sets up a D-Bus connection for exchanging D-Bus messages * with the end represented by @stream. @@ -13235,37 +14987,38 @@ * This is a synchronous failable constructor. See * g_dbus_connection_new() for the asynchronous version. * - * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). * Since: 2.26 */ /** * g_dbus_connection_register_object: - * @connection: A #GDBusConnection. - * @object_path: The object path to register at. - * @interface_info: Introspection data for the interface. - * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL. - * @user_data: (allow-none): Data to pass to functions in @vtable. - * @user_data_free_func: Function to call when the object path is unregistered. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @object_path: the object path to register at + * @interface_info: introspection data for the interface + * @vtable: (allow-none): a #GDBusInterfaceVTable to call into or %NULL + * @user_data: (allow-none): data to pass to functions in @vtable + * @user_data_free_func: function to call when the object path is unregistered + * @error: return location for error or %NULL * * 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 @@ -13277,34 +15030,35 @@ * * 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. * - * Returns: 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() . + * Returns: 0 if @error is set, otherwise a registration id (never 0) + * that can be used with g_dbus_connection_unregister_object() * Since: 2.26 */ /** * g_dbus_connection_register_subtree: - * @connection: A #GDBusConnection. - * @object_path: The object path to register the subtree at. - * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree. - * @flags: Flags used to fine tune the behavior of the subtree. - * @user_data: Data to pass to functions in @vtable. - * @user_data_free_func: Function to call when the subtree is unregistered. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @object_path: the object path to register the subtree at + * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and + * dispatch nodes in the subtree + * @flags: flags used to fine tune the behavior of the subtree + * @user_data: data to pass to functions in @vtable + * @user_data_free_func: function to call when the subtree is unregistered + * @error: return location for error or %NULL * - * 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 @@ -13319,9 +15073,9 @@ * #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. @@ -13330,16 +15084,17 @@ * 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. * - * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) that can be used with g_dbus_connection_unregister_subtree() . + * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) + * that can be used with g_dbus_connection_unregister_subtree() . * Since: 2.26 */ @@ -13357,11 +15112,12 @@ /** * g_dbus_connection_send_message: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage - * @flags: Flags affecting how the message is sent. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent + * @out_serial: (out) (allow-none): return location for serial number assigned + * to @message when sending it or %NULL + * @error: Return location for error or %NULL * * Asynchronously sends @message to the peer represented by @connection. * @@ -13376,28 +15132,32 @@ * %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. * - * Returns: %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set. + * Returns: %TRUE if the message was well-formed and queued for + * transmission, %FALSE if @error is set * Since: 2.26 */ /** * g_dbus_connection_send_message_with_reply: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage. - * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. - * @user_data: The data to pass to @callback. + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @out_serial: (out) (allow-none): return location for serial number assigned + * to @message when sending it or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call when the request + * is satisfied or %NULL if you don't care about the result + * @user_data: The data to pass to @callback * * Asynchronously sends @message to the peer represented by @connection. * @@ -13413,8 +15173,9 @@ * 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. @@ -13422,9 +15183,9 @@ * 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 */ @@ -13433,8 +15194,9 @@ /** * g_dbus_connection_send_message_with_reply_finish: * @connection: a #GDBusConnection - * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply(). - * @error: Return location for error or %NULL. + * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to + * g_dbus_connection_send_message_with_reply() + * @error: teturn location for error or %NULL * * Finishes an operation started with g_dbus_connection_send_message_with_reply(). * @@ -13443,24 +15205,26 @@ * 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. * - * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set. + * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set * Since: 2.26 */ /** * g_dbus_connection_send_message_with_reply_sync: - * @connection: A #GDBusConnection. - * @message: A #GDBusMessage. - * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. - * @cancellable: (allow-none): A #GCancellable or %NULL. - * @error: Return location for error or %NULL. + * @connection: a #GDBusConnection + * @message: a #GDBusMessage + * @flags: flags affecting how the message is sent. + * @timeout_msec: the timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout + * @out_serial: (out) (allow-none): return location for serial number + * assigned to @message when sending it or %NULL + * @cancellable: (allow-none): a #GCancellable or %NULL + * @error: return location for error or %NULL * * Synchronously sends @message to the peer represented by @connection * and blocks the calling thread until a reply is received or the @@ -13484,22 +15248,24 @@ * 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. * - * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set. + * Returns: (transfer full): a locked #GDBusMessage that is the reply + * to @message or %NULL if @error is set * Since: 2.26 */ /** * g_dbus_connection_set_exit_on_close: - * @connection: A #GDBusConnection. - * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer. + * @connection: a #GDBusConnection + * @exit_on_close: whether the process should be terminated + * when @connection is closed by the remote peer * * Sets whether the process should be terminated when @connection is * closed by the remote peer. See #GDBusConnection:exit-on-close for @@ -13518,22 +15284,27 @@ /** * g_dbus_connection_signal_subscribe: - * @connection: A #GDBusConnection. - * @sender: (allow-none): Sender name to match on (unique or well-known name) or %NULL to listen from all senders. - * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to match on all interfaces. - * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals. - * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths. - * @arg0: (allow-none): Contents of first string argument to match on or %NULL to match on all kinds of arguments. - * @flags: Flags describing how to subscribe to the signal (currently unused). - * @callback: Callback to invoke when there is a signal matching the requested data. - * @user_data: User data to pass to @callback. - * @user_data_free_func: (allow-none): Function to free @user_data with when subscription is removed or %NULL. + * @connection: a #GDBusConnection + * @sender: (allow-none): sender name to match on (unique or well-known name) + * or %NULL to listen from all senders + * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to + * match on all interfaces + * @member: (allow-none): D-Bus signal name to match on or %NULL to match on + * all signals + * @object_path: (allow-none): object path to match on or %NULL to match on + * all object paths + * @arg0: (allow-none): contents of first string argument to match on or %NULL + * to match on all kinds of arguments + * @flags: flags describing how to subscribe to the signal (currently unused) + * @callback: callback to invoke when there is a signal matching the requested data + * @user_data: user data to pass to @callback + * @user_data_free_func: (allow-none): function to free @user_data with when + * subscription is removed or %NULL * - * 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. @@ -13545,15 +15316,21 @@ * tracking the name owner of the well-known name and use that when * processing the received signal. * - * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe(). + * If one of %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_NAMESPACE or + * %G_DBUS_SIGNAL_FLAGS_MATCH_ARG0_PATH are given, @arg0 is + * interpreted as part of a namespace or path. The first argument + * of a signal is matched against that part as specified by D-Bus. + * + * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe() * Since: 2.26 */ /** * g_dbus_connection_signal_unsubscribe: - * @connection: A #GDBusConnection. - * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe(). + * @connection: a #GDBusConnection + * @subscription_id: a subscription id obtained from + * g_dbus_connection_signal_subscribe() * * Unsubscribes from signals. * @@ -13563,7 +15340,7 @@ /** * g_dbus_connection_start_message_processing: - * @connection: A #GDBusConnection. + * @connection: a #GDBusConnection * * If @connection was created with * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method @@ -13608,24 +15385,26 @@ /** * g_dbus_connection_unregister_object: - * @connection: A #GDBusConnection. - * @registration_id: A registration id obtained from g_dbus_connection_register_object(). + * @connection: a #GDBusConnection + * @registration_id: a registration id obtained from + * g_dbus_connection_register_object() * * Unregisters an object. * - * Returns: %TRUE if the object was unregistered, %FALSE otherwise. + * Returns: %TRUE if the object was unregistered, %FALSE otherwise * Since: 2.26 */ /** * g_dbus_connection_unregister_subtree: - * @connection: A #GDBusConnection. - * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree(). + * @connection: a #GDBusConnection + * @registration_id: a subtree registration id obtained from + * g_dbus_connection_register_subtree() * * Unregisters a subtree. * - * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise. + * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise * Since: 2.26 */ @@ -13639,7 +15418,7 @@ * 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(). * @@ -13653,16 +15432,17 @@ /** * g_dbus_error_get_remote_error: - * @error: A #GError. + * @error: a #GError * * 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. * - * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free(). + * Returns: an allocated string or %NULL if the D-Bus error name + * could not be found. Free with g_free(). * Since: 2.26 */ @@ -13674,7 +15454,8 @@ * Checks if @error represents an error received via D-Bus from a remote peer. If so, * use g_dbus_error_get_remote_error() to get the name of the error. * - * Returns: %TRUE if @error represents an error from a remote peer, %FALSE otherwise. + * Returns: %TRUE if @error represents an error from a remote peer, + * %FALSE otherwise. * Since: 2.26 */ @@ -13723,12 +15504,13 @@ * @dbus_error_name: A D-Bus error name. * * 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. * - * Returns: %TRUE if the association was created, %FALSE if it already exists. + * Returns: %TRUE if the association was created, %FALSE if it already + * exists. * Since: 2.26 */ @@ -13821,80 +15603,41 @@ /** * g_dbus_gvalue_to_gvariant: - * @gvalue: A #GValue to convert to a #GVariant. - * @type: A #GVariantType. + * @gvalue: A #GValue to convert to a #GVariant + * @type: A #GVariantType * - * 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. * - * Returns: A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or %NULL in case of failure. Free with g_variant_unref(). + * Returns: A #GVariant (never floating) of #GVariantType @type holding + * the data from @gvalue or %NULL in case of failure. Free with + * g_variant_unref(). * Since: 2.30 */ @@ -13917,14 +15660,14 @@ /** - * g_dbus_interface_dup_object: + * g_dbus_interface_dup_object: (rename-to g_dbus_interface_get_object) * @interface_: An exported D-Bus interface. * * Gets the #GDBusObject that @interface_ belongs to, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). + * Returns: (transfer full): A #GDBusObject or %NULL. The returned + * reference should be freed with g_object_unref(). * Since: 2.32 - * Rename to: g_dbus_interface_get_object */ @@ -13942,16 +15685,16 @@ /** * g_dbus_interface_get_object: (skip) - * @interface_: An exported D-Bus interface. + * @interface_: An exported D-Bus interface * * 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. * - * Returns: (transfer none): A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. + * Returns: (transfer none): A #GDBusObject or %NULL. The returned + * reference belongs to @interface_ and should not be freed. * Since: 2.30 */ @@ -13997,7 +15740,7 @@ * * 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 @@ -14011,7 +15754,7 @@ * * Looks up information about a method. * - * This cost of this function is O(n) in number of methods unless + * The cost of this function is O(n) in number of methods unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14026,7 +15769,7 @@ * * Looks up information about a property. * - * This cost of this function is O(n) in number of properties unless + * The cost of this function is O(n) in number of properties unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14041,7 +15784,7 @@ * * Looks up information about a signal. * - * This cost of this function is O(n) in number of signals unless + * The cost of this function is O(n) in number of signals unless * g_dbus_interface_info_cache_build() has been used on @info. * * Returns: (transfer none): A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. @@ -14101,7 +15844,8 @@ * * Use g_dbus_interface_skeleton_unexport() to unexport the object. * - * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set. + * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with + * @error set. * Since: 2.30 */ @@ -14115,7 +15859,7 @@ * * 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. * @@ -14129,7 +15873,8 @@ * * Gets the first connection that @interface_ is exported on, if any. * - * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. + * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is + * not exported anywhere. Do not free, the object belongs to @interface_. * Since: 2.30 */ @@ -14140,7 +15885,10 @@ * * Gets a list of the connections that @interface_ is exported on. * - * Returns: (element-type GDBusConnection) (transfer full): A list of all the connections that @interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). + * Returns: (element-type GDBusConnection) (transfer full): A list of + * all the connections that @interface_ is exported on. The returned + * list should be freed with g_list_free() after each element has + * been freed with g_object_unref(). * Since: 2.32 */ @@ -14175,7 +15923,8 @@ * * Gets the object path that @interface_ is exported on, if any. * - * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. + * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported + * anywhere. Do not free, the string belongs to @interface_. * Since: 2.30 */ @@ -14186,7 +15935,9 @@ * * Gets all D-Bus properties for @interface_. * - * Returns: (transfer full): A #GVariant of type <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>. Free with g_variant_unref(). + * Returns: (transfer full): A #GVariant of type + * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + * Free with g_variant_unref(). * Since: 2.30 */ @@ -14209,7 +15960,7 @@ * @interface_: A #GDBusInterfaceSkeleton. * @connection: A #GDBusConnection. * - * Checks if @interface_ is export on @connection. + * Checks if @interface_ is exported on @connection. * * Returns: %TRUE if @interface_ is exported on @connection, %FALSE otherwise. * Since: 2.32 @@ -14325,7 +16076,8 @@ * transports in @string and that key/value pairs for each transport * are valid. * - * Returns: %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set. + * Returns: %TRUE if @string is a valid D-Bus address that is + * supported by this library, %FALSE if @error is set. * Since: 2.26 */ @@ -14356,7 +16108,8 @@ * (and linked models) must also originate from this same context, with * the thread default main context unchanged. * - * Returns: (transfer full): a #GDBusMenuModel object. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusMenuModel object. Free with + * g_object_unref(). * Since: 2.32 */ @@ -14370,7 +16123,9 @@ * Utility function to calculate how many bytes are needed to * completely deserialize the D-Bus message stored at @blob. * - * Returns: Number of bytes needed or -1 if @error is set (e.g. if @blob contains invalid data or not enough data is available to determine the size). + * Returns: Number of bytes needed or -1 if @error is set (e.g. if + * @blob contains invalid data or not enough data is available to + * determine the size). * Since: 2.26 */ @@ -14387,7 +16142,8 @@ * This operation can fail if e.g. @message contains file descriptors * and the per-process or system-wide open files limit is reached. * - * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ @@ -14398,7 +16154,8 @@ * * Convenience to get the first item in the body of @message. * - * Returns: The string item or %NULL if the first item in the body of @message is not a string. + * Returns: The string item or %NULL if the first item in the body of + * @message is not a string. * Since: 2.26 */ @@ -14464,7 +16221,8 @@ * * Gets a header field on @message. * - * Returns: A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message. + * Returns: A #GVariant with the value if the header was found, %NULL + * otherwise. Do not free, it is owned by @message. * Since: 2.26 */ @@ -14475,7 +16233,9 @@ * * Gets an array of all header fields on @message that are set. * - * Returns: (array zero-terminated=1): An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free(). + * Returns: (array zero-terminated=1): An array of header fields + * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element + * is a #guchar. Free with g_free(). * Since: 2.26 */ @@ -14600,7 +16360,8 @@ * * This method is only available on UNIX. * - * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. + * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are + * associated. Do not free, this object is owned by @message. * Since: 2.26 */ @@ -14636,7 +16397,8 @@ * order that the message was in can be retrieved using * g_dbus_message_get_byte_order(). * - * Returns: A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). + * Returns: A new #GDBusMessage or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ @@ -14657,7 +16419,8 @@ /** * g_dbus_message_new_method_error: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message_format: The D-Bus error message in a printf() format. * @...: Arguments for @error_message_format. @@ -14671,7 +16434,8 @@ /** * g_dbus_message_new_method_error_literal: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message: The D-Bus error message. * @@ -14684,7 +16448,8 @@ /** * g_dbus_message_new_method_error_valist: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message_format: The D-Bus error message in a printf() format. * @var_args: Arguments for @error_message_format. @@ -14698,7 +16463,8 @@ /** * g_dbus_message_new_method_reply: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * * Creates a new #GDBusMessage that is a reply to @method_call_message. * @@ -14721,7 +16487,7 @@ /** - * g_dbus_message_print: + * g_dbus_message_print: (type method-return) * @message: A #GDBusMessage. * @indent: Indentation level. * @@ -14730,35 +16496,33 @@ * 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 - * Serial: 4 - * Headers: + * |[ + * Flags: none + * Version: 0 + * Serial: 4 + * Headers: * path -> objectpath '/org/gtk/GDBus/TestObject' * interface -> 'org.gtk.GDBus.TestInterface' * member -> 'GimmeStdout' * destination -> ':1.146' - * Body: () + * Body: () * UNIX File Descriptors: * (none) - * </programlisting> + * ]| * or - * <programlisting> - * Type: method-return - * Flags: no-reply-expected - * Version: 0 - * Serial: 477 - * Headers: + * |[ + * Flags: no-reply-expected + * Version: 0 + * Serial: 477 + * Headers: * reply-serial -> uint32 4 * destination -> ':1.159' * sender -> ':1.146' * num-unix-fds -> uint32 1 - * Body: () - * UNIX File Descriptors: + * 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> + * ]| * * Returns: A string that should be freed with g_free(). * Since: 2.26 @@ -14814,7 +16578,8 @@ /** * g_dbus_message_set_flags: * @message: A #GDBusMessage. - * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). + * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags + * enumeration bitwise ORed together). * * Sets the flags to set on @message. * @@ -14961,7 +16726,9 @@ * Serializes @message to a blob. The byte order returned by * g_dbus_message_get_byte_order() will be used. * - * Returns: (array length=out_size) (transfer full): A pointer to a valid binary D-Bus message of @out_size bytes generated by @message or %NULL if @error is set. Free with g_free(). + * Returns: (array length=out_size) (transfer full): A pointer to a + * valid binary D-Bus message of @out_size bytes generated by @message + * or %NULL if @error is set. Free with g_free(). * Since: 2.26 */ @@ -15025,6 +16792,11 @@ * * Gets the name of the D-Bus interface the method was invoked on. * + * If this method call is a property Get, Set or GetAll call that has + * been redirected to the method call handler then + * "org.freedesktop.DBus.Properties" will be returned. See + * #GDBusInterfaceVTable for more information. + * * Returns: A string. Do not free, it is owned by @invocation. * Since: 2.26 */ @@ -15039,9 +16811,9 @@ * 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. * * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. * Since: 2.26 @@ -15054,6 +16826,11 @@ * * Gets information about the method call, if any. * + * If this method invocation is a property Get, Set or GetAll call that + * has been redirected to the method call handler then %NULL will be + * returned. See g_dbus_method_invocation_get_property_info() and + * #GDBusInterfaceVTable for more information. + * * Returns: A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. * Since: 2.26 */ @@ -15094,6 +16871,27 @@ /** + * g_dbus_method_invocation_get_property_info: + * @invocation: A #GDBusMethodInvocation + * + * Gets information about the property that this method call is for, if + * any. + * + * This will only be set in the case of an invocation in response to a + * property Get or Set call that has been directed to the method call + * handler for an object on account of its property_get() or + * property_set() vtable pointers being unset. + * + * See #GDBusInterfaceVTable for more information. + * + * If the call was GetAll, %NULL will be returned. + * + * Returns: (transfer none): a #GDBusPropertyInfo or %NULL + * Since: 2.38 + */ + + +/** * g_dbus_method_invocation_get_sender: * @invocation: A #GDBusMethodInvocation. * @@ -15143,12 +16941,11 @@ * 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. @@ -15258,7 +17055,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> method. + * handling the `org.freedesktop.DBus.Introspectable.Introspect` method. * * Since: 2.26 */ @@ -15271,7 +17068,7 @@ * * Looks up information about an interface. * - * This cost of this function is O(n) in number of interfaces. + * The cost of this function is O(n) in number of interfaces. * * Returns: (transfer none): A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. * Since: 2.26 @@ -15286,13 +17083,14 @@ * 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. * - * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref(). + * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free + * with g_dbus_node_info_unref(). * Since: 2.26 */ @@ -15329,7 +17127,8 @@ * Gets the D-Bus interface with name @interface_name associated with * @object, if any. * - * Returns: (transfer full): %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). + * Returns: (transfer full): %NULL if not found, otherwise a + * #GDBusInterface that must be freed with g_object_unref(). * Since: 2.30 */ @@ -15340,7 +17139,9 @@ * * Gets the D-Bus interfaces associated with @object. * - * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref(). + * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. + * The returned list must be freed by g_list_free() after each element has been freed + * with g_object_unref(). * Since: 2.30 */ @@ -15362,7 +17163,8 @@ * * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer none): A #GDBusConnection object. Do not free, the object belongs to @manager. + * Returns: (transfer none): A #GDBusConnection object. Do not free, + * the object belongs to @manager. * Since: 2.30 */ @@ -15373,7 +17175,8 @@ * * Gets the flags that @manager was constructed with. * - * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags enumeration. + * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags + * enumeration. * Since: 2.30 */ @@ -15382,9 +17185,11 @@ * g_dbus_object_manager_client_get_name: * @manager: A #GDBusObjectManagerClient * - * Gets the name that @manager is for. + * Gets the name that @manager is for, or %NULL if not a message bus + * connection. * - * Returns: A unique or well-known name. Do not free, the string belongs to @manager. + * Returns: A unique or well-known name. Do not free, the string + * belongs to @manager. * Since: 2.30 */ @@ -15398,7 +17203,8 @@ * #GObject::notify signal to track changes to the * #GDBusObjectManagerClient:name-owner property. * - * Returns: The name owner or %NULL if no name owner exists. Free with g_free(). + * Returns: The name owner or %NULL if no name owner exists. Free with + * g_free(). * Since: 2.30 */ @@ -15420,7 +17226,7 @@ * * 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. @@ -15436,7 +17242,9 @@ * * Finishes an operation started with g_dbus_object_manager_client_new(). * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15459,7 +17267,7 @@ * * 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. @@ -15475,7 +17283,9 @@ * * Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15499,7 +17309,9 @@ * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() * for the asynchronous version. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15508,7 +17320,7 @@ * g_dbus_object_manager_client_new_sync: * @connection: A #GDBusConnection. * @flags: Zero or more flags from the #GDBusObjectManagerClientFlags enumeration. - * @name: The owner of the control object (unique or well-known name). + * @name: (allow-none): The owner of the control object (unique or well-known name), or %NULL when not using a message bus connection. * @object_path: The object path of the control object. * @get_proxy_type_func: (allow-none): A #GDBusProxyTypeFunc function or %NULL to always construct #GDBusProxy proxies. * @get_proxy_type_user_data: User data to pass to @get_proxy_type_func. @@ -15522,7 +17334,9 @@ * blocked until a reply is received. See g_dbus_object_manager_client_new() * for the asynchronous version. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15536,7 +17350,8 @@ * Gets the interface proxy for @interface_name at @object_path, if * any. * - * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free with g_object_unref(). + * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free + * with g_object_unref(). * Since: 2.30 */ @@ -15548,7 +17363,8 @@ * * Gets the #GDBusObjectProxy at @object_path, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. Free with g_object_unref(). + * Returns: (transfer full): A #GDBusObject or %NULL. Free with + * g_object_unref(). * Since: 2.30 */ @@ -15570,7 +17386,10 @@ * * Gets all #GDBusObject objects known to @manager. * - * Returns: (transfer full) (element-type GDBusObject): A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref(). + * Returns: (transfer full) (element-type GDBusObject): A list of + * #GDBusObject objects. The returned list should be freed with + * g_list_free() after each element has been freed with + * g_object_unref(). * Since: 2.30 */ @@ -15601,10 +17420,9 @@ * @object: An object. * * 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 */ @@ -15616,7 +17434,9 @@ * * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer full): A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref(). + * Returns: (transfer full): A #GDBusConnection object or %NULL if + * @manager isn't exported on a connection. The returned object should + * be freed with g_object_unref(). * Since: 2.30 */ @@ -15682,7 +17502,8 @@ * * Gets the connection that @proxy is for. * - * Returns: (transfer none): A #GDBusConnection. Do not free, the object is owned by @proxy. + * Returns: (transfer none): A #GDBusConnection. Do not free, the + * object is owned by @proxy. * Since: 2.30 */ @@ -15806,9 +17627,11 @@ * @method_name: Name of method to invoke. * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. * @user_data: The data to pass to @callback. * * Asynchronously invokes the @method_name method on @proxy. @@ -15826,7 +17649,7 @@ * * 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)", @@ -15836,7 +17659,7 @@ * -1, * NULL, * (GAsyncReadyCallback) two_strings_done, - * &data); + * &data); * ]| * * If @proxy has an expected interface (see @@ -15845,7 +17668,7 @@ * * 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 @@ -15866,7 +17689,8 @@ * * Finishes an operation started with g_dbus_proxy_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -15875,9 +17699,11 @@ * g_dbus_proxy_call_sync: * @proxy: A #GDBusProxy. * @method_name: Name of method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. * @error: Return location for error or %NULL. * @@ -15896,7 +17722,7 @@ * * 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)", @@ -15905,7 +17731,7 @@ * G_DBUS_CALL_FLAGS_NONE, * -1, * NULL, - * &error); + * &error); * ]| * * The calling thread is blocked until a reply is received. See @@ -15916,7 +17742,8 @@ * #GDBusProxy:g-interface-info) and @method_name is referenced by it, * then the return value is checked against the return type. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -15927,10 +17754,12 @@ * @method_name: Name of method to invoke. * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. * @user_data: The data to pass to @callback. * * Like g_dbus_proxy_call() but also takes a #GUnixFDList object. @@ -15950,7 +17779,8 @@ * * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -15959,9 +17789,11 @@ * g_dbus_proxy_call_with_unix_fd_list_sync: * @proxy: A #GDBusProxy. * @method_name: Name of method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. @@ -15971,7 +17803,8 @@ * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -15988,7 +17821,9 @@ * #GDBusProxy:g-interface-info) and @property_name is referenced by * it, then @value is checked against the type of the property. * - * Returns: A reference to the #GVariant instance that holds the value for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref(). + * Returns: A reference to the #GVariant instance that holds the value + * for @property_name or %NULL if the value is not in the cache. The + * returned reference must be freed with g_variant_unref(). * Since: 2.26 */ @@ -15999,7 +17834,9 @@ * * Gets the names of all cached properties on @proxy. * - * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev(). + * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if + * @proxy has no cached properties. Free the returned array with + * g_strfreev(). * Since: 2.26 */ @@ -16049,7 +17886,8 @@ * that @proxy conforms to. See the #GDBusProxy:g-interface-info * property for more details. * - * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy. + * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned + * object, it is owned by @proxy. * Since: 2.26 */ @@ -16125,9 +17963,9 @@ * to handle signals from the remote object. * * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION + * flags aren't set and no name owner currently exists, the message bus + * will be requested to launch a name owner for the name. * * This is a failable asynchronous constructor - when the proxy is * ready, @callback will be invoked and you can use @@ -16135,7 +17973,7 @@ * * 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 */ @@ -16167,7 +18005,7 @@ * * 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 */ @@ -16189,7 +18027,8 @@ * g_dbus_proxy_new_for_bus_sync: * @bus_type: A #GBusType. * @flags: Flags used when constructing the proxy. - * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface + * that @proxy conforms to or %NULL. * @name: A bus name (well-known or unique). * @object_path: An object path. * @interface_name: A D-Bus interface name. @@ -16198,7 +18037,7 @@ * * 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]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 @@ -16226,14 +18065,14 @@ * to handle signals from the remote object. * * If @name is a well-known name and the - * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START flag isn't set and no name - * owner currently exists, the message bus will be requested to launch - * a name owner for the name. + * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION + * flags aren't set and no name owner currently exists, the message bus + * 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]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 @@ -16258,7 +18097,7 @@ * * 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)", @@ -16266,20 +18105,19 @@ * 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 */ @@ -16320,7 +18158,8 @@ * Gets a D-Bus address string that can be used by clients to connect * to @server. * - * Returns: A D-Bus address string. Do not free, the string is owned by @server. + * Returns: A D-Bus address string. Do not free, the string is owned + * by @server. * Since: 2.26 */ @@ -16379,13 +18218,13 @@ * 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. * - * Returns: A #GDBusServer or %NULL if @error is set. Free with g_object_unref(). + * Returns: A #GDBusServer or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ @@ -16435,12 +18274,45 @@ /** + * g_desktop_app_info_get_action_name: + * @info: a #GDesktopAppInfo + * @action_name: the name of the action as from + * g_desktop_app_info_list_actions() + * + * Gets the user-visible display name of the "additional application + * action" specified by @action_name. + * + * This corresponds to the "Name" key within the keyfile group for the + * action. + * + * Returns: (transfer full): the locale-specific action name + * Since: 2.38 + */ + + +/** + * g_desktop_app_info_get_boolean: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Looks up a boolean value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: the boolean value, or %FALSE if the key + * is not found + * Since: 2.36 + */ + + +/** * g_desktop_app_info_get_categories: * @info: a #GDesktopAppInfo * * Gets the categories from the desktop file. * - * Returns: The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it. + * Returns: The unparsed Categories key from the desktop file; + * i.e. no attempt is made to split it by ';' or validate it. */ @@ -16509,7 +18381,7 @@ * * 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. @@ -16517,7 +18389,9 @@ * Note that g_app_info_should_show() for @info will include this check (with * %NULL for @desktop_env) as well as additional checks. * - * Returns: %TRUE if the @info should be shown in @desktop_env according to the <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE otherwise. + * Returns: %TRUE if the @info should be shown in @desktop_env according to the + * `OnlyShowIn` and `NotShowIn` keys, %FALSE + * otherwise. * Since: 2.30 */ @@ -16530,21 +18404,78 @@ * WM_CLASS property of the main window of the application, if launched * through @info. * - * Returns: (transfer none): the startup WM class, or %NULL if none is set in the desktop file. + * Returns: (transfer none): the startup WM class, or %NULL if none is set + * in the desktop file. * Since: 2.34 */ /** + * g_desktop_app_info_get_string: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Looks up a string value in the keyfile backing @info. + * + * The @key is looked up in the "Desktop Entry" group. + * + * Returns: a newly allocated string, or %NULL if the key + * is not found + * Since: 2.36 + */ + + +/** + * g_desktop_app_info_has_key: + * @info: a #GDesktopAppInfo + * @key: the key to look up + * + * Returns whether @key exists in the "Desktop Entry" group + * of the keyfile backing @info. + * + * Returns: %TRUE if the @key exists + * Since: 2.36 + */ + + +/** + * g_desktop_app_info_launch_action: + * @info: a #GDesktopAppInfo + * @action_name: the name of the action as from + * g_desktop_app_info_list_actions() + * @launch_context: (allow-none): a #GAppLaunchContext + * + * Activates the named application action. + * + * You may only call this function on action names that were + * returned from g_desktop_app_info_list_actions(). + * + * Note that if the main entry of the desktop file indicates that the + * application supports startup notification, and @launch_context is + * non-%NULL, then startup notification will be used when activating the + * action (and as such, invocation of the action on the receiving side + * must signal the end of startup notification when it is completed). + * This is the expected behaviour of applications declaring additional + * actions, as per the desktop file specification. + * + * As with g_app_info_launch() there is no way to detect failures that + * occur while using this function. + * + * Since: 2.38 + */ + + +/** * g_desktop_app_info_launch_uris_as_manager: * @appinfo: a #GDesktopAppInfo * @uris: (element-type utf8): List of URIs - * @launch_context: a #GAppLaunchContext + * @launch_context: (allow-none): a #GAppLaunchContext * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process. - * @user_setup_data: (closure user_setup): User data for @user_setup - * @pid_callback: (scope call): Callback for child processes - * @pid_callback_data: (closure pid_callback): User data for @callback + * @user_setup: (scope call) (allow-none): a #GSpawnChildSetupFunc, used once + * for each process. + * @user_setup_data: (closure user_setup) (allow-none): User data for @user_setup + * @pid_callback: (scope call) (allow-none): Callback for child processes + * @pid_callback_data: (closure pid_callback) (allow-none): User data for @callback * @error: return location for a #GError, or %NULL * * This function performs the equivalent of g_app_info_launch_uris(), @@ -16552,21 +18483,36 @@ * launch applications. Ordinary applications should use * g_app_info_launch_uris(). * - * In contrast to g_app_info_launch_uris(), all processes created will - * always be run directly as children as if by the UNIX fork()/exec() - * calls. + * If the application is launched via traditional UNIX fork()/exec() + * then @spawn_flags, @user_setup and @user_setup_data are used for the + * call to g_spawn_async(). Additionally, @pid_callback (with + * @pid_callback_data) will be called to inform about the PID of the + * created process. * - * This guarantee allows additional control over the exact environment - * of the child processes, which is provided via a setup function - * @user_setup, as well as the process identifier of each child process - * via @pid_callback. See g_spawn_async() for more information about the - * semantics of the @user_setup function. + * If application launching occurs via some other mechanism (eg: D-Bus + * activation) then @spawn_flags, @user_setup, @user_setup_data, + * @pid_callback and @pid_callback_data are ignored. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ /** + * g_desktop_app_info_list_actions: + * @info: a #GDesktopAppInfo + * + * Returns the list of "additional application actions" supported on the + * desktop file, as per the desktop file specification. + * + * As per the specification, this is the list of actions that are + * explicitly listed in the "Actions" key of the [Desktop Entry] group. + * + * Returns: (array zero-terminated=1) (element-type utf8) (transfer none): a list of strings, always non-%NULL + * Since: 2.38 + */ + + +/** * g_desktop_app_info_lookup_get_default_for_uri_scheme: * @lookup: a #GDesktopAppInfoLookup * @uri_scheme: a string containing a URI scheme. @@ -16593,13 +18539,13 @@ * * 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`). * * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id */ @@ -16627,26 +18573,44 @@ /** + * g_desktop_app_info_search: + * @search_string: the search string to use + * + * Searches desktop files for ones that match @search_string. + * + * The return value is an array of strvs. Each strv contains a list of + * applications that matched @search_string with an equal score. The + * outer list is sorted by score so that the first strv contains the + * best-matching applications, and so on. + * The algorithm for determining matches is undefined and may change at + * any time. + * + * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a + * list of strvs. Free each item with g_strfreev() and free the outer + * list with g_free(). + */ + + +/** * g_desktop_app_info_set_desktop_env: * @desktop_env: a string specifying what desktop this is * * 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. */ @@ -16668,7 +18632,8 @@ * * Checks if a drive can be polled for media changes. * - * Returns: %TRUE if the @drive can be polled for media changes, %FALSE otherwise. + * Returns: %TRUE if the @drive can be polled for media changes, + * %FALSE otherwise. */ @@ -16731,7 +18696,8 @@ * * Finishes ejecting a drive. * - * Returns: %TRUE if the drive has been ejected successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been ejected successfully, + * %FALSE otherwise. * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. */ @@ -16740,7 +18706,8 @@ * g_drive_eject_with_operation: * @drive: a #GDrive. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -16757,7 +18724,8 @@ * g_drive_eject_with_operation_finish: * @drive: a #GDrive. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a drive. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -16775,7 +18743,9 @@ * Use g_drive_get_identifier() to obtain the identifiers * themselves. * - * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. + * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated + * array of strings containing kinds of identifiers. Use g_strfreev() + * to free. */ @@ -16785,7 +18755,8 @@ * * Gets the icon for @drive. * - * Returns: (transfer full): #GIcon for the @drive. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GIcon for the @drive. + * Free the returned object with g_object_unref(). */ @@ -16796,7 +18767,9 @@ * * Gets the identifier of the given kind for @drive. * - * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier. + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GDrive + * doesn't have this kind of identifier. */ @@ -16806,7 +18779,8 @@ * * Gets the name of @drive. * - * Returns: a string containing @drive's name. The returned string should be freed when no longer needed. + * Returns: a string containing @drive's name. The returned + * string should be freed when no longer needed. */ @@ -16838,7 +18812,8 @@ * * Gets the icon for @drive. * - * Returns: (transfer full): symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). + * Returns: (transfer full): symbolic #GIcon for the @drive. + * Free the returned object with g_object_unref(). * Since: 2.34 */ @@ -16884,7 +18859,8 @@ * * Checks if @drive is capabable of automatically detecting media changes. * - * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise. + * Returns: %TRUE if the @drive is capabable of automatically detecting + * media changes, %FALSE otherwise. */ @@ -16921,7 +18897,8 @@ * * Finishes an operation started with g_drive_poll_for_media() on a drive. * - * Returns: %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been poll_for_mediaed successfully, + * %FALSE otherwise. */ @@ -16929,7 +18906,8 @@ * g_drive_start: * @drive: a #GDrive. * @flags: flags affecting the start operation. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data to pass to @callback @@ -16952,7 +18930,8 @@ * * Finishes starting a drive. * - * Returns: %TRUE if the drive has been started successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been started successfully, + * %FALSE otherwise. * Since: 2.22 */ @@ -16961,7 +18940,8 @@ * g_drive_stop: * @drive: a #GDrive. * @flags: flags affecting the unmount if required for stopping. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data to pass to @callback @@ -16984,7 +18964,8 @@ * * Finishes stopping a drive. * - * Returns: %TRUE if the drive has been stopped successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been stopped successfully, + * %FALSE otherwise. * Since: 2.22 */ @@ -16995,7 +18976,8 @@ * * Gives back the icon from @emblem. * - * Returns: (transfer none): a #GIcon. The returned object belongs to the emblem and should not be modified or freed. + * Returns: (transfer none): a #GIcon. The returned object belongs to + * the emblem and should not be modified or freed. * Since: 2.18 */ @@ -17039,7 +19021,7 @@ * @emblemed: a #GEmblemedIcon * @emblem: a #GEmblem * - * Adds @emblem to the #GList of #GEmblem <!-- -->s. + * Adds @emblem to the #GList of #GEmblems. * * Since: 2.18 */ @@ -17061,7 +19043,8 @@ * * Gets the list of emblems for the @icon. * - * Returns: (element-type Gio.Emblem) (transfer none): a #GList of #GEmblem <!-- -->s that is owned by @emblemed + * Returns: (element-type Gio.Emblem) (transfer none): a #GList of + * #GEmblems that is owned by @emblemed * Since: 2.18 */ @@ -17093,7 +19076,8 @@ * g_file_append_to: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Gets an output stream for appending data to the file. @@ -17114,7 +19098,8 @@ * %G_IO_ERROR_IS_DIRECTORY error will be returned. Other errors are * possible too, and depend on what kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17122,9 +19107,11 @@ * g_file_append_to_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for appending. @@ -17147,7 +19134,9 @@ * Finishes an asynchronous file append operation started with * g_file_append_to_async(). * - * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a valid #GFileOutputStream + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17180,7 +19169,8 @@ * * Gets the file attribute with the name @name from @list. * - * Returns: a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found. + * Returns: a #GFileAttributeInfo for the @name, or %NULL if an + * attribute isn't found. */ @@ -17224,7 +19214,8 @@ * * TODO: this is awkwardly worded. * - * Returns: %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise. + * Returns: %TRUE if the matcher matches all of the entries + * in the given @ns, %FALSE otherwise. */ @@ -17234,7 +19225,8 @@ * * Gets the next matched attribute from a #GFileAttributeMatcher. * - * Returns: a string containing the next attribute or %NULL if no more attribute exist. + * Returns: a string containing the next attribute or %NULL if + * no more attribute exist. */ @@ -17268,7 +19260,7 @@ * @attributes: an attribute string to match. * * 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. @@ -17279,20 +19271,15 @@ * 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 * - * Returns: a #GFileAttributeMatcher. + * - `"*"`: 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. + * + * Returns: a #GFileAttributeMatcher */ @@ -17320,7 +19307,8 @@ * is a limitation of the current implementation, but may be fixed * in the future. * - * Returns: A file attribute matcher matching all attributes of @matcher that are not matched by @subtract + * Returns: A file attribute matcher matching all attributes of + * @matcher that are not matched by @subtract */ @@ -17333,7 +19321,8 @@ * The output however, might not be identical, as the matcher may * decide to use a different order or omit needless parts. * - * Returns: a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL. + * Returns: a string describing the attributes the matcher matches + * against or %NULL if @matcher was %NULL. * Since: 2.32 */ @@ -17352,8 +19341,10 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none) (scope call): function to callback with progress information, or %NULL if progress information is not needed + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none) (scope call): function to callback with + * progress information, or %NULL if progress information is not needed * @progress_callback_data: (closure): user data to pass to @progress_callback * @error: #GError to set on error, or %NULL * @@ -17403,9 +19394,11 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none): function to callback with progress information, or %NULL if progress information is not needed + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none): function to callback with progress + * information, or %NULL if progress information is not needed * @progress_callback_data: (closure): user data to pass to @progress_callback * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -17427,7 +19420,8 @@ * @source: a #GFile with attributes * @destination: a #GFile to copy attributes to * @flags: a set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, %NULL to ignore * * Copies the file attributes from @source to @destination. @@ -17439,7 +19433,8 @@ * all the metadata that is possible to copy is copied. This * is useful when implementing move by copy + delete source. * - * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise. + * Returns: %TRUE if the attributes were copied successfully, + * %FALSE otherwise. */ @@ -17459,7 +19454,8 @@ * g_file_create: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a new file and returns an output stream for writing to it. @@ -17482,7 +19478,9 @@ * be returned. Other errors are possible too, and depend on what kind * of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream for the newly created + * file, or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17490,9 +19488,11 @@ * g_file_create_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously creates a new file and returns an output stream @@ -17516,7 +19516,8 @@ * Finishes an asynchronous file create operation started with * g_file_create_async(). * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -17524,7 +19525,8 @@ * g_file_create_readwrite: * @file: a #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: return location for a #GError, or %NULL * * Creates a new file and returns a stream for reading and @@ -17551,7 +19553,9 @@ * not supported, so make sure you really need to do read and write * streaming, rather than just opening for reading or writing. * - * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream for the newly created + * file, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -17560,9 +19564,11 @@ * g_file_create_readwrite_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously creates a new file and returns a stream @@ -17588,15 +19594,17 @@ * Finishes an asynchronous file create operation started with * g_file_create_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ /** - * g_file_delete: + * g_file_delete: (virtual delete_file) * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Deletes a file. If the @file is a directory, it will only be @@ -17606,37 +19614,37 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Virtual: delete_file * Returns: %TRUE if the file was deleted. %FALSE otherwise. */ /** - * g_file_delete_async: + * g_file_delete_async: (virtual delete_file_async) * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: the data to pass to callback function * * Asynchronously delete a file. If the @file is a directory, it will * only be deleted if it is empty. This has the same semantics as * g_unlink(). * - * Virtual: delete_file_async * Since: 2.34 */ /** - * g_file_delete_finish: + * g_file_delete_finish: (virtual delete_file_finish) * @file: input #GFile * @result: a #GAsyncResult * @error: a #GError, or %NULL * * Finishes deleting a file started with g_file_delete_async(). * - * Virtual: delete_file_finish + * Returns: %TRUE if the file was deleted. %FALSE otherwise. * Since: 2.34 */ @@ -17662,7 +19670,8 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile. + * Returns: (transfer full): a new #GFile that is a duplicate + * of the given #GFile. */ @@ -17670,8 +19679,10 @@ * g_file_eject_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Starts an asynchronous eject on a mountable. @@ -17696,8 +19707,10 @@ * Finishes an asynchronous eject operation started by * g_file_eject_mountable(). * - * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise. - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead. + * Returns: %TRUE if the @file was ejected successfully. + * %FALSE otherwise. + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() + * instead. */ @@ -17705,9 +19718,12 @@ * g_file_eject_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Starts an asynchronous eject on a mountable. @@ -17732,7 +19748,8 @@ * Finishes an asynchronous eject operation started by * g_file_eject_mountable_with_operation(). * - * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise. + * Returns: %TRUE if the @file was ejected successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -17742,7 +19759,8 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: #GError for error reporting * * Gets the requested information about the files in a directory. @@ -17766,10 +19784,11 @@ * returned. * * If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will - * be returned. If the file is not a directory, the %G_FILE_ERROR_NOTDIR + * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY * error will be returned. Other errors are possible too. * - * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): A #GFileEnumerator if successful, + * %NULL on error. Free the returned object with g_object_unref(). */ @@ -17778,9 +19797,11 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about the files @@ -17805,7 +19826,9 @@ * Finishes an async enumerate children operation. * See g_file_enumerate_children_async(). * - * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileEnumerator or %NULL + * if an error occurred. + * Free the returned object with g_object_unref(). */ @@ -17829,7 +19852,7 @@ /** * g_file_enumerator_close_async: * @enumerator: a #GFileEnumerator. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -17847,7 +19870,8 @@ * g_file_enumerator_close_finish: * @enumerator: a #GFileEnumerator. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). * @@ -17865,6 +19889,28 @@ /** + * g_file_enumerator_get_child: + * @enumerator: a #GFileEnumerator + * @info: a #GFileInfo gotten from g_file_enumerator_next_file() + * or the async equivalents. + * + * Return a new #GFile which refers to the file named by @info in the source + * 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); + * ]| + * + * Returns: (transfer full): a #GFile for the #GFileInfo passed it. + * Since: 2.36 + */ + + +/** * g_file_enumerator_get_container: * @enumerator: a #GFileEnumerator * @@ -17906,11 +19952,15 @@ * returned from this function will contain attributes that match the * attribute string that was passed when the #GFileEnumerator was created. * + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * * On error, returns %NULL and sets @error to the error. If the * enumerator is at the end, %NULL will be returned and @error will * be unset. * - * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed. + * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. + * Free the returned object with g_object_unref() when no longer needed. */ @@ -17918,7 +19968,7 @@ * g_file_enumerator_next_files_async: * @enumerator: a #GFileEnumerator. * @num_files: the number of file info objects to request - * @io_priority: the <link linkend="gioscheduler">io priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -17927,6 +19977,9 @@ * When all i/o for the operation is finished the @callback will be called with * the requested information. * + * See the documentation of #GFileEnumerator for information about the + * order of returned files. + * * The callback can be called with less than @num_files files in case of error * or at the end of the enumerator. In case of a partial error the callback will * be called with any succeeding items and no error, and on the next request the @@ -17946,11 +19999,14 @@ * g_file_enumerator_next_files_finish: * @enumerator: a #GFileEnumerator. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). * - * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them. + * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with + * g_list_free() and unref the infos with g_object_unref() when you're + * done with them. */ @@ -17976,14 +20032,16 @@ * * This call does no blocking I/O. * - * Returns: %TRUE if @file1 and @file2 are equal. %FALSE if either is not a #GFile. + * Returns: %TRUE if @file1 and @file2 are equal. + * %FALSE if either is not a #GFile. */ /** * g_file_find_enclosing_mount: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Gets a #GMount for the #GFile. @@ -17996,16 +20054,20 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GMount where the @file is located + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_find_enclosing_mount_async: * @file: a #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the mount for the file. @@ -18028,7 +20090,8 @@ * Finishes an asynchronous find mount request. * See g_file_find_enclosing_mount_async(). * - * Returns: (transfer full): #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GMount for given @file or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -18050,7 +20113,9 @@ * * This call does no blocking I/O. * - * Returns: string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed. + * Returns: string containing the #GFile's base name, or %NULL + * if given #GFile is invalid. The returned string should be + * freed with g_free() when no longer needed. */ @@ -18067,7 +20132,8 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile to a child specified by @name. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile to a child specified by @name. + * Free the returned object with g_object_unref(). */ @@ -18086,7 +20152,9 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile to the specified child, or + * %NULL if the display name couldn't be converted. + * Free the returned object with g_object_unref(). */ @@ -18100,7 +20168,9 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile structure to the + * parent of the given #GFile or %NULL if there is + * no parent. Free the returned object with g_object_unref(). */ @@ -18123,7 +20193,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's parse name. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -18135,7 +20207,9 @@ * * This call does no blocking I/O. * - * Returns: string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed. + * Returns: string containing the #GFile's path, or %NULL if + * no such path exists. The returned string should be + * freed with g_free() when no longer needed. */ @@ -18148,7 +20222,10 @@ * * This call does no blocking I/O. * - * Returns: string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed. + * Returns: string with the relative path from @descendant + * to @parent, or %NULL if @descendant doesn't have @parent + * as prefix. The returned string should be freed with g_free() + * when no longer needed. */ @@ -18160,7 +20237,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's URI. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's URI. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -18170,14 +20249,16 @@ * * 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. * - * Returns: a string containing the URI scheme for the given #GFile. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the URI scheme for the given + * #GFile. The returned string should be freed with g_free() + * when no longer needed. */ @@ -18192,13 +20273,14 @@ * parent at all. If @parent is non-%NULL then %TRUE is only returned * if @file is a child of @parent. * - * Returns: %TRUE if @file is a child of @parent (or any parent in the case that @parent is %NULL). + * Returns: %TRUE if @file is a child of @parent (or any parent in the + * case that @parent is %NULL). * Since: 2.24 */ /** - * g_file_has_prefix: + * g_file_has_prefix: (virtual prefix_matches) * @file: input #GFile * @prefix: input #GFile * @@ -18214,8 +20296,8 @@ * filesystem point of view), because the prefix of @file is an alias * of @prefix. * - * Virtual: prefix_matches - * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, %FALSE otherwise. + * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, + * %FALSE otherwise. */ @@ -18228,20 +20310,24 @@ * * This call does no blocking I/O. * - * Returns: %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. + * Returns: %TRUE if #GFile's backend supports the + * given URI scheme, %FALSE if URI scheme is %NULL, + * not supported, or #GFile is invalid. */ /** - * g_file_hash: + * g_file_hash: (virtual hash) * @file: (type GFile): #gconstpointer to a #GFile * * Creates a hash value for a #GFile. * * This call does no blocking I/O. * - * Virtual: hash - * Returns: 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure. + * Returns: 0 if @file is not a valid #GFile, otherwise an + * integer that can be used as hash value for the #GFile. + * This function is intended for easily hashing a #GFile to + * add to a #GHashTable or similar data structure. */ @@ -18261,7 +20347,8 @@ * * Creates a new icon for a file. * - * Returns: (transfer full) (type GFileIcon): a #GIcon for the given @file, or %NULL on error. + * Returns: (transfer full) (type GFileIcon): a #GIcon for the given + * @file, or %NULL on error. */ @@ -18278,7 +20365,7 @@ * @src_info: source to copy attributes from. * @dest_info: destination to copy attributes to. * - * Copies all of the <link linkend="gio-GFileAttribute">GFileAttribute</link>s + * Copies all of the [GFileAttribute][gio-GFileAttribute] * from @src_info to @dest_info. */ @@ -18302,7 +20389,8 @@ * This escapes things as needed to make the string valid * utf8. * - * Returns: a UTF-8 string associated with the given @attribute. When you're done with the string it must be freed with g_free(). + * Returns: a UTF-8 string associated with the given @attribute. + * When you're done with the string it must be freed with g_free(). */ @@ -18326,7 +20414,8 @@ * Gets the value of a byte string attribute. If the attribute does * not contain a byte string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a byte string, or %NULL otherwise. + * Returns: the contents of the @attribute value as a byte string, or + * %NULL otherwise. */ @@ -18340,7 +20429,8 @@ * * Gets the attribute type, value and status for an attribute key. * - * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, %FALSE otherwise. + * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, + * %FALSE otherwise. */ @@ -18378,7 +20468,8 @@ * Gets the value of a #GObject attribute. If the attribute does * not contain a #GObject, %NULL will be returned. * - * Returns: (transfer none): a #GObject associated with the given @attribute, or %NULL otherwise. + * Returns: (transfer none): a #GObject associated with the given @attribute, or + * %NULL otherwise. */ @@ -18389,7 +20480,8 @@ * * Gets the attribute status for an attribute key. * - * Returns: a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. + * Returns: a #GFileAttributeStatus for the given @attribute, or + * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. */ @@ -18401,7 +20493,8 @@ * Gets the value of a string attribute. If the attribute does * not contain a string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. + * Returns: the contents of the @attribute value as a UTF-8 string, or + * %NULL otherwise. */ @@ -18413,7 +20506,8 @@ * Gets the value of a stringv attribute. If the attribute does * not contain a stringv, %NULL will be returned. * - * Returns: (transfer none): the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8. + * Returns: (transfer none): the contents of the @attribute value as a stringv, or + * %NULL otherwise. Do not free. These returned strings are UTF-8. * Since: 2.22 */ @@ -18425,7 +20519,8 @@ * * Gets the attribute type for an attribute key. * - * Returns: a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. + * Returns: a #GFileAttributeType for the given @attribute, or + * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. */ @@ -18466,6 +20561,19 @@ /** + * g_file_info_get_deletion_date: + * @info: a #GFileInfo. + * + * Returns the #GDateTime representing the deletion date of the file, as + * available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the + * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. + * + * Returns: a #GDateTime, or %NULL. + * Since: 2.36 + */ + + +/** * g_file_info_get_display_name: * @info: a #GFileInfo. * @@ -18489,7 +20597,7 @@ * g_file_info_get_etag: * @info: a #GFileInfo. * - * 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. * * Returns: a string containing the value of the "etag:value" attribute. @@ -18616,7 +20724,8 @@ * * Checks if a file info structure has an attribute named @attribute. * - * Returns: %TRUE if @Ginfo has an attribute named @attribute, %FALSE otherwise. + * Returns: %TRUE if @Ginfo has an attribute named @attribute, + * %FALSE otherwise. */ @@ -18628,7 +20737,8 @@ * Checks if a file info structure has an attribute in the * specified @name_space. * - * Returns: %TRUE if @Ginfo has an attribute in @name_space, %FALSE otherwise. + * Returns: %TRUE if @Ginfo has an attribute in @name_space, + * %FALSE otherwise. * Since: 2.22 */ @@ -18640,7 +20750,9 @@ * * Lists the file info structure's attributes. * - * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error. + * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the + * possible attribute types for the given @name_space, or + * %NULL on error. */ @@ -18805,7 +20917,7 @@ /** * g_file_info_set_content_type: * @info: a #GFileInfo. - * @content_type: a content type. See <link linkend="gio-GContentType">GContentType</link>. + * @content_type: a content type. See [GContentType][gio-GContentType] * * Sets the content type attribute for a given #GFileInfo. * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. @@ -18857,7 +20969,7 @@ * @info: a #GFileInfo. * @is_hidden: a #gboolean. * - * Sets the "is_hidden" attribute in a #GFileInfo according to @is_symlink. + * Sets the "is_hidden" attribute in a #GFileInfo according to @is_hidden. * See %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN. */ @@ -18948,7 +21060,8 @@ * @stream: a #GFileInputStream. * @attributes: a file attribute query string. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Queries a file input stream the given @attributes. This function blocks * while querying the stream. For the asynchronous (non-blocking) version @@ -18964,7 +21077,7 @@ * g_file_input_stream_query_info_async: * @stream: a #GFileInputStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -18987,7 +21100,8 @@ * g_file_input_stream_query_info_finish: * @stream: a #GFileInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, + * or %NULL to ignore. * * Finishes an asynchronous info query operation. * @@ -19042,7 +21156,7 @@ * g_file_io_stream_query_info_async: * @stream: a #GFileIOStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -19097,8 +21211,10 @@ * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Loads the content of the file into memory. The data is always @@ -19110,7 +21226,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors. + * Returns: %TRUE if the @file's contents were successfully loaded. + * %FALSE if there were errors. */ @@ -19142,8 +21259,10 @@ * @file: input #GFile * @res: a #GAsyncResult * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous load of the @file's contents. @@ -19152,7 +21271,8 @@ * g_free() when no longer needed. If @etag_out is present, it will be * set to the new entity tag for the @file. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ @@ -19160,7 +21280,8 @@ * g_file_load_partial_contents_async: (skip) * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read + * @read_more_callback: a #GFileReadMoreCallback to receive partial data + * and to specify whether further data should be read * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to the callback functions * @@ -19183,8 +21304,10 @@ * @file: input #GFile * @res: a #GAsyncResult * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous partial load operation that was started @@ -19193,14 +21316,16 @@ * The returned @content should be freed with g_free() when no longer * needed. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ /** * g_file_make_directory: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a directory. Note that this will only create a child directory @@ -19223,9 +21348,40 @@ /** + * g_file_make_directory_async: (virtual make_directory_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously creates a directory. + * + * Since: 2.38 + */ + + +/** + * g_file_make_directory_finish: (virtual make_directory_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous directory creation, started with + * g_file_make_directory_async(). + * + * Returns: %TRUE on successful directory creation, %FALSE otherwise. + * Since: 2.38 + */ + + +/** * g_file_make_directory_with_parents: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a directory and any parent directories that may not @@ -19242,7 +21398,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if all directories have been successfully created, %FALSE otherwise. + * Returns: %TRUE if all directories have been successfully created, %FALSE + * otherwise. * Since: 2.18 */ @@ -19251,7 +21408,8 @@ * g_file_make_symbolic_link: * @file: a #GFile with the name of the symlink to create * @symlink_value: a string with the path for the target of the new symlink - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Creates a symbolic link named @file which contains the string @@ -19266,10 +21424,87 @@ /** + * g_file_measure_disk_usage: + * @file: a #GFile + * @flags: #GFileMeasureFlags + * @cancellable: (allow-none): optional #GCancellable + * @progress_callback: (allow-none): a #GFileMeasureProgressCallback + * @progress_data: user_data for @progress_callback + * @disk_usage: (allow-none) (out): the number of bytes of disk space used + * @num_dirs: (allow-none) (out): the number of directories encountered + * @num_files: (allow-none) (out): the number of non-directories encountered + * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer + * + * Recursively measures the disk usage of @file. + * + * 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 + * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags. + * + * The returned size, @disk_usage, is in bytes and should be formatted + * with g_format_size() in order to get something reasonable for showing + * in a user interface. + * + * @progress_callback and @progress_data can be given to request + * periodic progress updates while scanning. See the documentation for + * #GFileMeasureProgressCallback for information about when and how the + * callback will be invoked. + * + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. + * Since: 2.38 + */ + + +/** + * g_file_measure_disk_usage_async: + * @file: a #GFile + * @flags: #GFileMeasureFlags + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable + * @progress_callback: (allow-none): a #GFileMeasureProgressCallback + * @progress_data: user_data for @progress_callback + * @callback: (allow-none): a #GAsyncReadyCallback to call when complete + * @user_data: the data to pass to callback function + * + * Recursively measures the disk usage of @file. + * + * This is the asynchronous version of g_file_measure_disk_usage(). See + * there for more information. + * + * Since: 2.38 + */ + + +/** + * g_file_measure_disk_usage_finish: + * @file: a #GFile + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @disk_usage: (allow-none) (out): the number of bytes of disk space used + * @num_dirs: (allow-none) (out): the number of directories encountered + * @num_files: (allow-none) (out): the number of non-directories encountered + * @error: (allow-none): %NULL, or a pointer to a %NULL #GError pointer + * + * Collects the results from an earlier call to + * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for + * more information. + * + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. + * Since: 2.38 + */ + + +/** * g_file_monitor: * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a file or directory monitor for the given file, @@ -19279,7 +21514,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.18 */ @@ -19295,10 +21532,11 @@ /** - * g_file_monitor_directory: + * g_file_monitor_directory: (virtual monitor_dir) * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a directory monitor for the given file. @@ -19308,8 +21546,15 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Virtual: monitor_dir - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * It does not make sense for @flags to contain + * %G_FILE_MONITOR_WATCH_HARD_LINKS, since hard links can not be made to + * directories. It is not possible to monitor all the files in a + * directory for changes made via hard links; if you want to do this then + * you must register individual watches with g_file_monitor(). + * + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19324,9 +21569,8 @@ * 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]). */ @@ -19334,7 +21578,8 @@ * g_file_monitor_file: * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a file monitor for the given file. If no file notification @@ -19344,7 +21589,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * If @flags contains %G_FILE_MONITOR_WATCH_HARD_LINKS then the monitor + * will also attempt to report changes made to the file via another + * filename (ie, a hard link). Without this flag, you can only rely on + * changes made through the filename contained in @file to be + * reported. Using this flag may result in an increase in resource + * usage, and may not have any effect depending on the #GFileMonitor + * backend and/or filesystem type. + * + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19361,7 +21616,8 @@ /** * g_file_monitor_set_rate_limit: * @monitor: a #GFileMonitor. - * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes + * @limit_msecs: a non-negative integer with the limit in milliseconds + * to poll for changes * * Sets the rate limit to which the @monitor will report * consecutive change events to the same file. @@ -19372,9 +21628,12 @@ * g_file_mount_enclosing_volume: * @location: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Starts a @mount_operation, mounting the volume that contains @@ -19398,7 +21657,9 @@ * * Finishes a mount operation started by g_file_mount_enclosing_volume(). * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, + * this function will return %FALSE and set @error + * appropriately if present. */ @@ -19406,9 +21667,12 @@ * g_file_mount_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Mounts a file of type G_FILE_TYPE_MOUNTABLE. @@ -19436,7 +21700,8 @@ * Finish an asynchronous mount operation that was started * with g_file_mount_mountable(). * - * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19445,9 +21710,12 @@ * @source: #GFile pointing to the source location * @destination: #GFile pointing to the destination location * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none) (scope call): #GFileProgressCallback function for updates - * @progress_callback_data: (closure): gpointer to user data for the callback function + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none) (scope call): #GFileProgressCallback + * function for updates + * @progress_callback_data: (closure): gpointer to user data for + * the callback function * @error: #GError for returning error conditions, or %NULL * * Tries to move the file or directory @source to the location specified @@ -19502,19 +21770,53 @@ * This operation never fails, but the returned object might not * support any I/O operation if @arg points to a malformed path. * - * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref(). + * 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. + * + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). + */ + + +/** + * g_file_new_for_commandline_arg_and_cwd: + * @arg: a command line string + * @cwd: the current working directory of the commandline + * + * Creates a #GFile with the given argument from the command line. + * + * This function is similar to g_file_new_for_commandline_arg() except + * that it allows for passing the current working directory as an + * argument instead of using the current working directory of the + * process. + * + * This is useful if the commandline argument was given in a context + * other than the invocation of the current process. + * + * See also g_application_command_line_create_file_for_arg(). + * + * Returns: (transfer full): a new #GFile + * Since: 2.36 */ /** * g_file_new_for_path: - * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. + * @path: a string containing a relative or absolute path. + * The string must be encoded in the glib filename encoding. * * Constructs a #GFile for a given path. This operation never * fails, but the returned object might not support any I/O * operation if @path is malformed. * - * Returns: (transfer full): a new #GFile for the given @path. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile for the given @path. + * Free the returned object with g_object_unref(). */ @@ -19527,13 +21829,15 @@ * operation if @uri is malformed or if the uri type is * not supported. * - * Returns: (transfer full): a new #GFile for the given @uri. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile for the given @uri. + * Free the returned object with g_object_unref(). */ /** * g_file_new_tmp: - * @tmpl: (type filename) (allow-none): Template for the file name, as in g_file_open_tmp(), or %NULL for a default template + * @tmpl: (type filename) (allow-none): Template for the file + * name, as in g_file_open_tmp(), or %NULL for a default template * @iostream: (out): on return, a #GFileIOStream for the created file * @error: a #GError, or %NULL * @@ -19548,7 +21852,8 @@ * Unlike the other #GFile constructors, this will return %NULL if * a temporary file could not be created. * - * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). * Since: 2.32 */ @@ -19576,7 +21881,8 @@ * really need to do read and write streaming, rather than just opening * for reading or writing. * - * Returns: (transfer full): #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -19584,9 +21890,11 @@ /** * g_file_open_readwrite_async: * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for reading and writing. @@ -19611,7 +21919,8 @@ * Finishes an asynchronous file read operation started with * g_file_open_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -19661,7 +21970,7 @@ * g_file_output_stream_query_info_async: * @stream: a #GFileOutputStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -19705,7 +22014,8 @@ * g_file_poll_mountable: * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Polls a file of type #G_FILE_TYPE_MOUNTABLE. @@ -19733,7 +22043,8 @@ * Finish an asynchronous poll operation that was polled * with g_file_poll_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. * Since: 2.22 */ @@ -19751,14 +22062,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref() + * Returns: (transfer full): a #GAppInfo if the handle was found, + * %NULL if there were errors. + * When you are done with it, release it with g_object_unref() */ /** * g_file_query_exists: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * * Utility function to check if a particular file exists. This is * implemented using g_file_query_info() and as such does blocking I/O. @@ -19783,7 +22097,8 @@ * dialog. If you do this, you should make sure to also handle the errors * that can happen due to races when you execute the operation. * - * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). + * Returns: %TRUE if the file exists (and can be detected without error), + * %FALSE otherwise (or if cancelled). */ @@ -19791,7 +22106,8 @@ * g_file_query_file_type: * @file: input #GFile * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info() - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * * Utility function to inspect the #GFileType of a file. This is * implemented using g_file_query_info() and as such does blocking I/O. @@ -19799,7 +22115,8 @@ * The primary use case of this method is to check if a file is * a regular file, directory, or symlink. * - * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file does not exist + * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN + * if the file does not exist * Since: 2.18 */ @@ -19808,7 +22125,8 @@ * g_file_query_filesystem_info: * @file: input #GFile * @attributes: an attribute query string - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Similar to g_file_query_info(), but obtains information @@ -19837,7 +22155,8 @@ * be returned. Other errors are possible too, and depend on what * kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. + * Free the returned object with g_object_unref(). */ @@ -19845,9 +22164,11 @@ * g_file_query_filesystem_info_async: * @file: input #GFile * @attributes: an attribute query string - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about the filesystem @@ -19873,7 +22194,9 @@ * Finishes an asynchronous filesystem info query. * See g_file_query_filesystem_info_async(). * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19882,7 +22205,8 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Gets the requested information about specified @file. @@ -19916,7 +22240,8 @@ * returned. Other errors are possible too, and depend on what kind of * filesystem the file is on. * - * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL + * on error. Free the returned object with g_object_unref(). */ @@ -19925,9 +22250,11 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about specified @file. @@ -19951,14 +22278,17 @@ * Finishes an asynchronous file info query. * See g_file_query_info_async(). * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. Free the returned object with + * g_object_unref(). */ /** * g_file_query_settable_attributes: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtain the list of settable attributes for the file. @@ -19972,14 +22302,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() + * Returns: a #GFileAttributeInfoList describing the settable attributes. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** * g_file_query_writable_namespaces: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtain the list of attribute namespaces where new attributes @@ -19990,12 +22323,14 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() + * Returns: a #GFileAttributeInfoList describing the writable namespaces. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** - * g_file_read: + * g_file_read: (virtual read_fn) * @file: #GFile to read * @cancellable: (allow-none): a #GCancellable * @error: a #GError, or %NULL @@ -20012,17 +22347,19 @@ * error will be returned. Other errors are possible too, and depend * on what kind of filesystem the file is on. * - * Virtual: read_fn - * Returns: (transfer full): #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_read_async: * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for reading. @@ -20045,17 +22382,20 @@ * Finishes an asynchronous file read operation started with * g_file_read_async(). * - * Returns: (transfer full): a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace: * @file: input #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @etag: (allow-none): an optional [entity tag][gfile-etag] + * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Returns an output stream for overwriting the file, possibly @@ -20100,19 +22440,23 @@ * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are * possible too, and depend on what kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace_async: * @file: input #GFile - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously overwrites the file, replacing the contents, @@ -20132,10 +22476,13 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL + * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document, + * or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when no longer needed, or %NULL + * @new_etag: (allow-none) (out): 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 * @cancellable: optional #GCancellable object, %NULL to ignore * @error: a #GError, or %NULL * @@ -20154,7 +22501,8 @@ * The returned @new_etag can be used to verify that the file hasn't * changed the next time it is saved over. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. */ @@ -20163,7 +22511,7 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @length: the length of @contents in bytes - * @etag: (allow-none): a new <link linkend="gfile-etag">entity tag</link> for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -20184,6 +22532,35 @@ * * If @make_backup is %TRUE, this function will attempt to * make a backup of @file. + * + * 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. + */ + + +/** + * g_file_replace_contents_bytes_async: + * @file: input #GFile + * @contents: a #GBytes + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL + * @make_backup: %TRUE if a backup should be created + * @flags: a set of #GFileCreateFlags + * @cancellable: optional #GCancellable object, %NULL to ignore + * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @user_data: the data to pass to callback function + * + * Same as g_file_replace_contents_async() but takes a #GBytes input instead. + * This function will keep a ref on @contents until the operation is done. + * Unlike g_file_replace_contents_async() this allows forgetting about the + * content without waiting for the callback. + * + * When this operation has completed, @callback will be called with + * @user_user data, and the operation can be finalized with + * g_file_replace_contents_finish(). + * + * Since: 2.40 */ @@ -20191,7 +22568,9 @@ * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when it is no longer needed, or %NULL + * @new_etag: (out) (allow-none): 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 * @error: a #GError, or %NULL * * Finishes an asynchronous replace of the given @file. See @@ -20211,17 +22590,20 @@ * Finishes an asynchronous file replace operation started with * g_file_replace_async(). * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @etag: (allow-none): an optional [entity tag][gfile-etag] + * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: return location for a #GError, or %NULL * * Returns an output stream for overwriting the file in readwrite mode, @@ -20235,7 +22617,8 @@ * supported, so make sure you really need to do read and write streaming, * rather than just opening for reading or writing. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -20243,12 +22626,15 @@ /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously overwrites the file in read-write mode, @@ -20275,7 +22661,8 @@ * Finishes an asynchronous file replace operation started with * g_file_replace_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -20289,7 +22676,9 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path is %NULL or if @file is invalid. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFile to the resolved path. + * %NULL if @relative_path is %NULL or if @file is invalid. + * Free the returned object with g_object_unref(). */ @@ -20298,9 +22687,11 @@ * @file: input #GFile * @attribute: a string containing the attribute's name * @type: The type of the attribute - * @value_p: (allow-none): a pointer to the value (or the pointer itself if the type is a pointer type) + * @value_p: (allow-none): a pointer to the value (or the pointer + * itself if the type is a pointer type) * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets an attribute in the file with attribute name @attribute to @value. @@ -20322,7 +22713,8 @@ * @attribute: a string containing the attribute's name * @value: a string containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. @@ -20333,7 +22725,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20343,7 +22736,8 @@ * @attribute: a string containing the attribute's name * @value: a #gint32 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. @@ -20353,7 +22747,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20363,7 +22758,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint64 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. @@ -20383,7 +22779,8 @@ * @attribute: a string containing the attribute's name * @value: a string containing the attribute's value * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. @@ -20403,7 +22800,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint32 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. @@ -20413,7 +22811,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20423,7 +22822,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint64 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. @@ -20433,7 +22833,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -20442,8 +22843,9 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: a #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer * @@ -20476,7 +22878,8 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Tries to set all attributes in the #GFileInfo on the target @@ -20492,7 +22895,7 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if there was any error, %FALSE otherwise. + * Returns: %FALSE if there was any error, %TRUE otherwise. */ @@ -20500,7 +22903,8 @@ * g_file_set_display_name: * @file: input #GFile * @display_name: a string - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Renames @file to the specified display name. @@ -20519,7 +22923,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile specifying what @file was renamed to, + * or %NULL if there was an error. + * Free the returned object with g_object_unref(). */ @@ -20527,9 +22933,11 @@ * g_file_set_display_name_async: * @file: input #GFile * @display_name: a string - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously sets the display name for a given #GFile. @@ -20552,7 +22960,8 @@ * Finishes setting a display name started with * g_file_set_display_name_async(). * - * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -20592,7 +23001,8 @@ * Finish an asynchronous start operation that was started * with g_file_start_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. * Since: 2.22 */ @@ -20601,9 +23011,12 @@ * g_file_stop_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Stops a file of type #G_FILE_TYPE_MOUNTABLE. @@ -20631,7 +23044,8 @@ * Finish an asynchronous stop operation that was started * with g_file_stop_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -20640,11 +23054,10 @@ * g_file_supports_thread_contexts: * @file: a #GFile * - * 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. * * Returns: Whether or not @file supports thread-default contexts. * Since: 2.22 @@ -20652,9 +23065,10 @@ /** - * g_file_trash: + * g_file_trash: (virtual trash) * @file: #GFile to send to trash - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sends @file to the "Trashcan", if possible. This is similar to @@ -20671,11 +23085,43 @@ /** + * g_file_trash_async: (virtual trash_async) + * @file: input #GFile + * @io_priority: the [I/O priority][io-priority] of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied + * @user_data: the data to pass to callback function + * + * Asynchronously sends @file to the Trash location, if possible. + * + * Since: 2.38 + */ + + +/** + * g_file_trash_finish: (virtual trash_finish) + * @file: input #GFile + * @result: a #GAsyncResult + * @error: a #GError, or %NULL + * + * Finishes an asynchronous file trashing operation, started with + * g_file_trash_async(). + * + * Returns: %TRUE on successful trash, %FALSE otherwise. + * Since: 2.38 + */ + + +/** * g_file_unmount_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. @@ -20703,8 +23149,10 @@ * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. + * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() + * instead. */ @@ -20712,9 +23160,12 @@ * g_file_unmount_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. @@ -20743,7 +23194,8 @@ * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable_with_operation(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -20755,7 +23207,9 @@ * * Obtains a completion for @initial_text from @completer. * - * Returns: a completed string, or %NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished. + * Returns: a completed string, or %NULL if no completion exists. + * This string is not owned by GIO, so remember to g_free() it + * when finished. */ @@ -20766,7 +23220,8 @@ * * Gets an array of completion strings for a given initial text. * - * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished. + * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. + * This array must be freed by g_strfreev() when finished. */ @@ -20850,6 +23305,17 @@ /** + * g_icon_deserialize: + * @value: a #GVariant created with g_icon_serialize() + * + * Deserializes a #GIcon previously serialized using g_icon_serialize(). + * + * Returns: (transfer full): a #GIcon, or %NULL when deserialization fails. + * Since: 2.38 + */ + + +/** * g_icon_equal: * @icon1: (allow-none): pointer to the first #GIcon. * @icon2: (allow-none): pointer to the second #GIcon. @@ -20861,13 +23327,13 @@ /** - * g_icon_hash: + * g_icon_hash: (virtual hash) * @icon: #gconstpointer to an icon object. * * Gets a hash for an icon. * - * Virtual: hash - * Returns: a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. + * Returns: a #guint containing a hash for the @icon, suitable for + * use in a #GHashTable or similar data structure. */ @@ -20883,13 +23349,29 @@ * implementations you need to ensure that each #GType is registered * with the type system prior to calling g_icon_new_for_string(). * - * Returns: (transfer full): An object implementing the #GIcon interface or %NULL if @error is set. + * Returns: (transfer full): An object implementing the #GIcon + * interface or %NULL if @error is set. * Since: 2.20 */ /** - * g_icon_to_string: + * g_icon_serialize: + * @icon: a #GIcon + * + * Serializes a #GIcon into a #GVariant. An equivalent #GIcon can be retrieved + * back by calling g_icon_deserialize() on the returned value. + * As serialization will avoid using raw icon data when possible, it only + * makes sense to transfer the #GVariant between processes on the same machine, + * (as opposed to over the network), and within the same file system namespace. + * + * Returns: (transfer full): a #GVariant, or %NULL when serialization fails. + * Since: 2.38 + */ + + +/** + * g_icon_to_string: (virtual to_tokens) * @icon: a #GIcon. * * Generates a textual representation of @icon that can be used for @@ -20900,22 +23382,17 @@ * 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 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> - * - * Virtual: to_tokens - * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free. + * - 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 `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`). + * + * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't + * be serialized. Use g_free() to free. * Since: 2.20 */ @@ -21122,7 +23599,8 @@ * * Tests if @address falls within the range described by @mask. * - * Returns: whether @address falls within the range described by @mask. + * Returns: whether @address falls within the range described by + * @mask. * Since: 2.32 */ @@ -21151,7 +23629,8 @@ * delimited by a "/". If it is not present, then the length is * assumed to be the full length of the address. * - * Returns: a new #GInetAddressMask corresponding to @string, or %NULL on error. + * Returns: a new #GInetAddressMask corresponding to @string, or %NULL + * on error. * Since: 2.32 */ @@ -21174,7 +23653,8 @@ * Creates a #GInetAddress for the "any" address (unassigned/"don't * care") for @family. * - * Returns: a new #GInetAddress corresponding to the "any" address for @family. + * Returns: a new #GInetAddress corresponding to the "any" address + * for @family. * Since: 2.22 */ @@ -21199,7 +23679,8 @@ * * Parses @string as an IP address and creates a new #GInetAddress. * - * Returns: a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed. + * Returns: a new #GInetAddress corresponding to @string, or %NULL if + * @string could not be parsed. * Since: 2.22 */ @@ -21210,7 +23691,8 @@ * * Creates a #GInetAddress for the loopback address for @family. * - * Returns: a new #GInetAddress corresponding to the loopback address for @family. + * Returns: a new #GInetAddress corresponding to the loopback address + * for @family. * Since: 2.22 */ @@ -21221,7 +23703,9 @@ * * Gets the raw binary address data from @address. * - * Returns: a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size(). + * Returns: a pointer to an internal array of the bytes in @address, + * which should not be modified, stored, or freed. The size of this + * array can be gotten with g_inet_address_get_native_size(). * Since: 2.22 */ @@ -21232,7 +23716,8 @@ * * Converts @address to string form. * - * Returns: a representation of @address as a string, which should be freed after use. + * Returns: a representation of @address as a string, which should be + * freed after use. * Since: 2.22 */ @@ -21243,7 +23728,8 @@ * * Gets @address's #GInetAddress. * - * Returns: (transfer none): the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored + * Returns: (transfer none): the #GInetAddress for @address, which must be + * g_object_ref()'d if it will be stored * Since: 2.22 */ @@ -21252,7 +23738,7 @@ * g_inet_socket_address_get_flowinfo: * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress * - * Gets the <literal>sin6_flowinfo</literal> field from @address, + * Gets the `sin6_flowinfo` field from @address, * which must be an IPv6 address. * * Returns: the flowinfo field @@ -21275,7 +23761,7 @@ * g_inet_socket_address_get_scope_id: * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress * - * Gets the <literal>sin6_scope_id</literal> field from @address, + * Gets the `sin6_scope_id` field from @address, * which must be an IPv6 address. * * Returns: the scope id field @@ -21296,10 +23782,27 @@ /** + * g_inet_socket_address_new_from_string: + * @address: the string form of an IP address + * @port: a port number + * + * 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>"). + * + * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be + * parsed. + * Since: 2.40 + */ + + +/** * g_initable_init: * @initable: a #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Initializes the object implementing the interface. * @@ -21316,8 +23819,7 @@ * 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. @@ -21325,7 +23827,8 @@ * of the first call. This is so that it's safe to implement the singleton * pattern in the GObject constructor function. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function will + * return %FALSE and set @error appropriately if present. * Since: 2.22 */ @@ -21334,15 +23837,19 @@ * g_initable_new: * @object_type: a #GType supporting #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. - * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties - * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. + * @first_property_name: (allow-none): the name of the first property, or %NULL if no + * properties + * @...: the value if the first property, followed by and other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GInitable object. This is * similar to g_object_new() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -21350,16 +23857,19 @@ /** * g_initable_new_valist: * @object_type: a #GType supporting #GInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, followed by + * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Helper function for constructing #GInitable object. This is * similar to g_object_new_valist() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -21370,18 +23880,30 @@ * @n_parameters: the number of parameters in @parameters * @parameters: (array length=n_parameters): the parameters to use to construct the object * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Helper function for constructing #GInitable object. This is * similar to g_object_newv() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ /** + * g_input_stream_async_read_is_via_threads: + * @stream: input stream + * + * Checks if an input stream's read_async function uses threads. + * + * Returns: %TRUE if @stream's read_async function uses threads. + */ + + +/** * g_input_stream_clear_pending: * @stream: input stream * @@ -21426,7 +23948,7 @@ /** * g_input_stream_close_async: * @stream: A #GInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional cancellable object * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21448,7 +23970,8 @@ * g_input_stream_close_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). * @@ -21479,7 +24002,8 @@ /** * g_input_stream_read: * @stream: a #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore @@ -21510,7 +24034,8 @@ /** * g_input_stream_read_all: * @stream: a #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @bytes_read: (out): location to store the number of bytes that was read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -21537,9 +24062,11 @@ /** * g_input_stream_read_async: * @stream: A #GInputStream. - * @buffer: a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21573,7 +24100,8 @@ /** * g_input_stream_read_bytes: * @stream: a #GInputStream. - * @count: maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. + * @count: maximum number of bytes that will be read from the stream. Common + * values include 4096 and 8192. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -21609,7 +24137,7 @@ * g_input_stream_read_bytes_async: * @stream: A #GInputStream. * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21641,7 +24169,8 @@ * g_input_stream_read_bytes_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream read-into-#GBytes operation. * @@ -21653,7 +24182,8 @@ * g_input_stream_read_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream read operation. * @@ -21664,7 +24194,8 @@ /** * g_input_stream_set_pending: * @stream: input stream - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -21704,7 +24235,7 @@ * g_input_stream_skip_async: * @stream: A #GInputStream. * @count: the number of bytes that will be skipped from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21739,7 +24270,8 @@ * g_input_stream_skip_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream skip operation. * @@ -21819,7 +24351,8 @@ * * Finds a #GIOExtension for an extension point by name. * - * Returns: (transfer none): the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name + * Returns: (transfer none): the #GIOExtension for @extension_point that has the + * given name, or %NULL if there is no extension with that name */ @@ -21830,7 +24363,9 @@ * Gets a list of all extensions that implement this extension point. * The list is sorted by priority, beginning with the highest priority. * - * Returns: (element-type GIOExtension) (transfer none): a #GList of #GIOExtension<!-- -->s. The list is owned by GIO and should not be modified. + * Returns: (element-type GIOExtension) (transfer none): a #GList of + * #GIOExtensions. The list is owned by GIO and should not be + * modified. */ @@ -21840,7 +24375,8 @@ * * Gets the required type for @extension_point. * - * Returns: the #GType that all implementations must have, or #G_TYPE_INVALID if the extension point has no required type + * Returns: the #GType that all implementations must have, + * or #G_TYPE_INVALID if the extension point has no required type */ @@ -21867,7 +24403,8 @@ * * Looks up an existing extension point. * - * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. + * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there + * is no registered extension point with the given name. */ @@ -21877,7 +24414,8 @@ * * Registers an extension point. * - * Returns: (transfer none): the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. + * Returns: (transfer none): the new #GIOExtensionPoint. This object is + * owned by GIO and should not be freed. */ @@ -21909,7 +24447,8 @@ * Creates a new GIOModule that will load the specific * shared library when in use. * - * Returns: a #GIOModule from given @filename, or %NULL on error. + * Returns: a #GIOModule from given @filename, + * or %NULL on error. */ @@ -21962,7 +24501,12 @@ * all gtypes) then you can use g_io_modules_scan_all_in_directory() * which allows delayed/lazy loading of modules. * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free(). + * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded + * from the directory, + * All the modules are loaded into memory, if you want to + * unload them (enabling on-demand loading) you must call + * g_type_module_unuse() on all the modules. Free the list + * with g_list_free(). */ @@ -21977,7 +24521,12 @@ * all gtypes) then you can use g_io_modules_scan_all_in_directory() * which allows delayed/lazy loading of modules. * - * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free(). + * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded + * from the directory, + * All the modules are loaded into memory, if you want to + * unload them (enabling on-demand loading) you must call + * g_type_module_unuse() on all the modules. Free the list + * with g_list_free(). * Since: 2.30 */ @@ -22030,6 +24579,10 @@ * * A job is cancellable if a #GCancellable was passed into * g_io_scheduler_push_job(). + * + * Deprecated: You should never call this function, since you don't + * know how other libraries in your program might be making use of + * gioscheduler. */ @@ -22045,6 +24598,7 @@ * blocking the I/O job). * * Returns: The return value of @func + * Deprecated: Use g_main_context_invoke(). */ @@ -22064,6 +24618,8 @@ * on to this function you have to ensure that it is not freed before * @func is called, either by passing %NULL as @notify to * g_io_scheduler_push_job() or by using refcounting for @user_data. + * + * Deprecated: Use g_main_context_invoke(). */ @@ -22072,7 +24628,8 @@ * @job_func: a #GIOSchedulerJobFunc. * @user_data: data to pass to @job_func * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the <link linkend="gioscheduler">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] + * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * * Schedules the I/O job to run in another thread. @@ -22083,6 +24640,8 @@ * If @cancellable is not %NULL, it can be used to cancel the I/O job * by calling g_cancellable_cancel() or by calling * g_io_scheduler_cancel_all_jobs(). + * + * Deprecated: use #GThreadPool or g_task_run_in_thread() */ @@ -22168,7 +24727,8 @@ * g_io_stream_close_finish: * @stream: a #GIOStream * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Closes a stream. * @@ -22184,7 +24744,8 @@ * Gets the input stream for this object. This is used * for reading. * - * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. Do not free. + * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. + * Do not free. * Since: 2.22 */ @@ -22196,7 +24757,8 @@ * Gets the output stream for this object. This is used for * writing. * - * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. Do not free. + * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. + * Do not free. * Since: 2.22 */ @@ -22226,7 +24788,8 @@ /** * g_io_stream_set_pending: * @stream: a #GIOStream - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -22262,7 +24825,8 @@ /** * g_io_stream_splice_finish: * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous io stream splice operation. * @@ -22275,7 +24839,8 @@ * g_keyfile_settings_backend_new: * @filename: the filename of the keyfile * @root_path: the path under which all settings keys appear - * @root_group: (allow-none): the group name corresponding to @root_path, or %NULL + * @root_group: (allow-none): the group name corresponding to + * @root_path, or %NULL * * Creates a keyfile-backed #GSettingsBackend. * @@ -22330,9 +24895,11 @@ * g_loadable_icon_load: * @icon: a #GLoadableIcon. * @size: an integer. - * @type: (out) (allow-none): a location to store the type of the loaded icon, %NULL to ignore. + * @type: (out) (allow-none): a location to store the type of the + * loaded icon, %NULL to ignore. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Loads a loadable icon. For the asynchronous version of this function, * see g_loadable_icon_load_async(). @@ -22346,7 +24913,8 @@ * @icon: a #GLoadableIcon. * @size: an integer. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Loads an icon asynchronously. To finish this function, see @@ -22359,8 +24927,10 @@ * g_loadable_icon_load_finish: * @icon: a #GLoadableIcon. * @res: a #GAsyncResult. - * @type: a location to store the type of the loaded icon, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @type: (out) (allow-none): a location to store the type of the + * loaded icon, %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). * @@ -22448,9 +25018,8 @@ * g_memory_output_stream_get_data_size: * @ostream: a #GMemoryOutputStream * - * Returns the number of bytes from the start up - * to including the last byte written in the stream - * that has not been truncated away. + * Returns the number of bytes from the start up to including the last + * byte written in the stream that has not been truncated away. * * Returns: the number of bytes written to the stream * Since: 2.18 @@ -22462,16 +25031,20 @@ * @ostream: a #GMemoryOutputStream * * Gets the size of the currently allocated data area (available from - * g_memory_output_stream_get_data()). If the stream isn't - * growable (no realloc was passed to g_memory_output_stream_new()) then - * this is the maximum size of the stream and further writes - * will return %G_IO_ERROR_NO_SPACE. + * g_memory_output_stream_get_data()). + * + * You probably don't want to use this function on resizable streams. + * See g_memory_output_stream_get_data_size() instead. For resizable + * streams the size returned by this function is an implementation + * detail and may be change at any time in response to operations on the + * stream. * - * Note that for growable streams the returned size may become invalid on - * the next write or truncate operation on the stream. + * If the stream is fixed-sized (ie: no realloc was passed to + * g_memory_output_stream_new()) then this is the maximum size of the + * stream and further writes will return %G_IO_ERROR_NO_SPACE. * - * If you want the number of bytes currently written to the stream, use - * g_memory_output_stream_get_data_size(). + * In any case, if you want the number of bytes currently written to the + * stream, use g_memory_output_stream_get_data_size(). * * Returns: the number of bytes allocated for the data buffer */ @@ -22481,24 +25054,49 @@ * g_memory_output_stream_new: (skip) * @data: (allow-none): pointer to a chunk of memory to use, or %NULL * @size: the size of @data - * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL - * @destroy_function: (allow-none): a function to be called on @data when the stream is finalized, or %NULL + * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) + * to be called when @data needs to be grown, or %NULL + * @destroy_function: (allow-none): a function to be called on @data when the stream is + * finalized, or %NULL * * Creates a new #GMemoryOutputStream. * - * If @data is non-%NULL, the stream will use that for its internal storage. - * If @realloc_fn is non-%NULL, it will be used for resizing the internal - * storage when necessary. To construct a fixed-size output stream, - * pass %NULL as @realloc_fn. + * In most cases this is not the function you want. See + * g_memory_output_stream_new_resizable() instead. * - * |[ - * /* a stream that can grow */ + * If @data is non-%NULL, the stream will use that for its internal storage. + * + * If @realloc_fn is non-%NULL, it will be used for resizing the internal + * storage when necessary and the stream will be considered resizable. + * In that case, the stream will start out being (conceptually) empty. + * @size is used only as a hint for how big @data is. Specifically, + * seeking to the end of a newly-created stream will seek to zero, not + * @size. Seeking past the end of the stream and then writing will + * introduce a zero-filled gap. + * + * If @realloc_fn is %NULL then the stream is fixed-sized. Seeking to + * the end will seek to @size exactly. Writing past the end will give + * an 'out of space' error. Attempting to seek past the end will fail. + * Unlike the resizable case, seeking to an offset within the stream and + * writing will preserve the bytes passed in as @data before that point + * and will return them as part of g_memory_output_stream_steal_data(). + * If you intend to seek you should probably therefore ensure that @data + * is properly initialised. + * + * It is probably only meaningful to provide @data and @size in the case + * that you want a fixed-sized stream. Put another way: if @realloc_fn + * 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). + * + * |[<!-- 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); * ]| @@ -22508,6 +25106,16 @@ /** + * g_memory_output_stream_new_resizable: + * + * Creates a new #GMemoryOutputStream, using g_realloc() and g_free() + * for memory allocation. + * + * Since: 2.36 + */ + + +/** * g_memory_output_stream_steal_as_bytes: * @ostream: a #GMemoryOutputStream * @@ -22640,7 +25248,8 @@ * remains at the current position. The value returned in @value must * be unreffed using g_variant_unref() when it is no longer in use. * - * Returns: %TRUE on success, or %FALSE if there is no additional attribute + * Returns: %TRUE on success, or %FALSE if there is no additional + * attribute * Since: 2.32 */ @@ -22784,7 +25393,8 @@ * type, then the positional parameters are ignored and %FALSE is * returned. * - * Returns: %TRUE if the named attribute was found with the expected type + * Returns: %TRUE if the named attribute was found with the expected + * type * Since: 2.34 */ @@ -22881,8 +25491,7 @@ * 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'/> @@ -22894,7 +25503,7 @@ * <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 @@ -22902,8 +25511,7 @@ * 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'> @@ -22919,7 +25527,7 @@ * </link> * </item> * </menu> - * ]]></programlisting></informalexample> + * ]| * * Returns: a new #GMenuItem * Since: 2.32 @@ -23085,14 +25693,8 @@ * * Sets the "action" and possibly the "target" attribute of @menu_item. * - * If @detailed_action contains a double colon ("::") then it is used as - * a separator between an action name and a target string. In this - * case, this call is equivalent to calling - * g_menu_item_set_action_and_target() with the part before the "::" and - * with a string-type #GVariant containing the part following the "::". - * - * If @detailed_action doesn't contain "::" then the action is set to - * the given string (verbatim) and the target value is unset. + * The format of @detailed_action is the same format parsed by + * g_action_parse_detailed_name(). * * See g_menu_item_set_action_and_target() or * g_menu_item_set_action_and_target_value() for more flexible (but @@ -23106,6 +25708,28 @@ /** + * g_menu_item_set_icon: + * @menu_item: a #GMenuItem + * @icon: a #GIcon, or %NULL + * + * Sets (or unsets) the icon on @menu_item. + * + * This call is the same as calling g_icon_serialize() and using the + * result as the value to g_menu_item_set_attribute_value() for + * %G_MENU_ATTRIBUTE_ICON. + * + * This API is only intended for use with "noun" menu items; things like + * bookmarks or applications in an "Open With" menu. Don't use it on + * menu items corresponding to verbs (eg: stock icons for 'Save' or + * 'Quit'). + * + * If @icon is %NULL then the icon is unset. + * + * Since: 2.38 + */ + + +/** * g_menu_item_set_label: * @menu_item: a #GMenuItem * @label: (allow-none): the label to set, or %NULL to unset @@ -23267,9 +25891,10 @@ * g_variant_get(), followed by a g_variant_unref(). As such, * @format_string must make a complete copy of the data (since the * #GVariant may go away after the call to g_variant_unref()). In - * particular, no '&' characters are allowed in @format_string. + * particular, no '&' characters are allowed in @format_string. * - * Returns: %TRUE if the named attribute was found with the expected type + * Returns: %TRUE if the named attribute was found with the expected + * type * Since: 2.32 */ @@ -23279,7 +25904,8 @@ * @model: a #GMenuModel * @item_index: the index of the item * @attribute: the attribute to query - * @expected_type: (allow-none): the expected type of the attribute, or %NULL + * @expected_type: (allow-none): the expected type of the attribute, or + * %NULL * * Queries the item at position @item_index in @model for the attribute * specified by @attribute. @@ -23335,7 +25961,8 @@ * An immutable #GMenuModel will never emit the #GMenuModel::items-changed * signal. Consumers of the model may make optimisations accordingly. * - * Returns: %TRUE if the model is mutable (ie: "items-changed" may be emitted). + * Returns: %TRUE if the model is mutable (ie: "items-changed" may be + * emitted). * Since: 2.32 */ @@ -23485,6 +26112,16 @@ /** + * g_menu_remove_all: + * @menu: a #GMenu + * + * Removes all items in the menu. + * + * Since: 2.38 + */ + + +/** * g_mount_can_eject: * @mount: a #GMount. * @@ -23524,7 +26161,8 @@ * g_mount_eject_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23538,7 +26176,8 @@ * g_mount_eject_with_operation: * @mount: a #GMount. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -23555,7 +26194,8 @@ * g_mount_eject_with_operation_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23573,7 +26213,9 @@ * @mount is a path that reflects the main entry point for the user (e.g. * the home directory, or the root of the volume). * - * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23586,7 +26228,9 @@ * This is a convenience method for getting the #GVolume and then * using that object to get the #GDrive. * - * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23596,7 +26240,9 @@ * * Gets the icon for @mount. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23606,7 +26252,9 @@ * * Gets the name of @mount. * - * Returns: the name for the given @mount. The returned string should be freed with g_free() when no longer needed. + * Returns: the name for the given @mount. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -23616,7 +26264,9 @@ * * Gets the root directory on @mount. * - * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -23637,7 +26287,9 @@ * * Gets the symbolic icon for @mount. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * Since: 2.34 */ @@ -23651,7 +26303,9 @@ * considered an opaque string. Returns %NULL if there is no UUID * available. * - * Returns: the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. + * Returns: the UUID for @mount or %NULL if no UUID can be computed. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -23661,14 +26315,17 @@ * * Gets the volume for the @mount. * - * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ /** * g_mount_guess_content_type: * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @force_rescan: Whether to force a rescan of the content. + * Otherwise a cached result will be used if available * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: a #GAsyncReadyCallback * @user_data: user data passed to @callback @@ -23676,7 +26333,8 @@ * 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 @@ -23692,7 +26350,8 @@ * g_mount_guess_content_type_finish: * @mount: a #GMount * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Finishes guessing content types of @mount. If any errors occurred * during the operation, @error will be set to contain the errors and @@ -23700,7 +26359,8 @@ * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content * guessing. * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. + * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. + * Caller should free this array with g_strfreev() when done with it. * Since: 2.18 */ @@ -23708,20 +26368,24 @@ /** * g_mount_guess_content_type_sync: * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @force_rescan: Whether to force a rescan of the content. + * Otherwise a cached result will be used if available * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * 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; * see g_mount_guess_content_type() for the asynchronous version. * - * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it. + * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. + * Caller should free this array with g_strfreev() when done with it. * Since: 2.18 */ @@ -23742,10 +26406,10 @@ * 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. @@ -23776,7 +26440,8 @@ * * Gets a choice from the mount operation. * - * Returns: an integer containing an index of the user's choice from the choice's list, or %0. + * Returns: an integer containing an index of the user's choice from + * the choice's list, or %0. */ @@ -23896,7 +26561,8 @@ * g_mount_remount: * @mount: a #GMount. * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -23917,7 +26583,8 @@ * g_mount_remount_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes remounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23959,7 +26626,8 @@ * g_mount_unmount_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes unmounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -23973,7 +26641,8 @@ * g_mount_unmount_with_operation: * @mount: a #GMount. * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -23990,7 +26659,8 @@ * g_mount_unmount_with_operation_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes unmounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -24179,7 +26849,8 @@ * @monitor: a #GNetworkMonitor * @connectable: a #GSocketConnectable * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously attempts to determine whether or not the host @@ -24305,6 +26976,202 @@ /** + * g_networking_init: + * + * Initializes the platform networking libraries (eg, on Windows, this + * calls WSAStartup()). GLib will call this itself if it is needed, so + * you only need to call it if you directly call system networking + * functions (without calling any GLib networking functions first). + * + * Since: 2.36 + */ + + +/** + * g_notification_add_button: + * @notification: a #GNotification + * @label: label of the button + * @detailed_action: a detailed action name + * + * Adds a button to @notification that activates the action in + * @detailed_action when clicked. That action must be an + * application-wide action (starting with "app."). If @detailed_action + * contains a target, the action will be activated with that target as + * its parameter. + * + * See g_action_parse_detailed_name() for a description of the format + * for @detailed_action. + * + * Since: 2.40 + */ + + +/** + * g_notification_add_button_with_target: (skip) + * @notification: a #GNotification + * @label: label of the button + * @action: an action name + * @target_format: (allow-none): a GVariant format string, or %NULL + * @...: positional parameters, as determined by @format_string + * + * Adds a button to @notification that activates @action when clicked. + * @action must be an application-wide action (it must start with "app."). + * + * If @target_format is given, it is used to collect remaining + * positional parameters into a GVariant instance, similar to + * g_variant_new(). @action will be activated with that GVariant as its + * parameter. + * + * Since: 2.40 + */ + + +/** + * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target) + * @notification: a #GNotification + * @label: label of the button + * @action: an action name + * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL + * + * Adds a button to @notification that activates @action when clicked. + * @action must be an application-wide action (it must start with "app."). + * + * If @target is non-%NULL, @action will be activated with @target as + * its parameter. + * + * Since: 2.40 + */ + + +/** + * g_notification_new: + * @title: the title of the notification + * + * Creates a new #GNotification with @title as its title. + * + * After populating @notification with more details, it can be sent to + * the desktop shell with g_application_send_notification(). Changing + * any properties after this call will not have any effect until + * resending @notification. + * + * Returns: a new #GNotification instance + * Since: 2.40 + */ + + +/** + * g_notification_set_body: + * @notification: a #GNotification + * @body: (allow-none): the new body for @notification, or %NULL + * + * Sets the body of @notification to @body. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_default_action: + * @notification: a #GNotification + * @detailed_action: a detailed action name + * + * Sets the default action of @notification to @detailed_action. This + * action is activated when the notification is clicked on. + * + * The action in @detailed_action must be an application-wide action (it + * must start with "app."). If @detailed_action contains a target, the + * given action will be activated with that target as its parameter. + * See g_action_parse_detailed_name() for a description of the format + * for @detailed_action. + * + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_default_action_and_target: (skip) + * @notification: a #GNotification + * @action: an action name + * @target_format: (allow-none): a GVariant format string, or %NULL + * @...: positional parameters, as determined by @format_string + * + * Sets the default action of @notification to @action. This action is + * activated when the notification is clicked on. It must be an + * application-wide action (it must start with "app."). + * + * If @target_format is given, it is used to collect remaining + * positional parameters into a GVariant instance, similar to + * g_variant_new(). @action will be activated with that GVariant as its + * parameter. + * + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_default_action_and_target_value: (rename-to g_notification_set_default_action_and_target) + * @notification: a #GNotification + * @action: an action name + * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL + * + * Sets the default action of @notification to @action. This action is + * activated when the notification is clicked on. It must be an + * application-wide action (start with "app."). + * + * If @target_format is given, it is used to collect remaining + * positional parameters into a GVariant instance, similar to + * g_variant_new(). + * + * If @target is non-%NULL, @action will be activated with @target as + * its parameter. + * + * When no default action is set, the application that the notification + * was sent on is activated. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_icon: + * @notification: a #GNotification + * @icon: the icon to be shown in @notification, as a #GIcon + * + * Sets the icon of @notification to @icon. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_title: + * @notification: a #GNotification + * @title: the new title for @notification + * + * Sets the title of @notification to @title. + * + * Since: 2.40 + */ + + +/** + * g_notification_set_urgent: + * @notification: a #GNotification + * @urgent: %TRUE if @notification is urgent + * + * Sets or unsets whether @notification is marked as urgent. + * + * Since: 2.40 + */ + + +/** * g_null_settings_backend_new: * * Creates a readonly #GSettingsBackend. @@ -24318,6 +27185,16 @@ /** + * g_output_stream_async_write_is_via_threads: + * @stream: a #GOutputStream. + * + * Checks if an ouput stream's write_async function uses threads. + * + * Returns: %TRUE if @stream's write_async function uses threads. + */ + + +/** * g_output_stream_clear_pending: * @stream: output stream * @@ -24390,7 +27267,8 @@ * g_output_stream_close_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Closes an output stream. * @@ -24440,7 +27318,8 @@ * g_output_stream_flush_finish: * @stream: a #GOutputStream. * @result: a GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes flushing an output stream. * @@ -24483,9 +27362,38 @@ /** + * g_output_stream_printf: + * @stream: a #GOutputStream. + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore + * @format: the format string. See the printf() documentation + * @...: the parameters to insert into the format string + * + * This is a utility function around g_output_stream_write_all(). It + * uses g_strdup_vprintf() to turn @format and @... into a string that + * is then written to @stream. + * + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. + * + * Note that partial writes cannot be properly checked with this + * function due to the variable length of the written string, if you + * need precise control over partial write failures, you need to + * create you own printf()-like wrapper around g_output_stream_write() + * or g_output_stream_write_all(). + * + * Since: 2.40 + * Returns: %TRUE on success, %FALSE if there was an error + */ + + +/** * g_output_stream_set_pending: * @stream: a #GOutputStream. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -24501,11 +27409,16 @@ * @source: a #GInputStream. * @flags: a set of #GOutputStreamSpliceFlags. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Splices an input stream into an output stream. * - * Returns: a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. + * Returns: a #gssize containing the size of the data spliced, or + * -1 if an error occurred. Note that if the number of bytes + * spliced is greater than %G_MAXSSIZE, then that will be + * returned, and there is no way to determine the actual number + * of bytes spliced. */ @@ -24533,16 +27446,48 @@ * g_output_stream_splice_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream splice operation. * - * Returns: a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced. + * Returns: a #gssize of the number of bytes spliced. Note that if the + * number of bytes spliced is greater than %G_MAXSSIZE, then that + * will be returned, and there is no way to determine the actual + * number of bytes spliced. + */ + + +/** + * g_output_stream_vprintf: + * @stream: a #GOutputStream. + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @error: location to store the error occurring, or %NULL to ignore + * @format: the format string. See the printf() documentation + * @args: the parameters to insert into the format string + * + * This is a utility function around g_output_stream_write_all(). It + * uses g_strdup_vprintf() to turn @format and @args into a string that + * is then written to @stream. + * + * See the documentation of g_output_stream_write_all() about the + * behavior of the actual write operation. + * + * Note that partial writes cannot be properly checked with this + * function due to the variable length of the written string, if you + * need precise control over partial write failures, you need to + * create you own printf()-like wrapper around g_output_stream_write() + * or g_output_stream_write_all(). + * + * Since: 2.40 + * Returns: %TRUE on success, %FALSE if there was an error */ /** - * g_output_stream_write: + * g_output_stream_write: (virtual write_fn) * @stream: a #GOutputStream. * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. * @count: the number of bytes to write @@ -24570,7 +27515,6 @@ * * On error -1 is returned and @error is set accordingly. * - * Virtual: write_fn * Returns: Number of bytes written, or -1 on error */ @@ -24580,7 +27524,8 @@ * @stream: a #GOutputStream. * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. * @count: the number of bytes to write - * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -24641,6 +27586,11 @@ * * For the synchronous, blocking version of this function, see * g_output_stream_write(). + * + * 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. */ @@ -24651,26 +27601,17 @@ * @cancellable: (allow-none): optional cancellable object * @error: location to store the error occurring, or %NULL to ignore * - * Tries to write the data from @bytes into the stream. Will block - * during the operation. + * A wrapper function for g_output_stream_write() which takes a + * #GBytes as input. This can be more convenient for use by language + * bindings or in other cases where the refcounted nature of #GBytes + * is helpful over a bare pointer interface. * - * If @bytes is 0-length, returns 0 and does nothing. A #GBytes larger - * than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written to the stream is returned. - * It is not an error if this is not the same as the requested size, as it - * can happen e.g. on a partial I/O error, or if there is not enough - * storage in the stream. All writes block until at least one byte - * is written or an error occurs; 0 is never returned (unless - * the size of @bytes is 0). - * - * If @cancellable is not %NULL, then the operation can be cancelled by - * triggering the cancellable object from another thread. If the operation - * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an - * operation was partially finished when the operation was cancelled the - * partial result will be returned, without an error. - * - * On error -1 is returned and @error is set accordingly. + * 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. * * Returns: Number of bytes written, or -1 on error */ @@ -24685,29 +27626,16 @@ * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function * - * Request an asynchronous write of the data in @bytes to the stream. - * When the operation is finished @callback will be called. You can - * then call g_output_stream_write_bytes_finish() to get the result of - * the operation. - * - * During an async request no other sync and async calls are allowed, - * and will result in %G_IO_ERROR_PENDING errors. - * - * A #GBytes larger than %G_MAXSSIZE will cause a - * %G_IO_ERROR_INVALID_ARGUMENT error. - * - * On success, the number of bytes written will be passed to the - * @callback. It is not an error if this is not the same as the - * requested size, as it can happen e.g. on a partial I/O error, - * but generally we try to write as many bytes as requested. - * - * You are guaranteed that this method will never fail with - * %G_IO_ERROR_WOULD_BLOCK - if @stream can't accept more data, the - * method will just wait until this changes. + * 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. * - * Any outstanding I/O request with higher priority (lower numerical - * value) will be executed before an outstanding request with lower - * priority. Default priority is %G_PRIORITY_DEFAULT. + * 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(). @@ -24718,7 +27646,8 @@ * g_output_stream_write_bytes_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream write-from-#GBytes operation. * @@ -24730,7 +27659,8 @@ * g_output_stream_write_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream write operation. * @@ -24973,15 +27903,19 @@ * g_pollable_input_stream_read_nonblocking(), which will return a * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. * - * Returns: %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error. + * Returns: %TRUE if @stream is readable, %FALSE if not. If an error + * has occurred on @stream, this will result in + * g_pollable_input_stream_is_readable() returning %TRUE, and the + * next attempt to read will return the error. * Since: 2.28 */ /** - * g_pollable_input_stream_read_nonblocking: + * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking) * @stream: a #GPollableInputStream - * @buffer: a buffer to read data into (which should be at least @count bytes long). + * @buffer: a buffer to read data into (which should be at least @count + * bytes long). * @count: the number of bytes you want to read * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -24998,8 +27932,8 @@ * may happen if you call this method after a source triggers due * to having been cancelled. * - * Virtual: read_nonblocking - * Returns: the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). + * Returns: the number of bytes read, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ @@ -25052,15 +27986,19 @@ * g_pollable_output_stream_write_nonblocking(), which will return a * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. * - * Returns: %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error. + * Returns: %TRUE if @stream is writable, %FALSE if not. If an error + * has occurred on @stream, this will result in + * g_pollable_output_stream_is_writable() returning %TRUE, and the + * next attempt to write will return the error. * Since: 2.28 */ /** - * g_pollable_output_stream_write_nonblocking: + * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking) * @stream: a #GPollableOutputStream - * @buffer: (array length=count) (element-type guint8): a buffer to write data from + * @buffer: (array length=count) (element-type guint8): a buffer to write + * data from * @count: the number of bytes you want to write * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -25077,8 +28015,8 @@ * may happen if you call this method after a source triggers due * to having been cancelled. * - * Virtual: write_nonblocking - * Returns: the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). + * Returns: the number of bytes written, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ @@ -25099,7 +28037,8 @@ /** * g_pollable_source_new_full: - * @pollable_stream: (type GObject): the stream associated with the new source + * @pollable_stream: (type GObject): the stream associated with the + * new source * @child_source: (allow-none): optional child source to attach * @cancellable: (allow-none): optional #GCancellable to attach * @@ -25140,7 +28079,8 @@ /** * g_pollable_stream_write: * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @buffer: (array length=count) (element-type guint8): the buffer + * containing the data to write. * @count: the number of bytes to write * @blocking: whether to do blocking I/O * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -25165,10 +28105,12 @@ /** * g_pollable_stream_write_all: * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @buffer: (array length=count) (element-type guint8): the buffer + * containing the data to write. * @count: the number of bytes to write * @blocking: whether to do blocking I/O - * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -25197,6 +28139,26 @@ /** + * g_property_action_new: + * @name: the name of the action to create + * @object: the object that has the property to wrap + * @property_name: the name of the property + * + * Creates a #GAction corresponding to the value of property + * @property_name on @object. + * + * The property must be existent and readable and writable (and not + * construct-only). + * + * This function takes a reference on @object and doesn't release it + * until the action is destroyed. + * + * Returns: a new #GPropertyAction + * Since: 2.38 + */ + + +/** * g_proxy_address_get_destination_hostname: * @proxy: a #GProxyAddress * @@ -25285,8 +28247,10 @@ * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). * @dest_hostname: The destination hostname the proxy should tunnel to. * @dest_port: The destination port to tunnel to. - * @username: (allow-none): The username to authenticate to the proxy server (or %NULL). - * @password: (allow-none): The password to authenticate to the proxy server (or %NULL). + * @username: (allow-none): The username to authenticate to the proxy server + * (or %NULL). + * @password: (allow-none): The password to authenticate to the proxy server + * (or %NULL). * * Creates a new #GProxyAddress for @inetaddr with @protocol that should * tunnel through @dest_hostname and @dest_port. @@ -25313,7 +28277,9 @@ * does the necessary handshake to connect to @proxy_address, and if * required, wraps the #GIOStream to handle proxy payload. * - * Returns: (transfer full): a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. + * Returns: (transfer full): a #GIOStream that will replace @connection. This might + * be the same as @connection, in which case a reference + * will be added. * Since: 2.26 */ @@ -25353,7 +28319,8 @@ * Lookup "gio-proxy" extension point for a proxy implementation that supports * specified protocol. * - * Returns: (transfer full): return a #GProxy or NULL if protocol is not supported. + * Returns: (transfer full): return a #GProxy or NULL if protocol + * is not supported. * Since: 2.26 */ @@ -25389,22 +28356,24 @@ * @error: return location for a #GError, or %NULL * * 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. * - * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ @@ -25434,7 +28403,9 @@ * g_proxy_resolver_lookup_async() is complete. See * g_proxy_resolver_lookup() for more details. * - * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ @@ -25563,7 +28534,8 @@ * operation, in which case @error (if non-%NULL) will be set to * %G_IO_ERROR_CANCELLED. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. * Since: 2.22 */ @@ -25597,7 +28569,8 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. * Since: 2.22 */ @@ -25633,7 +28606,10 @@ * address, it may be easier to create a #GNetworkAddress and use its * #GSocketConnectable interface. * - * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.) + * Returns: (element-type GInetAddress) (transfer full): a #GList + * of #GInetAddress, or %NULL on error. You + * must unref each of the addresses and free the list when you are + * done with it. (You can use g_resolver_free_addresses() to do this.) * Since: 2.22 */ @@ -25668,7 +28644,9 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. + * Returns: (element-type GInetAddress) (transfer full): a #GList + * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() + * for more details. * Since: 2.22 */ @@ -25692,7 +28670,9 @@ * operation, in which case @error (if non-%NULL) will be set to * %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) + * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, + * or %NULL on error. You must free each of the records and the list when you are + * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) * Since: 2.34 */ @@ -25729,7 +28709,9 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) + * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, + * or %NULL on error. You must free each of the records and the list when you are + * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) * Since: 2.34 */ @@ -25746,9 +28728,8 @@ * 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 @@ -25766,7 +28747,9 @@ * to create a #GNetworkService and use its #GSocketConnectable * interface. * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.) + * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, + * or %NULL on error. You must free each of the targets and the list when you are + * done with it. (You can use g_resolver_free_targets() to do this.) * Since: 2.22 */ @@ -25804,7 +28787,8 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. + * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, + * or %NULL on error. See g_resolver_lookup_service() for more details. * Since: 2.22 */ @@ -25860,8 +28844,10 @@ * @resource: A #GResource * @path: A pathname inside the resource * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed + * @size: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (allow-none): a location to place the flags about the file, + * or %NULL if the length is not needed * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the resource and @@ -25912,7 +28898,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref() + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() * Since: 2.32 */ @@ -25946,7 +28933,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref() + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() * Since: 2.32 */ @@ -25998,8 +28986,10 @@ * g_resources_get_info: * @path: A pathname inside the resource * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed + * @size: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (allow-none): a location to place the flags about the file, + * or %NULL if the length is not needed * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the set of @@ -26033,7 +29023,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref() + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() * Since: 2.32 */ @@ -26050,7 +29041,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref() + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() * Since: 2.32 */ @@ -26103,15 +29095,27 @@ * @offset: a #goffset. * @type: a #GSeekType. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Seeks in the stream by the given @offset, modified by @type. * + * Attempting to seek past the end of the stream will have different + * results depending on if the stream is fixed-sized or resizable. If + * the stream is resizable then seeking past the end and then writing + * will result in zeros filling the empty space. Seeking past the end + * of a resizable stream and reading will result in EOF. Seeking past + * the end of a fixed-sized stream will fail. + * + * Any operation that would result in a negative offset will fail. + * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ @@ -26126,11 +29130,12 @@ /** - * g_seekable_truncate: + * g_seekable_truncate: (virtual truncate_fn) * @seekable: a #GSeekable. * @offset: a #goffset. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Truncates a stream with a given #offset. * @@ -26140,8 +29145,9 @@ * operation was partially finished when the operation was cancelled the * partial result will be returned, without an error. * - * Virtual: truncate_fn - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ @@ -26207,8 +29213,10 @@ * g_settings_backend_flatten_tree: * @tree: a #GTree containing the changes * @path: (out): the location to save the path - * @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys - * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL + * @keys: (out) (transfer container) (array zero-terminated=1): the + * location to save the relative keys + * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): + * the location to save the values, or %NULL * * Calculate the longest common prefix of all keys in a tree and write * out an array of the key names relative to that prefix and, @@ -26226,8 +29234,8 @@ * g_settings_backend_get_default: * * 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. * @@ -26370,8 +29378,10 @@ * @object: (type GObject.Object): a #GObject * @property: the name of the property to bind * @flags: flags for the binding - * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping - * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping + * @get_mapping: a function that gets called to convert values + * from @settings to @object, or %NULL to use the default GIO mapping + * @set_mapping: a function that gets called to convert values + * from @object to @settings, or %NULL to use the default GIO mapping * @user_data: data that gets passed to @get_mapping and @set_mapping * @destroy: #GDestroyNotify function for @user_data * @@ -26409,8 +29419,7 @@ * * 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. @@ -26498,14 +29507,14 @@ /** * g_settings_get_child: * @settings: a #GSettings object - * @name: the name of the 'child' schema + * @name: the name of the child schema * - * 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. * * Returns: (transfer full): a 'child' settings object * Since: 2.26 @@ -26513,6 +29522,38 @@ /** + * g_settings_get_default_value: + * @settings: a #GSettings object + * @key: the key to get the default value for + * + * Gets the "default value" of a key. + * + * This is the value that would be read if g_settings_reset() were to be + * called on the key. + * + * Note that this may be a different value than returned by + * g_settings_schema_key_get_default_value() if the system administrator + * has provided a default value. + * + * Comparing the return values of g_settings_get_default_value() and + * g_settings_get_value() is not sufficient for determining if a value + * has been set because the user may have explicitly set the value to + * something that happens to be equal to the default. The difference + * here is that if the default changes in the future, the user's key + * will still be set. + * + * This function may be useful for adding an indication to a UI of what + * the default value was before the user set it. + * + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. + * + * Returns: (allow-none) (transfer full): the default value + * Since: 2.40 + */ + + +/** * g_settings_get_double: * @settings: a #GSettings object * @key: the key to get the value for @@ -26608,7 +29649,8 @@ * g_settings_get_mapped: * @settings: a #GSettings object * @key: the key to get the value for - * @mapping: (scope call): the function to map the value in the settings database to the value used by the application + * @mapping: (scope call): the function to map the value in the + * settings database to the value used by the application * @user_data: user data for @mapping * * Gets the value that is stored at @key in @settings, subject to @@ -26650,49 +29692,8 @@ * * 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. - * - * 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 <literal>'enum'</literal> 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>. - * - * 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. - * - * This information should not be used by normal programs. It is - * considered to be a hint for introspection purposes. Normal programs - * should already know what is permitted by their own schema. The - * format may change in any way in the future -- but particularly, new - * forms may be added to the possibilities described above. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * - * You should free the returned value with g_variant_unref() when it is - * no longer needed. - * - * Returns: a #GVariant describing the range * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_key_get_range() instead. */ @@ -26723,7 +29724,9 @@ * It is a programmer error to give a @key that isn't specified as * having an array of strings type in the schema for @settings. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. + * Returns: (array zero-terminated=1) (transfer full): a + * newly-allocated, %NULL-terminated array of strings, the value that + * is stored at @key in @settings. * Since: 2.26 */ @@ -26747,6 +29750,35 @@ /** + * g_settings_get_user_value: + * @settings: a #GSettings object + * @key: the key to get the user value for + * + * Checks the "user value" of a key, if there is one. + * + * The user value of a key is the last value that was set by the user. + * + * After calling g_settings_reset() this function should always return + * %NULL (assuming something is not wrong with the system + * configuration). + * + * It is possible that g_settings_get_value() will return a different + * value than this function. This can happen in the case that the user + * set a value for a key that was subsequently locked down by the system + * administrator -- this function will return the user's old value. + * + * This function may be useful for adding a "reset" option to a UI or + * for providing indication that a particular value has been changed. + * + * It is a programmer error to give a @key that isn't contained in the + * schema for @settings. + * + * Returns: (allow-none) (transfer full): the user's value, if set + * Since: 2.40 + */ + + +/** * g_settings_get_value: * @settings: a #GSettings object * @key: the key to get the value for @@ -26821,34 +29853,25 @@ /** * g_settings_list_relocatable_schemas: * - * Gets a list of the relocatable #GSettings schemas installed on the - * system. These are schemas that do not provide their own path. It is - * usual to instantiate these schemas directly, but if you want to you - * can use g_settings_new_with_path() to specify the path. - * - * The output of this function, taken together with the output of - * g_settings_list_schemas() represents the complete list of all - * installed schemas. - * - * Returns: (element-type utf8) (transfer none): a list of relocatable #GSettings schemas that are available. The list must not be modified or freed. + * Returns: (element-type utf8) (transfer none): a list of relocatable + * #GSettings schemas that are available. The list must not be + * modified or freed. * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead */ /** * g_settings_list_schemas: * - * Gets a list of the #GSettings schemas installed on the system. The - * returned list is exactly the list of schemas for which you may call - * g_settings_new() without adverse effects. - * - * This function does not list the schemas that do not provide their own - * paths (ie: schemas for which you must use - * g_settings_new_with_path()). See - * g_settings_list_relocatable_schemas() for that. - * - * Returns: (element-type utf8) (transfer none): a list of #GSettings schemas that are available. The list must not be modified or freed. + * Returns: (element-type utf8) (transfer none): a list of #GSettings + * schemas that are available. The list must not be modified or + * freed. * Since: 2.26 + * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead. + * If you used g_settings_list_schemas() to check for the presence of + * a particular schema, use g_settings_schema_source_lookup() instead + * of your whole loop. */ @@ -26955,6 +29978,10 @@ * It is a programmer error to call this function for a schema that * has an explicitly specified path. * + * It is a programmer error if @path is not a valid path. A valid path + * begins and ends with '/' and does not contain two consecutive '/' + * characters. + * * Returns: a new #GSettings object * Since: 2.26 */ @@ -26969,15 +29996,9 @@ * Checks if the given @value is of the correct type and within the * permitted range for @key. * - * This API is not intended to be used by normal programs -- they should - * already know what is permitted by their own schemas. This API is - * meant to be used by programs such as editors or commandline tools. - * - * It is a programmer error to give a @key that isn't contained in the - * schema for @settings. - * * Returns: %TRUE if @value is valid for @key * Since: 2.28 + * Deprecated: 2.40: Use g_settings_schema_key_range_check() instead. */ @@ -27018,6 +30039,21 @@ /** + * g_settings_schema_get_key: + * @schema: a #GSettingsSchema + * @name: the name of a key + * + * Gets the key named @name from @schema. + * + * It is a programmer error to request a key that does not exist. See + * g_settings_schema_list_keys(). + * + * Returns: (transfer full): the #GSettingsSchemaKey for @name + * Since: 2.40 + */ + + +/** * g_settings_schema_get_path: * @schema: a #GSettingsSchema * @@ -27037,6 +30073,173 @@ /** + * g_settings_schema_has_key: + * @schema: a #GSettingsSchema + * @name: the name of a key + * + * Checks if @schema has a key named @name. + * + * Returns: %TRUE if such a key exists + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_get_default_value: + * @key: a #GSettingsSchemaKey + * + * Gets the default value for @key. + * + * Note that this is the default value according to the schema. System + * administrator defaults and lockdown are not visible via this API. + * + * Returns: (transfer full): the default value for the key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_get_description: + * @key: a #GSettingsSchemaKey + * + * Gets the description for @key. + * + * If no description has been provided in the schema for @key, returns + * %NULL. + * + * The description can be one sentence to several paragraphs in length. + * Paragraphs are delimited with a double newline. Descriptions can be + * translated and the value returned from this function is is the + * current locale. + * + * This function is slow. The summary and description information for + * the schemas is not stored in the compiled schema database so this + * function has to parse all of the source XML files in the schema + * directory. + * + * Returns: the description for @key, or %NULL + * Since: 2.34 + */ + + +/** + * g_settings_schema_key_get_range: + * @key: a #GSettingsSchemaKey + * + * 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 `(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 `'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 `'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 `'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 `'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 + * should already know what is permitted by their own schema. The + * format may change in any way in the future -- but particularly, new + * forms may be added to the possibilities described above. + * + * You should free the returned value with g_variant_unref() when it is + * no longer needed. + * + * Returns: (transfer full): a #GVariant describing the range + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_get_summary: + * @key: a #GSettingsSchemaKey + * + * Gets the summary for @key. + * + * If no summary has been provided in the schema for @key, returns + * %NULL. + * + * The summary is a short description of the purpose of the key; usually + * one short sentence. Summaries can be translated and the value + * returned from this function is is the current locale. + * + * This function is slow. The summary and description information for + * the schemas is not stored in the compiled schema database so this + * function has to parse all of the source XML files in the schema + * directory. + * + * Returns: the summary for @key, or %NULL + * Since: 2.34 + */ + + +/** + * g_settings_schema_key_get_value_type: + * @key: a #GSettingsSchemaKey + * + * Gets the #GVariantType of @key. + * + * Returns: (transfer none): the type of @key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_range_check: + * @key: a #GSettingsSchemaKey + * @value: the value to check + * + * Checks if the given @value is of the correct type and within the + * permitted range for @key. + * + * It is a programmer error if @value is not of the correct type -- you + * must check for this first. + * + * Returns: %TRUE if @value is valid for @key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_ref: + * @key: a #GSettingsSchemaKey + * + * Increase the reference count of @key, returning a new reference. + * + * Returns: a new reference to @key + * Since: 2.40 + */ + + +/** + * g_settings_schema_key_unref: + * @key: a #GSettingsSchemaKey + * + * Decrease the reference count of @key, possibly freeing it. + * + * Since: 2.40 + */ + + +/** * g_settings_schema_ref: * @schema: a #GSettingsSchema * @@ -27060,9 +30263,8 @@ * * 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. * * Returns: (transfer none): the default schema source @@ -27071,6 +30273,31 @@ /** + * g_settings_schema_source_list_schemas: + * @source: a #GSettingsSchemaSource + * @recursive: if we should recurse + * @non_relocatable: (out) (transfer full): the list of non-relocatable + * schemas + * @relocatable: (out) (transfer full): the list of relocatable schemas + * + * Lists the schemas in a given source. + * + * If @recursive is %TRUE then include parent sources. If %FALSE then + * only include the schemas from one source (ie: one directory). You + * probably want %TRUE. + * + * Non-relocatable schemas are those for which you can call + * g_settings_new(). Relocatable schemas are those for which you must + * use g_settings_new_with_path(). + * + * Do not call this function from normal programs. This is designed for + * use by database editors, commandline tools, etc. + * + * Since: 2.40 + */ + + +/** * g_settings_schema_source_lookup: * @source: a #GSettingsSchemaSource * @schema_id: a schema ID @@ -27105,16 +30332,14 @@ * 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. * @@ -27123,8 +30348,8 @@ * 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 @@ -27181,7 +30406,8 @@ * schema for @settings or for the #GVariantType of @format to mismatch * the type given in the schema. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27199,7 +30425,8 @@ * It is a programmer error to give a @key that isn't specified as * having a boolean type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27217,7 +30444,8 @@ * It is a programmer error to give a @key that isn't specified as * having a 'double' type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27278,7 +30506,8 @@ * It is a programmer error to give a @key that isn't specified as * having a int32 type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27296,7 +30525,8 @@ * It is a programmer error to give a @key that isn't specified as * having a string type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27315,7 +30545,8 @@ * It is a programmer error to give a @key that isn't specified as * having an array of strings type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27334,7 +30565,8 @@ * It is a programmer error to give a @key that isn't specified as * having a uint32 type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.30 */ @@ -27353,7 +30585,8 @@ * * If @value is floating then this function consumes the reference. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -27393,7 +30626,8 @@ /** * g_simple_action_group_add_entries: * @simple: a #GSimpleActionGroup - * @entries: (array length=n_entries): a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries): a pointer to the first item in + * an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 * @user_data: the user data for signal connections * @@ -27401,6 +30635,7 @@ * and adding them to the action group. * * Since: 2.30 + * Deprecated: 2.38: Use g_action_map_add_action_entries() */ @@ -27417,6 +30652,7 @@ * The action group takes its own reference on @action. * * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_add_action() */ @@ -27431,6 +30667,7 @@ * * Returns: (transfer none): a #GAction, or %NULL * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_lookup_action() */ @@ -27454,6 +30691,7 @@ * If no action of this name is in the group then nothing happens. * * Since: 2.28 + * Deprecated: 2.38: Use g_action_map_remove_action() */ @@ -27520,6 +30758,8 @@ * property. Instead, they should call g_action_change_state() to * request the change. * + * If the @value GVariant is floating, it is consumed. + * * Since: 2.30 */ @@ -27586,9 +30826,9 @@ * g_simple_async_result_complete_in_idle: * @simple: a #GSimpleAsyncResult. * - * 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 @@ -27602,7 +30842,8 @@ * * Gets the operation result boolean from within the asynchronous result. * - * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE. + * Returns: %TRUE if the operation's result was %TRUE, %FALSE + * if the operation's result was %FALSE. */ @@ -27639,8 +30880,8 @@ /** * g_simple_async_result_is_valid: * @result: the #GAsyncResult passed to the _finish function. - * @source: the #GObject passed to the _finish function. - * @source_tag: the asynchronous function. + * @source: (allow-none): the #GObject passed to the _finish function. + * @source_tag: (allow-none): the asynchronous function. * * Ensures that the data passed to the _finish function of an async * operation is consistent. Three checks are performed. @@ -27648,12 +30889,12 @@ * 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.) * * Returns: #TRUE if all checks passed or #FALSE if any failed. * Since: 2.20 @@ -27884,6 +31125,74 @@ /** + * g_simple_proxy_resolver_new: + * @default_proxy: (allow-none): the default proxy to use, eg + * "socks://192.168.1.1" + * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses + * to not use a proxy for. + * + * Creates a new #GSimpleProxyResolver. See + * #GSimpleProxyResolver:default-proxy and + * #GSimpleProxyResolver:ignore-hosts for more details on how the + * arguments are interpreted. + * + * Returns: (transfer full): a new #GSimpleProxyResolver + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_default_proxy: + * @resolver: a #GSimpleProxyResolver + * @default_proxy: the default proxy to use + * + * 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 "socks://", + * #GSimpleProxyResolver will treat it as referring to all three of + * the socks5, socks4a, and socks4 proxy types. + * + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_ignore_hosts: + * @resolver: a #GSimpleProxyResolver + * @ignore_hosts: %NULL-terminated list of hosts/IP addresses + * to not use a proxy for + * + * Sets the list of ignored hosts. + * + * See #GSimpleProxyResolver:ignore-hosts for more details on how the + * @ignore_hosts argument is interpreted. + * + * Since: 2.36 + */ + + +/** + * g_simple_proxy_resolver_set_uri_proxy: + * @resolver: a #GSimpleProxyResolver + * @uri_scheme: the URI scheme to add a proxy for + * @proxy: the proxy to use for @uri_scheme + * + * Adds a URI-scheme-specific proxy to @resolver; URIs whose scheme + * 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 + * "socks://", #GSimpleProxyResolver will treat it + * as referring to all three of the socks5, socks4a, and socks4 proxy + * types. + * + * Since: 2.36 + */ + + +/** * g_socket_accept: * @socket: a #GSocket. * @cancellable: (allow-none): a %GCancellable or %NULL @@ -27900,7 +31209,8 @@ * or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled. * To be notified of an incoming connection, wait for the %G_IO_IN condition. * - * Returns: (transfer full): a new #GSocket, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GSocket, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -27925,7 +31235,9 @@ * internal errors (other than @cancellable being triggered) will be * ignored. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses. + * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * error (in which case *@error will be set) or if there are no + * more addresses. */ @@ -27933,7 +31245,8 @@ * g_socket_address_enumerator_next_async: * @enumerator: a #GSocketAddressEnumerator * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the request + * is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously retrieves the next #GSocketAddress from @enumerator @@ -27953,7 +31266,9 @@ * g_socket_address_enumerator_next() for more information about * error handling. * - * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case *@error will be set) or if there are no more addresses. + * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on + * error (in which case *@error will be set) or if there are no + * more addresses. */ @@ -27963,7 +31278,7 @@ * * Gets the socket family type of @address. * - * Returns: the socket family type of @address. + * Returns: the socket family type of @address * Since: 2.22 */ @@ -27972,24 +31287,26 @@ * g_socket_address_get_native_size: * @address: a #GSocketAddress * - * 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(). * - * Returns: the size of the native <type>struct sockaddr</type> that @address represents + * Returns: the size of the native struct sockaddr that + * @address represents * Since: 2.22 */ /** * g_socket_address_new_from_native: - * @native: a pointer to a <type>struct sockaddr</type> + * @native: a pointer to a struct sockaddr * @len: the size of the memory location pointed to by @native * * Creates a #GSocketAddress subclass corresponding to the native - * <type>struct sockaddr</type> @native. + * struct sockaddr @native. * - * Returns: a new #GSocketAddress if @native could successfully be converted, otherwise %NULL. + * Returns: a new #GSocketAddress if @native could successfully + * be converted, otherwise %NULL * Since: 2.22 */ @@ -27997,16 +31314,17 @@ /** * g_socket_address_to_native: * @address: a #GSocketAddress - * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>. - * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size(). - * @error: #GError for error reporting, or %NULL to ignore. + * @dest: a pointer to a memory location that will contain the native + * struct sockaddr + * @destlen: the size of @dest. Must be at least as large as + * g_socket_address_get_native_size() + * @error: #GError for error reporting, or %NULL to ignore * - * 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. * * Returns: %TRUE if @dest was filled in, %FALSE on error @@ -28030,14 +31348,20 @@ * In certain situations, you may also want to bind a socket that will be * used to initiate connections, though this is not normally required. * - * @allow_reuse should be %TRUE for server sockets (sockets that you will - * eventually call g_socket_accept() on), and %FALSE for client sockets. - * (Specifically, if it is %TRUE, then g_socket_bind() will set the - * %SO_REUSEADDR flag on the socket, allowing it to bind @address even if - * that address was previously used by another socket that has not yet been - * fully cleaned-up by the kernel. Failing to set this flag on a server - * socket may cause the bind call to return %G_IO_ERROR_ADDRESS_IN_USE if - * the server program is stopped and then immediately restarted.) + * If @socket is a TCP socket, then @allow_reuse controls the setting + * 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 + * time. In particular, you can have several UDP sockets bound to the + * same address, and they will all receive all of the multicast and + * broadcast packets sent to that address. (The behavior of unicast + * UDP packets to an address with multiple listeners is not defined.) * * Returns: %TRUE on success, %FALSE on error. * Since: 2.22 @@ -28138,7 +31462,8 @@ * g_socket_client_connect_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_async() * @@ -28214,7 +31539,8 @@ * g_socket_client_connect_to_host_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_host_async() * @@ -28270,7 +31596,8 @@ * g_socket_client_connect_to_service_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_service_async() * @@ -28337,7 +31664,8 @@ * g_socket_client_connect_to_uri_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() * @@ -28397,6 +31725,20 @@ /** + * g_socket_client_get_proxy_resolver: + * @client: a #GSocketClient. + * + * Gets the #GProxyResolver being used by @client. Normally, this will + * be the resolver returned by g_proxy_resolver_get_default(), but you + * can override it with g_socket_client_set_proxy_resolver(). + * + * Returns: (transfer none): The #GProxyResolver being used by + * @client. + * Since: 2.36 + */ + + +/** * g_socket_client_get_socket_type: * @client: a #GSocketClient. * @@ -28451,7 +31793,8 @@ * * Creates a new #GSocketClient with the default options. * - * Returns: a #GSocketClient. Free the returned object with g_object_unref(). + * Returns: a #GSocketClient. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -28466,6 +31809,8 @@ * #GProxyResolver to determine if a proxy protocol such as SOCKS is * needed, and automatically do the necessary proxy negotiation. * + * See also g_socket_client_set_proxy_resolver(). + * * Since: 2.26 */ @@ -28522,6 +31867,24 @@ /** + * g_socket_client_set_proxy_resolver: + * @client: a #GSocketClient. + * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the + * default. + * + * Overrides the #GProxyResolver used by @client. You can call this if + * you want to use specific proxies, rather than using the system + * default proxy settings. + * + * Note that whether or not the proxy resolver is actually used + * depends on the setting of #GSocketClient:enable-proxy, which is not + * changed by this function (but which is %TRUE by default) + * + * Since: 2.36 + */ + + +/** * g_socket_client_set_socket_type: * @client: a #GSocketClient. * @type: a #GSocketType @@ -28759,7 +32122,7 @@ * @connectable: a #GSocketConnectable * * 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 @@ -28868,7 +32231,8 @@ * * Try to get the local address of a socket connection. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -28880,7 +32244,15 @@ * * Try to get the remote address of a socket connection. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Since GLib 2.40, when used with g_socket_client_connect() or + * g_socket_client_connect_async(), during emission of + * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote + * address that will be used for the connection. This allows + * applications to print e.g. "Connecting to example.com + * (10.42.77.3)...". + * + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29019,7 +32391,19 @@ * * Get the amount of data pending in the OS input buffer. * - * Returns: the number of bytes that can be read from the socket without blocking or -1 on error. + * If @socket is a UDP or SCTP socket, this will return the size of + * just the next packet, even if additional packets are buffered after + * that one. + * + * Note that on Windows, this function is rather inefficient in the + * UDP case, and so if you know any plausible upper bound on the size + * of the incoming packet, it is better to just do a + * g_socket_receive() with a buffer of that size, rather than calling + * g_socket_get_available_bytes() first and then doing a receive of + * exactly the right size. + * + * Returns: the number of bytes that can be read from the socket + * without blocking or truncating, or -1 on error. * Since: 2.32 */ @@ -29042,7 +32426,7 @@ * * Gets the broadcast setting on @socket; if %TRUE, * it is possible to send packets to broadcast - * addresses or receive from broadcast addresses. + * addresses. * * Returns: the broadcast setting on @socket * Since: 2.32 @@ -29067,7 +32451,8 @@ * g_unix_connection_send_credentials() / * g_unix_connection_receive_credentials() functions. * - * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref(). + * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object + * that must be freed with g_object_unref(). * Since: 2.26 */ @@ -29131,7 +32516,8 @@ * useful if the socket has been bound to a local address, * either explicitly or implicitly when connecting. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29162,6 +32548,35 @@ /** + * g_socket_get_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, `SOL_SOCKET`) + * @optname: the "name" of the option (eg, `SO_BROADCAST`) + * @value: (out): return location for the option value + * @error: #GError for error reporting, or %NULL to ignore. + * + * Gets the value of an integer-valued option on @socket, as with + * getsockopt(). (If you need to fetch a non-integer-valued option, + * you will need to call getsockopt() directly.) + * + * 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 + * headers. + * + * Note that even for socket options that are a single byte in size, + * @value is still a pointer to a #gint variable, not a #guchar; + * g_socket_get_option() will handle the conversion internally. + * + * Returns: success or failure. On failure, @error will be set, and + * the system error value (`errno` or WSAGetLastError()) will still + * be set to the result of the getsockopt() call. + * Since: 2.36 + */ + + +/** * g_socket_get_protocol: * @socket: a #GSocket. * @@ -29181,7 +32596,8 @@ * Try to get the remove address of a connected socket. This is only * useful for connection oriented sockets that have been connected. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29354,7 +32770,8 @@ * @listener: a #GSocketListener * @result: a #GAsyncResult. * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async accept operation. See g_socket_listener_accept_async() * @@ -29412,7 +32829,8 @@ * @listener: a #GSocketListener * @result: a #GAsyncResult. * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async accept operation. See g_socket_listener_accept_socket_async() * @@ -29460,7 +32878,8 @@ * g_socket_listener_add_any_inet_port: * @listener: a #GSocketListener * @source_object: (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Listens for TCP connections on any available port number for both * IPv6 and IPv4 (if each is available). @@ -29576,7 +32995,8 @@ * system, so you can use protocols not listed in #GSocketProtocol if you * know the protocol number used for it. * - * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref(). + * Returns: a #GSocket or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29594,7 +33014,8 @@ * will be set to non-blocking mode, independent on the blocking * mode of the #GSocket. * - * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref(). + * Returns: a #GSocket or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29602,7 +33023,8 @@ /** * g_socket_receive: * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29631,7 +33053,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -29639,8 +33062,10 @@ /** * g_socket_receive_from: * @socket: a #GSocket - * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL - * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). + * @address: (out) (allow-none): a pointer to a #GSocketAddress + * pointer, or %NULL + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29653,7 +33078,8 @@ * * See g_socket_receive() for additional information. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -29661,11 +33087,14 @@ /** * g_socket_receive_message: * @socket: a #GSocket - * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL + * @address: (out) (allow-none): a pointer to a #GSocketAddress + * pointer, or %NULL * @vectors: (array length=num_vectors): an array of #GInputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL - * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL + * @messages: (array length=num_messages) (allow-none): a pointer which + * may be filled with an array of #GSocketControlMessages, or %NULL + * @num_messages: a pointer which will be filled with the number of + * elements in @messages, or %NULL * @flags: a pointer to an int containing #GSocketMsgFlags flags * @cancellable: (allow-none): a %GCancellable or %NULL * @error: a #GError pointer, or %NULL @@ -29728,7 +33157,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -29736,7 +33166,8 @@ /** * g_socket_receive_with_blocking: * @socket: a #GSocket - * @buffer: a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29746,7 +33177,8 @@ * the choice of blocking or non-blocking behavior is determined by * the @blocking argument rather than by @socket's properties. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.26 */ @@ -29754,7 +33186,8 @@ /** * g_socket_send: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29774,7 +33207,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -29785,7 +33219,8 @@ * @address: (allow-none): a #GSocketAddress, or %NULL * @vectors: (array length=num_vectors): an array of #GOutputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL. + * @messages: (array length=num_messages) (allow-none): a pointer to an + * array of #GSocketControlMessages, or %NULL. * @num_messages: number of elements in @messages, or -1. * @flags: an int containing #GSocketMsgFlags flags * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29803,7 +33238,7 @@ * 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(). * @@ -29829,7 +33264,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -29838,7 +33274,8 @@ * g_socket_send_to: * @socket: a #GSocket * @address: (allow-none): a #GSocketAddress, or %NULL - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -29849,7 +33286,8 @@ * * See g_socket_send() for additional information. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -29857,7 +33295,8 @@ /** * g_socket_send_with_blocking: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -29867,7 +33306,8 @@ * the choice of blocking or non-blocking behavior is determined by * the @blocking argument rather than by @socket's properties. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.26 */ @@ -29922,6 +33362,12 @@ * 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 */ @@ -29947,10 +33393,11 @@ /** * g_socket_set_broadcast: * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses + * @broadcast: whether @socket should allow sending to broadcast + * addresses * - * Sets whether @socket should allow sending to and receiving from - * broadcast addresses. This is %FALSE by default. + * Sets whether @socket should allow sending to broadcast addresses. + * This is %FALSE by default. * * Since: 2.32 */ @@ -30001,7 +33448,8 @@ /** * g_socket_set_multicast_loopback: * @socket: a #GSocket. - * @loopback: whether @socket should receive messages sent to its multicast groups from the local host + * @loopback: whether @socket should receive messages sent to its + * multicast groups from the local host * * Sets whether outgoing multicast packets will be received by sockets * listening on that multicast address on the same host. This is %TRUE @@ -30025,6 +33473,31 @@ /** + * g_socket_set_option: + * @socket: a #GSocket + * @level: the "API level" of the option (eg, `SOL_SOCKET`) + * @optname: the "name" of the option (eg, `SO_BROADCAST`) + * @value: the value to set the option to + * @error: #GError for error reporting, or %NULL to ignore. + * + * Sets the value of an integer-valued option on @socket, as with + * setsockopt(). (If you need to set a non-integer-valued option, + * you will need to call setsockopt() directly.) + * + * 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 + * headers. + * + * Returns: success or failure. On failure, @error will be set, and + * the system error value (`errno` or WSAGetLastError()) will still + * be set to the result of the setsockopt() call. + * Since: 2.36 + */ + + +/** * g_socket_set_timeout: * @socket: a #GSocket. * @timeout: the timeout for @socket, in seconds, or 0 for none @@ -30203,7 +33676,7 @@ * * 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. * * Returns: a new #GSrvTarget. @@ -30218,7 +33691,7 @@ * 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 @@ -30232,7 +33705,7 @@ * 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. * * Returns: (transfer none): a #GResource @@ -30248,7 +33721,7 @@ * 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 @@ -30256,6 +33729,1322 @@ /** + * g_subprocess_communicate: + * @subprocess: a #GSubprocess + * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL + * @cancellable: a #GCancellable + * @stdout_buf: (out): data read from the subprocess stdout + * @stderr_buf: (out): data read from the subprocess stderr + * @error: a pointer to a %NULL #GError pointer, or %NULL + * + * Communicate with the subprocess until it terminates, and all input + * and output has been completed. + * + * If @stdin_buf is given, the subprocess must have been created with + * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the + * stdin of the subprocess and the pipe is closed (ie: EOF). + * + * At the same time (as not to cause blocking when dealing with large + * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or + * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those + * streams. The data that was read is returned in @stdout and/or + * the @stderr. + * + * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, + * @stdout_buf will contain the data read from stdout. Otherwise, for + * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, + * @stdout_buf will be set to %NULL. Similar provisions apply to + * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE. + * + * As usual, any output variable may be given as %NULL to ignore it. + * + * If you desire the stdout and stderr data to be interleaved, create + * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and + * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned + * in @stdout_buf and @stderr_buf will be set to %NULL. + * + * In case of any error (including cancellation), %FALSE will be + * returned with @error set. Some or all of the stdin data may have + * been written. Any stdout or stderr data that has been read will be + * discarded. None of the out variables (aside from @error) will have + * been set to anything in particular and should not be inspected. + * + * In the case that %TRUE is returned, the subprocess has exited and the + * exit status inspection APIs (eg: g_subprocess_get_if_exited(), + * g_subprocess_get_exit_status()) may be used. + * + * You should not attempt to use any of the subprocess pipes after + * starting this function, since they may be left in strange states, + * even if the operation was cancelled. You should especially not + * attempt to interact with the pipes while the operation is in progress + * (either from another thread or if using the asynchronous version). + * + * Returns: %TRUE if successful + * Since: 2.40 + */ + + +/** + * g_subprocess_communicate_async: + * @subprocess: Self + * @stdin_buf: (allow-none): Input data, or %NULL + * @cancellable: (allow-none): Cancellable + * @callback: Callback + * @user_data: User data + * + * Asynchronous version of g_subprocess_communicate(). Complete + * invocation with g_subprocess_communicate_finish(). + */ + + +/** + * g_subprocess_communicate_finish: + * @subprocess: Self + * @result: Result + * @stdout_buf: (out): Return location for stdout data + * @stderr_buf: (out): Return location for stderr data + * @error: Error + * + * Complete an invocation of g_subprocess_communicate_async(). + */ + + +/** + * g_subprocess_communicate_utf8: + * @subprocess: a #GSubprocess + * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL + * @cancellable: a #GCancellable + * @stdout_buf: (out): data read from the subprocess stdout + * @stderr_buf: (out): data read from the subprocess stderr + * @error: a pointer to a %NULL #GError pointer, or %NULL + * + * Like g_subprocess_communicate(), but validates the output of the + * process as UTF-8, and returns it as a regular NUL terminated string. + */ + + +/** + * g_subprocess_communicate_utf8_async: + * @subprocess: Self + * @stdin_buf: (allow-none): Input data, or %NULL + * @cancellable: Cancellable + * @callback: Callback + * @user_data: User data + * + * Asynchronous version of g_subprocess_communicate_utf(). Complete + * invocation with g_subprocess_communicate_utf8_finish(). + */ + + +/** + * g_subprocess_communicate_utf8_finish: + * @subprocess: Self + * @result: Result + * @stdout_buf: (out): Return location for stdout data + * @stderr_buf: (out): Return location for stderr data + * @error: Error + * + * Complete an invocation of g_subprocess_communicate_utf8_async(). + */ + + +/** + * g_subprocess_force_exit: + * @subprocess: a #GSubprocess + * + * Use an operating-system specific method to attempt an immediate, + * forceful termination of the process. There is no mechanism to + * determine whether or not the request itself was successful; + * however, you can use g_subprocess_wait() to monitor the status of + * the process after calling this function. + * + * On Unix, this function sends %SIGKILL. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_get_exit_status: + * @subprocess: a #GSubprocess + * + * Check the exit status of the subprocess, given that it exited + * normally. This is the value passed to the exit() system call or the + * return value from main. + * + * This is equivalent to the system WEXITSTATUS macro. + * + * It is an error to call this function before g_subprocess_wait() and + * unless g_subprocess_get_if_exited() returned %TRUE. + * + * Returns: the exit status + * Since: 2.40 + */ + + +/** + * g_subprocess_get_identifier: + * @subprocess: a #GSubprocess + * + * On UNIX, returns the process ID as a decimal string. On Windows, + * returns the result of GetProcessId() also as a string. + */ + + +/** + * g_subprocess_get_if_exited: + * @subprocess: a #GSubprocess + * + * Check if the given subprocess exited normally (ie: by way of exit() + * or return from main()). + * + * This is equivalent to the system WIFEXITED macro. + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the case of a normal exit + * Since: 2.40 + */ + + +/** + * g_subprocess_get_if_signaled: + * @subprocess: a #GSubprocess + * + * Check if the given subprocess terminated in response to a signal. + * + * This is equivalent to the system WIFSIGNALED macro. + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the case of termination due to a signal + * Since: 2.40 + */ + + +/** + * g_subprocess_get_status: + * @subprocess: a #GSubprocess + * + * Gets the raw status code of the process, as from waitpid(). + * + * This value has no particular meaning, but it can be used with the + * macros defined by the system headers such as WIFEXITED. It can also + * be used with g_spawn_check_exit_status(). + * + * It is more likely that you want to use g_subprocess_get_if_exited() + * followed by g_subprocess_get_exit_status(). + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: the (meaningless) waitpid() exit status from the kernel + * Since: 2.40 + */ + + +/** + * g_subprocess_get_stderr_pipe: + * @subprocess: a #GSubprocess + * + * Gets the #GInputStream from which to read the stderr output of + * @subprocess. + * + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDERR_PIPE. + * + * Returns: (transfer none): the stderr pipe + * Since: 2.40 + */ + + +/** + * g_subprocess_get_stdin_pipe: + * @subprocess: a #GSubprocess + * + * Gets the #GOutputStream that you can write to in order to give data + * to the stdin of @subprocess. + * + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDIN_PIPE. + * + * Returns: (transfer none): the stdout pipe + * Since: 2.40 + */ + + +/** + * g_subprocess_get_stdout_pipe: + * @subprocess: a #GSubprocess + * + * Gets the #GInputStream from which to read the stdout output of + * @subprocess. + * + * The process must have been created with + * %G_SUBPROCESS_FLAGS_STDOUT_PIPE. + * + * Returns: (transfer none): the stdout pipe + * Since: 2.40 + */ + + +/** + * g_subprocess_get_successful: + * @subprocess: a #GSubprocess + * + * Checks if the process was "successful". A process is considered + * successful if it exited cleanly with an exit status of 0, either by + * way of the exit() system call or return from main(). + * + * It is an error to call this function before g_subprocess_wait() has + * returned. + * + * Returns: %TRUE if the process exited cleanly with a exit status of 0 + * Since: 2.40 + */ + + +/** + * g_subprocess_get_term_sig: + * @subprocess: a #GSubprocess + * + * Get the signal number that caused the subprocess to terminate, given + * that it terminated due to a signal. + * + * This is equivalent to the system WTERMSIG macro. + * + * It is an error to call this function before g_subprocess_wait() and + * unless g_subprocess_get_if_signaled() returned %TRUE. + * + * Returns: the signal causing termination + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_getenv: + * @self: a #GSubprocess + * @variable: the environment variable to get + * + * Returns the value of the environment variable @variable in the + * environment of processes launched from this launcher. + * + * The returned string is in the GLib file name encoding. On UNIX, this + * means that it can be an arbitrary byte string. On Windows, it will + * be UTF-8. + * + * Returns: the value of the environment variable, %NULL if unset + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_new: + * @flags: #GSubprocessFlags + * + * Creates a new #GSubprocessLauncher. + * + * The launcher is created with the default options. A copy of the + * environment of the calling process is made at the time of this call + * and will be used as the environment that the process is launched in. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_child_setup: + * @self: a #GSubprocessLauncher + * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function + * @user_data: user data for @child_setup + * @destroy_notify: a #GDestroyNotify for @user_data + * + * Sets up a child setup function. + * + * The child setup function will be called after fork() but before + * exec() on the child's side. + * + * @destroy_notify will not be automatically called on the child's side + * of the fork(). It will only be called when the last reference on the + * #GSubprocessLauncher is dropped or when a new child setup function is + * given. + * + * %NULL can be given as @child_setup to disable the functionality. + * + * Child setup functions are only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_cwd: + * @self: a #GSubprocess + * @cwd: the cwd for launched processes + * + * Sets the current working directory that processes will be launched + * with. + * + * By default processes are launched with the current working directory + * of the launching process at the time of launch. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_environ: + * @self: a #GSubprocess + * @env: the replacement environment + * + * Replace the entire environment of processes launched from this + * launcher with the given 'environ' variable. + * + * Typically you will build this variable by using g_listenv() to copy + * the process 'environ' and using the functions g_environ_setenv(), + * g_environ_unsetenv(), etc. + * + * As an alternative, you can use g_subprocess_launcher_setenv(), + * g_subprocess_launcher_unsetenv(), etc. + * + * All strings in this array are expected to be in the GLib file name + * encoding. On UNIX, this means that they can be arbitrary byte + * strings. On Windows, they should be in UTF-8. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_flags: + * @self: a #GSubprocessLauncher + * @flags: #GSubprocessFlags + * + * Sets the flags on the launcher. + * + * The default flags are %G_SUBPROCESS_FLAGS_NONE. + * + * You may not set flags that specify conflicting options for how to + * handle a particular stdio stream (eg: specifying both + * %G_SUBPROCESS_FLAGS_STDIN_PIPE and + * %G_SUBPROCESS_FLAGS_STDIN_INHERIT). + * + * You may also not set a flag that conflicts with a previous call to a + * function like g_subprocess_launcher_set_stdin_file_path() or + * g_subprocess_launcher_take_stdout_fd(). + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_stderr_file_path: + * @self: a #GSubprocessLauncher + * @path: a filename or %NULL + * + * Sets the file path to use as the stderr for spawned processes. + * + * If @path is %NULL then any previously given path is unset. + * + * The file will be created or truncated when the process is spawned, as + * would be the case if using '2>' at the shell. + * + * If you want to send both stdout and stderr to the same file then use + * %G_SUBPROCESS_FLAGS_STDERR_MERGE. + * + * You may not set a stderr file path if a stderr fd is already set or + * if the launcher flags contain any flags directing stderr elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_stdin_file_path: + * @self: a #GSubprocessLauncher + * @path: a filename or %NULL + * + * Sets the file path to use as the stdin for spawned processes. + * + * If @path is %NULL then any previously given path is unset. + * + * The file must exist or spawning the process will fail. + * + * You may not set a stdin file path if a stdin fd is already set or if + * the launcher flags contain any flags directing stdin elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_set_stdout_file_path: + * @self: a #GSubprocessLauncher + * @path: a filename or %NULL + * + * Sets the file path to use as the stdout for spawned processes. + * + * If @path is %NULL then any previously given path is unset. + * + * The file will be created or truncated when the process is spawned, as + * would be the case if using '>' at the shell. + * + * You may not set a stdout file path if a stdout fd is already set or + * if the launcher flags contain any flags directing stdout elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_setenv: + * @self: a #GSubprocess + * @variable: the environment variable to set, must not contain '=' + * @value: the new value for the variable + * @overwrite: whether to change the variable if it already exists + * + * Sets the environment variable @variable in the environment of + * processes launched from this launcher. + * + * Both the variable's name and value should be in the GLib file name + * encoding. On UNIX, this means that they can be arbitrary byte + * strings. On Windows, they should be in UTF-8. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_spawn: + * @self: a #GSubprocessLauncher + * @error: Error + * @argv0: Command line arguments + * @...: Continued arguments, %NULL terminated + * + * A convenience helper for creating a #GSubprocess given a provided + * varargs list of arguments. + * + * Since: 2.40 + * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + */ + + +/** + * g_subprocess_launcher_spawnv: + * @self: a #GSubprocessLauncher + * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments + * @error: Error + * + * A convenience helper for creating a #GSubprocess given a provided + * array of arguments. + * + * Since: 2.40 + * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set) + */ + + +/** + * g_subprocess_launcher_take_fd: + * @self: a #GSubprocessLauncher + * @source_fd: File descriptor in parent process + * @target_fd: Target descriptor for child process + * + * Transfer an arbitrary file descriptor from parent process to the + * child. This function takes "ownership" of the fd; it will be closed + * in the parent when @self is freed. + * + * By default, all file descriptors from the parent will be closed. + * This function allows you to create (for example) a custom pipe() or + * socketpair() before launching the process, and choose the target + * descriptor in the child. + * + * An example use case is GNUPG, which has a command line argument + * --passphrase-fd providing a file descriptor number where it expects + * the passphrase to be written. + */ + + +/** + * g_subprocess_launcher_take_stderr_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 + * + * Sets the file descriptor to use as the stderr for spawned processes. + * + * If @fd is -1 then any previously given fd is unset. + * + * Note that the default behaviour is to pass stderr through to the + * stderr of the parent process. + * + * The passed @fd belongs to the #GSubprocessLauncher. It will be + * automatically closed when the launcher is finalized. The file + * descriptor will also be closed on the child side when executing the + * spawned process. + * + * You may not set a stderr fd if a stderr file path is already set or + * if the launcher flags contain any flags directing stderr elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_take_stdin_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 + * + * Sets the file descriptor to use as the stdin for spawned processes. + * + * If @fd is -1 then any previously given fd is unset. + * + * Note that if your intention is to have the stdin of the calling + * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT + * is a better way to go about doing that. + * + * The passed @fd is noted but will not be touched in the current + * process. It is therefore necessary that it be kept open by the + * caller until the subprocess is spawned. The file descriptor will + * also not be explicitly closed on the child side, so it must be marked + * O_CLOEXEC if that's what you want. + * + * You may not set a stdin fd if a stdin file path is already set or if + * the launcher flags contain any flags directing stdin elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_take_stdout_fd: + * @self: a #GSubprocessLauncher + * @fd: a file descriptor, or -1 + * + * Sets the file descriptor to use as the stdout for spawned processes. + * + * If @fd is -1 then any previously given fd is unset. + * + * Note that the default behaviour is to pass stdout through to the + * stdout of the parent process. + * + * The passed @fd is noted but will not be touched in the current + * process. It is therefore necessary that it be kept open by the + * caller until the subprocess is spawned. The file descriptor will + * also not be explicitly closed on the child side, so it must be marked + * O_CLOEXEC if that's what you want. + * + * You may not set a stdout fd if a stdout file path is already set or + * if the launcher flags contain any flags directing stdout elsewhere. + * + * This feature is only available on UNIX. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_launcher_unsetenv: + * @self: a #GSubprocess + * @variable: the environment variable to unset, must not contain '=' + * + * Removes the environment variable @variable from the environment of + * processes launched from this launcher. + * + * The variable name should be in the GLib file name encoding. On UNIX, + * this means that they can be arbitrary byte strings. On Windows, they + * should be in UTF-8. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_new: (skip) + * @flags: flags that define the behaviour of the subprocess + * @error: (allow-none): return location for an error, or %NULL + * @argv0: first commandline argument to pass to the subprocess, + * followed by more arguments, followed by %NULL + * + * Create a new process with the given flags and varargs argument + * list. By default, matching the g_spawn_async() defaults, the + * child's stdin will be set to the system null device, and + * stdout/stderr will be inherited from the parent. You can use + * @flags to control this behavior. + * + * The argument list must be terminated with %NULL. + * + * Returns: A newly created #GSubprocess, or %NULL on error (and @error + * will be set) + * Since: 2.40 + */ + + +/** + * g_subprocess_newv: (rename-to g_subprocess_new) + * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess + * @flags: flags that define the behaviour of the subprocess + * @error: (allow-none): return location for an error, or %NULL + * + * Create a new process with the given flags and argument list. + * + * The argument list is expected to be %NULL-terminated. + * + * Returns: A newly created #GSubprocess, or %NULL on error (and @error + * will be set) + * Since: 2.40 + */ + + +/** + * g_subprocess_send_signal: + * @subprocess: a #GSubprocess + * @signal_num: the signal number to send + * + * Sends the UNIX signal @signal_num to the subprocess, if it is still + * running. + * + * This API is race-free. If the subprocess has terminated, it will not + * be signalled. + * + * This API is not available on Windows. + * + * Since: 2.40 + */ + + +/** + * g_subprocess_wait: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable + * @error: a #GError + * + * Synchronously wait for the subprocess to terminate. + * + * After the process terminates you can query its exit status with + * functions such as g_subprocess_get_if_exited() and + * g_subprocess_get_exit_status(). + * + * This function does not fail in the case of the subprocess having + * abnormal termination. See g_subprocess_wait_check() for that. + * + * Returns: %TRUE on success, %FALSE if @cancellable was cancelled + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_async: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable, or %NULL + * @callback: a #GAsyncReadyCallback to call when the operation is complete + * @user_data: user_data for @callback + * + * Wait for the subprocess to terminate. + * + * This is the asynchronous version of g_subprocess_wait(). + * + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_check: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable + * @error: a #GError + * + * Combines g_subprocess_wait() with g_spawn_check_exit_status(). + * + * Returns: %TRUE on success, %FALSE if process exited abnormally, or + * @cancellable was cancelled + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_check_async: + * @subprocess: a #GSubprocess + * @cancellable: a #GCancellable, or %NULL + * @callback: a #GAsyncReadyCallback to call when the operation is complete + * @user_data: user_data for @callback + * + * Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). + * + * This is the asynchronous version of g_subprocess_wait_check(). + * + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_check_finish: + * @subprocess: a #GSubprocess + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL + * + * Collects the result of a previous call to + * g_subprocess_wait_check_async(). + * + * Returns: %TRUE if successful, or %FALSE with @error set + * Since: 2.40 + */ + + +/** + * g_subprocess_wait_finish: + * @subprocess: a #GSubprocess + * @result: the #GAsyncResult passed to your #GAsyncReadyCallback + * @error: a pointer to a %NULL #GError, or %NULL + * + * Collects the result of a previous call to + * g_subprocess_wait_async(). + * + * Returns: %TRUE if successful, or %FALSE with @error set + * Since: 2.40 + */ + + +/** + * g_task_attach_source: + * @task: a #GTask + * @source: the source to attach + * @callback: the callback to invoke when @source triggers + * + * 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 [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. + * + * Since: 2.36 + */ + + +/** + * g_task_get_cancellable: + * @task: a #GTask + * + * Gets @task's #GCancellable + * + * Returns: (transfer none): @task's #GCancellable + * Since: 2.36 + */ + + +/** + * g_task_get_check_cancellable: + * @task: the #GTask + * + * Gets @task's check-cancellable flag. See + * g_task_set_check_cancellable() for more details. + * + * Since: 2.36 + */ + + +/** + * g_task_get_context: + * @task: a #GTask + * + * Gets the #GMainContext that @task will return its result in (that + * 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. + * + * Returns: (transfer none): @task's #GMainContext + * Since: 2.36 + */ + + +/** + * g_task_get_priority: + * @task: a #GTask + * + * Gets @task's priority + * + * Returns: @task's priority + * Since: 2.36 + */ + + +/** + * g_task_get_return_on_cancel: + * @task: the #GTask + * + * Gets @task's return-on-cancel flag. See + * g_task_set_return_on_cancel() for more details. + * + * Since: 2.36 + */ + + +/** + * g_task_get_source_object: + * @task: a #GTask + * + * Gets the source object from @task. Like + * g_async_result_get_source_object(), but does not ref the object. + * + * Returns: (transfer none) (type GObject): @task's source object, or %NULL + * Since: 2.36 + */ + + +/** + * g_task_get_source_tag: + * @task: a #GTask + * + * Gets @task's source tag. See g_task_set_source_tag(). + * + * Returns: (transfer none): @task's source tag + * Since: 2.36 + */ + + +/** + * g_task_get_task_data: + * @task: a #GTask + * + * Gets @task's `task_data`. + * + * Returns: (transfer none): @task's `task_data`. + * Since: 2.36 + */ + + +/** + * g_task_had_error: + * @task: a #GTask. + * + * Tests if @task resulted in an error. + * + * Returns: %TRUE if the task resulted in an error, %FALSE otherwise. + * Since: 2.36 + */ + + +/** + * g_task_is_valid: + * @result: (type Gio.AsyncResult): A #GAsyncResult + * @source_object: (allow-none) (type GObject): the source object + * expected to be associated with the task + * + * Checks that @result is a #GTask, and that @source_object is its + * source object (or that @source_object is %NULL and @result has no + * source object). This can be used in g_return_if_fail() checks. + * + * Returns: %TRUE if @result and @source_object are valid, %FALSE + * if not + * Since: 2.36 + */ + + +/** + * g_task_new: + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * + * Creates a #GTask acting on @source_object, which will eventually be + * 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 + * can use g_task_set_task_data() to attach task-specific data to the + * object, which you can retrieve later via g_task_get_task_data(). + * + * By default, if @cancellable is cancelled, then the return value of + * the task will always be %G_IO_ERROR_CANCELLED, even if the task had + * already completed before the cancellation. This allows for + * simplified handling in cases where cancellation may imply that + * other objects that the task depends on have been destroyed. If you + * do not want this behavior, you can use + * g_task_set_check_cancellable() to change it. + * + * Returns: a #GTask. + * Since: 2.36 + */ + + +/** + * g_task_propagate_boolean: + * @task: a #GTask. + * @error: return location for a #GError + * + * Gets the result of @task as a #gboolean. + * + * If the task resulted in an error, or was cancelled, then this will + * instead return %FALSE and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: the task result, or %FALSE on error + * Since: 2.36 + */ + + +/** + * g_task_propagate_int: + * @task: a #GTask. + * @error: return location for a #GError + * + * Gets the result of @task as an integer (#gssize). + * + * If the task resulted in an error, or was cancelled, then this will + * instead return -1 and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: the task result, or -1 on error + * Since: 2.36 + */ + + +/** + * g_task_propagate_pointer: + * @task: a #GTask + * @error: return location for a #GError + * + * Gets the result of @task as a pointer, and transfers ownership + * of that value to the caller. + * + * If the task resulted in an error, or was cancelled, then this will + * instead return %NULL and set @error. + * + * Since this method transfers ownership of the return value (or + * error) to the caller, you may only call it once. + * + * Returns: (transfer full): the task result, or %NULL on error + * Since: 2.36 + */ + + +/** + * g_task_report_error: + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * @source_tag: an opaque pointer indicating the source of this task + * @error: (transfer full): error to report + * + * Creates a #GTask and then immediately calls g_task_return_error() + * on it. Use this in the wrapper function of an asynchronous method + * when you want to avoid even calling the virtual method. You can + * then use g_async_result_is_tagged() in the finish method wrapper to + * check if the result there is tagged as having been created by the + * wrapper method, and deal with it appropriately if so. + * + * See also g_task_report_new_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_report_new_error: + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. + * @callback: (scope async): a #GAsyncReadyCallback. + * @callback_data: (closure): user data passed to @callback. + * @source_tag: an opaque pointer indicating the source of this task + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. + * + * Creates a #GTask and then immediately calls + * g_task_return_new_error() on it. Use this in the wrapper function + * of an asynchronous method when you want to avoid even calling the + * virtual method. You can then use g_async_result_is_tagged() in the + * finish method wrapper to check if the result there is tagged as + * having been created by the wrapper method, and deal with it + * appropriately if so. + * + * See also g_task_report_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_boolean: + * @task: a #GTask. + * @result: the #gboolean result of a task function. + * + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Since: 2.36 + */ + + +/** + * g_task_return_error: + * @task: a #GTask. + * @error: (transfer full): the #GError result of a task function. + * + * Sets @task's result to @error (which @task assumes ownership of) + * and completes the task (see g_task_return_pointer() for more + * discussion of exactly what this means). + * + * Note that since the task takes ownership of @error, and since the + * task may be completed before returning from g_task_return_error(), + * you cannot assume that @error is still valid after calling this. + * Call g_error_copy() on the error if you need to keep a local copy + * as well. + * + * See also g_task_return_new_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_error_if_cancelled: + * @task: a #GTask + * + * Checks if @task's #GCancellable has been cancelled, and if so, sets + * @task's error accordingly and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Returns: %TRUE if @task has been cancelled, %FALSE if not + * Since: 2.36 + */ + + +/** + * g_task_return_int: + * @task: a #GTask. + * @result: the integer (#gssize) result of a task function. + * + * Sets @task's result to @result and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * Since: 2.36 + */ + + +/** + * g_task_return_new_error: + * @task: a #GTask. + * @domain: a #GQuark. + * @code: an error code. + * @format: a string with format characters. + * @...: a list of values to insert into @format. + * + * Sets @task's result to a new #GError created from @domain, @code, + * @format, and the remaining arguments, and completes the task (see + * g_task_return_pointer() for more discussion of exactly what this + * means). + * + * See also g_task_return_error(). + * + * Since: 2.36 + */ + + +/** + * g_task_return_pointer: + * @task: a #GTask + * @result: (allow-none) (transfer full): the pointer result of a task + * function + * @result_destroy: (allow-none): a #GDestroyNotify function. + * + * Sets @task's result to @result and completes the task. If @result + * is not %NULL, then @result_destroy will be used to free @result if + * the caller does not take ownership of it with + * g_task_propagate_pointer(). + * + * "Completes the task" means that for an ordinary asynchronous task + * it will either invoke the task's callback, or else queue that + * callback to be invoked in the proper #GMainContext, or in the next + * iteration of the current #GMainContext. For a task run via + * g_task_run_in_thread() or g_task_run_in_thread_sync(), calling this + * method will save @result to be returned to the caller later, but + * the task will not actually be completed until the #GTaskThreadFunc + * exits. + * + * Note that since the task may be completed before returning from + * g_task_return_pointer(), you cannot assume that @result is still + * valid after calling this, unless you are still holding another + * reference on it. + * + * Since: 2.36 + */ + + +/** + * g_task_run_in_thread: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc + * + * Runs @task_func in another thread. When @task_func returns, @task's + * #GAsyncReadyCallback will be invoked in @task's #GMainContext. + * + * This takes a ref on @task until the task completes. + * + * See #GTaskThreadFunc for more details about how @task_func is handled. + * + * Since: 2.36 + */ + + +/** + * g_task_run_in_thread_sync: + * @task: a #GTask + * @task_func: a #GTaskThreadFunc + * + * Runs @task_func in another thread, and waits for it to return or be + * cancelled. You can use g_task_propagate_pointer(), etc, afterward + * 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 + * `callback`, but note that even if the task does + * have a callback, it will not be invoked when @task_func returns. + * + * Since: 2.36 + */ + + +/** + * g_task_set_check_cancellable: + * @task: the #GTask + * @check_cancellable: whether #GTask will check the state of + * its #GCancellable for you. + * + * Sets or clears @task's check-cancellable flag. If this is %TRUE + * (the default), then g_task_propagate_pointer(), etc, and + * g_task_had_error() will check the task's #GCancellable first, and + * if it has been cancelled, then they will consider the task to have + * returned an "Operation was cancelled" error + * (%G_IO_ERROR_CANCELLED), regardless of any other error or return + * value the task may have had. + * + * If @check_cancellable is %FALSE, then the #GTask will not check the + * cancellable itself, and it is up to @task's owner to do this (eg, + * via g_task_return_error_if_cancelled()). + * + * If you are using g_task_set_return_on_cancel() as well, then + * you must leave check-cancellable set %TRUE. + * + * Since: 2.36 + */ + + +/** + * g_task_set_priority: + * @task: the #GTask + * @priority: the [priority][io-priority] of the request + * + * Sets @task's priority. If you do not call this, it will default to + * %G_PRIORITY_DEFAULT. + * + * This will affect the priority of #GSources created with + * g_task_attach_source() and the scheduling of tasks run in threads, + * and can also be explicitly retrieved later via + * g_task_get_priority(). + * + * Since: 2.36 + */ + + +/** + * g_task_set_return_on_cancel: + * @task: the #GTask + * @return_on_cancel: whether the task returns automatically when + * it is cancelled. + * + * Sets or clears @task's return-on-cancel flag. This is only + * meaningful for tasks run via g_task_run_in_thread() or + * g_task_run_in_thread_sync(). + * + * If @return_on_cancel is %TRUE, then cancelling @task's + * #GCancellable will immediately cause it to return, as though the + * task's #GTaskThreadFunc had called + * g_task_return_error_if_cancelled() and then returned. + * + * This allows you to create a cancellable wrapper around an + * uninterruptable function. The #GTaskThreadFunc just needs to be + * careful that it does not modify any externally-visible state after + * it has been cancelled. To do that, the thread should call + * g_task_set_return_on_cancel() again to (atomically) set + * return-on-cancel %FALSE before making externally-visible changes; + * if the task gets cancelled before the return-on-cancel flag could + * be changed, g_task_set_return_on_cancel() will indicate this by + * returning %FALSE. + * + * You can disable and re-enable this flag multiple times if you wish. + * If the task's #GCancellable is cancelled while return-on-cancel is + * %FALSE, then calling g_task_set_return_on_cancel() to set it %TRUE + * again will cause the task to be cancelled at that point. + * + * If the task's #GCancellable is already cancelled before you call + * g_task_run_in_thread()/g_task_run_in_thread_sync(), then the + * #GTaskThreadFunc will still be run (for consistency), but the task + * will also be completed right away. + * + * Returns: %TRUE if @task's return-on-cancel flag was changed to + * match @return_on_cancel. %FALSE if @task has already been + * cancelled. + * Since: 2.36 + */ + + +/** + * g_task_set_source_tag: + * @task: the #GTask + * @source_tag: an opaque pointer indicating the source of this task + * + * Sets @task's source tag. You can use this to tag a task return + * value with a particular pointer (usually a pointer to the function + * doing the tagging) and then later check it using + * g_task_get_source_tag() (or g_async_result_is_tagged()) in the + * task's "finish" function, to figure out if the response came from a + * particular place. + * + * Since: 2.36 + */ + + +/** + * g_task_set_task_data: + * @task: the #GTask + * @task_data: (allow-none): task-specific data + * @task_data_destroy: (allow-none): #GDestroyNotify for @task_data + * + * Sets @task's task data (freeing the existing task data, if any). + * + * Since: 2.36 + */ + + +/** * g_tcp_connection_get_graceful_disconnect: * @connection: a #GTcpConnection * @@ -30313,7 +35102,7 @@ * @self: a #GTestDBus * @path: path to a directory containing .service files * - * Add a path where dbus-daemon will lookup for .services files. This can't be + * Add a path where dbus-daemon will look up .service files. This can't be * called after g_test_dbus_up(). */ @@ -30334,11 +35123,11 @@ * g_test_dbus_get_bus_address: * @self: a #GTestDBus * - * Get the address on which dbus-daemon is running. if g_test_dbus_up() has not + * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not * been called yet, %NULL is returned. This can be used with - * g_dbus_connection_new_for_address() + * g_dbus_connection_new_for_address(). * - * Returns: the address of the bus, or %NULL. + * Returns: (allow-none): the address of the bus, or %NULL. */ @@ -30346,7 +35135,7 @@ * g_test_dbus_get_flags: * @self: a #GTestDBus * - * Gets the flags of the #GTestDBus object. + * Get the flags of the #GTestDBus object. * * Returns: the value of #GTestDBus:flags property */ @@ -30392,7 +35181,7 @@ * @self: a #GTestDBus * * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this - * call, it is safe for unit tests to start sending messages on the session bug. + * call, it is safe for unit tests to start sending messages on the session bus. * * If this function is called from setup callback of g_test_add(), * g_test_dbus_down() must be called in its teardown callback. @@ -30409,10 +35198,8 @@ * * 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> */ @@ -30439,7 +35226,8 @@ /** * g_themed_icon_new_from_names: * @iconnames: (array length=len): an array of strings containing icon names. - * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated + * @len: the length of the @iconnames array, or -1 if @iconnames is + * %NULL-terminated * * Creates a new themed icon for @iconnames. * @@ -30455,7 +35243,7 @@ * 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", @@ -30478,10 +35266,8 @@ * * 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 */ @@ -30489,7 +35275,8 @@ /** * g_threaded_socket_service_new: - * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit + * @max_threads: the maximal number of threads to execute concurrently + * handling incoming clients, -1 means no limit * * Creates a new #GThreadedSocketService with no listeners. Listeners * must be added with one of the #GSocketListener "add" methods. @@ -30505,7 +35292,8 @@ * * Gets the #GType of @backend's #GTlsCertificate implementation. * - * Returns: the #GType of @backend's #GTlsCertificate implementation. + * Returns: the #GType of @backend's #GTlsCertificate + * implementation. * Since: 2.28 */ @@ -30516,7 +35304,8 @@ * * Gets the #GType of @backend's #GTlsClientConnection implementation. * - * Returns: the #GType of @backend's #GTlsClientConnection implementation. + * Returns: the #GType of @backend's #GTlsClientConnection + * implementation. * Since: 2.28 */ @@ -30537,7 +35326,8 @@ * * Gets the default #GTlsDatabase used to verify TLS connections. * - * Returns: (transfer full): the default database, which should be unreffed when done. + * Returns: (transfer full): the default database, which should be + * unreffed when done. * Since: 2.30 */ @@ -30559,7 +35349,8 @@ * * Gets the #GType of @backend's #GTlsServerConnection implementation. * - * Returns: the #GType of @backend's #GTlsServerConnection implementation. + * Returns: the #GType of @backend's #GTlsServerConnection + * implementation. * Since: 2.28 */ @@ -30582,7 +35373,9 @@ * * Gets the #GTlsCertificate representing @cert's issuer, if known * - * Returns: (transfer none): The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. + * Returns: (transfer none): The certificate of @cert's issuer, + * or %NULL if @cert is self-signed or signed with an unknown + * certificate. * Since: 2.28 */ @@ -30608,13 +35401,15 @@ * @file: file containing PEM-encoded certificates to import * @error: #GError for error reporting, or %NULL to ignore. * - * 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 * set @error. * - * Returns: (element-type Gio.TlsCertificate) (transfer full): a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it. + * Returns: (element-type Gio.TlsCertificate) (transfer full): a + * #GList containing #GTlsCertificate objects. You must free the list + * and its contents when you are done with it. * Since: 2.28 */ @@ -30713,7 +35508,9 @@ * Each item in the list is a #GByteArray which contains the complete * subject DN of the certificate authority. * - * Returns: (element-type GByteArray) (transfer full): the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free(). + * Returns: (element-type GByteArray) (transfer full): the list of + * CA DNs. You should unref each element with g_byte_array_unref() and then + * the free the list with g_list_free(). * Since: 2.28 */ @@ -30724,7 +35521,9 @@ * * Gets @conn's expected server identity * - * Returns: (transfer none): a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. + * Returns: (transfer none): a #GSocketConnectable describing the + * expected server identity, or %NULL if the expected identity is not + * known. * Since: 2.28 */ @@ -30763,7 +35562,8 @@ * must have pollable input and output streams) which is assumed to * communicate with the server identified by @server_identity. * - * Returns: (transfer full) (type GTlsClientConnection): the new #GTlsClientConnection, or %NULL on error + * Returns: (transfer full) (type GTlsClientConnection): the new + * #GTlsClientConnection, or %NULL on error * Since: 2.28 */ @@ -30819,7 +35619,8 @@ * Used by #GTlsConnection implementations to emit the * #GTlsConnection::accept-certificate signal. * - * Returns: %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert + * Returns: %TRUE if one of the signal handlers has returned + * %TRUE to accept @peer_cert * Since: 2.28 */ @@ -30907,7 +35708,8 @@ * when the connection is closed. See * g_tls_connection_set_require_close_notify() for details. * - * Returns: %TRUE if @conn requires a proper TLS close notification. + * Returns: %TRUE if @conn requires a proper TLS close + * notification. * Since: 2.28 */ @@ -30961,7 +35763,7 @@ /** * g_tls_connection_handshake_async: * @conn: a #GTlsConnection - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): a #GCancellable, or %NULL * @callback: callback to call when the handshake is complete * @user_data: the data to pass to the callback function @@ -30982,7 +35784,8 @@ * Finish an asynchronous TLS handshake operation. See * g_tls_connection_handshake() for more information. * - * Returns: %TRUE on success, %FALSE on failure, in which case @error will be set. + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set. * Since: 2.28 */ @@ -31064,16 +35867,16 @@ * * %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 */ @@ -31173,7 +35976,8 @@ * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full) (allow-none): a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full) (allow-none): a newly allocated + * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31207,7 +36011,8 @@ * If the handle is no longer valid, or does not point to a certificate in * this database, then %NULL will be returned. * - * Returns: (transfer full): a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated #GTlsCertificate object. + * Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31230,7 +36035,8 @@ * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31261,7 +36067,8 @@ * Finish an asynchronous lookup issuer operation. See * g_tls_database_lookup_certificate_issuer() for more information. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -31280,7 +36087,8 @@ * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. + * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate + * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. * Since: 2.30 */ @@ -31315,7 +36123,8 @@ * Finish an asynchronous lookup of certificates. See * g_tls_database_lookup_certificates_issued_by() for more information. * - * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. + * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate + * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list. * Since: 2.30 */ @@ -31356,7 +36165,8 @@ * This function can block, use g_tls_database_verify_chain_async() to perform * the verification operation asynchronously. * - * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification. + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. * Since: 2.30 */ @@ -31390,7 +36200,8 @@ * Finish an asynchronous verify chain operation. See * g_tls_database_verify_chain() for more information. * * - * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification. + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. * Since: 2.30 */ @@ -31415,7 +36226,8 @@ * * The certificates in @anchors must be PEM encoded. * - * Returns: (transfer full) (type GTlsFileDatabase): the new #GTlsFileDatabase, or %NULL on error + * Returns: (transfer full) (type GTlsFileDatabase): the new + * #GTlsFileDatabase, or %NULL on error * Since: 2.30 */ @@ -31528,6 +36340,114 @@ /** + * g_tls_interaction_invoke_request_certificate: + * @interaction: a #GTlsInteraction object + * @connection: a #GTlsConnection object + * @flags: flags providing more information about the request + * @cancellable: an optional #GCancellable cancellation object + * @error: an optional location to place an error on failure + * + * Invoke the interaction to ask the user to choose a certificate to + * use with the connection. It invokes this interaction in the main + * loop, specifically the #GMainContext returned by + * g_main_context_get_thread_default() when the interaction is + * created. This is called by called by #GTlsConnection when the peer + * requests a certificate during the handshake. + * + * Derived subclasses usually implement a certificate selector, + * although they may also choose to provide a certificate from + * elsewhere. Alternatively the user may abort this certificate + * request, which may or may not abort the TLS connection. + * + * The implementation can either be a synchronous (eg: modal dialog) or an + * asynchronous one (eg: modeless dialog). This function will take care of + * calling which ever one correctly. + * + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may + * not support immediate cancellation. + * + * Returns: The status of the certificate request interaction. + * Since: 2.40 + */ + + +/** + * g_tls_interaction_request_certificate: + * @interaction: a #GTlsInteraction object + * @connection: a #GTlsConnection object + * @flags: flags providing more information about the request + * @cancellable: an optional #GCancellable cancellation object + * @error: an optional location to place an error on failure + * + * Run synchronous interaction to ask the user to choose a certificate to use + * with the connection. In general, g_tls_interaction_invoke_request_certificate() + * should be used instead of this function. + * + * Derived subclasses usually implement a certificate selector, although they may + * also choose to provide a certificate from elsewhere. Alternatively the user may + * abort this certificate request, which will usually abort the TLS connection. + * + * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection + * passed to g_tls_interaction_request_certificate() will have had its + * #GTlsConnection:certificate filled in. + * + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. Certain implementations may + * not support immediate cancellation. + * + * Returns: The status of the request certificate interaction. + * Since: 2.40 + */ + + +/** + * g_tls_interaction_request_certificate_async: + * @interaction: a #GTlsInteraction object + * @connection: a #GTlsConnection object + * @flags: flags providing more information about the request + * @cancellable: an optional #GCancellable cancellation object + * @callback: (allow-none): will be called when the interaction completes + * @user_data: (allow-none): data to pass to the @callback + * + * Run asynchronous interaction to ask the user for a certificate to use with + * the connection. In general, g_tls_interaction_invoke_request_certificate() should + * be used instead of this function. + * + * Derived subclasses usually implement a certificate selector, although they may + * also choose to provide a certificate from elsewhere. @callback will be called + * when the operation completes. Alternatively the user may abort this certificate + * request, which will usually abort the TLS connection. + * + * Since: 2.40 + */ + + +/** + * g_tls_interaction_request_certificate_finish: + * @interaction: a #GTlsInteraction object + * @result: the result passed to the callback + * @error: an optional location to place an error on failure + * + * Complete an request certificate user interaction request. This should be once + * the g_tls_interaction_request_certificate_async() completion callback is called. + * + * If %G_TLS_INTERACTION_HANDLED is returned, then the #GTlsConnection + * passed to g_tls_interaction_request_certificate_async() will have had its + * #GTlsConnection:certificate filled in. + * + * If the interaction is cancelled by the cancellation object, or by the + * user then %G_TLS_INTERACTION_FAILED will be returned with an error that + * contains a %G_IO_ERROR_CANCELLED error code. + * + * Returns: The status of the request certificate interaction. + * Since: 2.40 + */ + + +/** * g_tls_password_get_description: * @password: a #GTlsPassword object * @@ -31630,7 +36550,7 @@ /** - * g_tls_password_set_value_full: + * g_tls_password_set_value_full: (virtual set_value) * @password: a #GTlsPassword object * @value: the value for the password * @length: the length of the password, or -1 @@ -31646,7 +36566,6 @@ * calculated automatically. (Note that the terminating nul is not * considered part of the password in this case.) * - * Virtual: set_value * Since: 2.30 */ @@ -31673,7 +36592,8 @@ * Creates a new #GTlsServerConnection wrapping @base_io_stream (which * must have pollable input and output streams). * - * Returns: (transfer full) (type GTlsServerConnection): the new #GTlsServerConnection, or %NULL on error + * Returns: (transfer full) (type GTlsServerConnection): the new + * #GTlsServerConnection, or %NULL on error * Since: 2.28 */ @@ -31695,7 +36615,8 @@ * Other ways to exchange credentials with a foreign peer includes the * #GUnixCredentialsMessage type and g_socket_get_credentials() function. * - * Returns: (transfer full): Received credentials on success (free with g_object_unref()), %NULL if @error is set. + * Returns: (transfer full): Received credentials on success (free with + * g_object_unref()), %NULL if @error is set. * Since: 2.26 */ @@ -31728,7 +36649,8 @@ * Finishes an asynchronous receive credentials operation started with * g_unix_connection_receive_credentials_async(). * - * Returns: (transfer full): a #GCredentials, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GCredentials, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.32 */ @@ -31889,7 +36811,8 @@ * this index with g_unix_fd_list_get() then you will receive back a * duplicated copy of the same file descriptor. * - * Returns: the index of the appended fd in case of success, else -1 (and @error is set) + * Returns: the index of the appended fd in case of success, else -1 + * (and @error is set) * Since: 2.24 */ @@ -31962,7 +36885,8 @@ /** * g_unix_fd_list_peek_fds: * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -31978,7 +36902,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: (array length=length) (transfer none): an array of file descriptors + * Returns: (array length=length) (transfer none): an array of file + * descriptors * Since: 2.24 */ @@ -31986,7 +36911,8 @@ /** * g_unix_fd_list_steal_fds: * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -32007,7 +36933,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: (array length=length) (transfer full): an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * Since: 2.24 */ @@ -32070,7 +36997,8 @@ /** * g_unix_fd_message_steal_fds: * @message: a #GUnixFDMessage - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -32090,7 +37018,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @message, an empty array is returned. * - * Returns: (array length=length) (transfer full): an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * Since: 2.22 */ @@ -32146,14 +37075,15 @@ /** * g_unix_is_mount_path_system_internal: - * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename> + * @mount_path: a mount path, e.g. `/media/disk` or `/usr` * * Determines if @mount_path is considered an implementation of the * OS. This is primarily used for hiding mountable and mounted volumes * that only are used in the OS and has little to no relevance to the * casual user. * - * Returns: %TRUE if @mount_path is considered an implementation detail of the OS. + * Returns: %TRUE if @mount_path is considered an implementation detail + * of the OS. */ @@ -32177,7 +37107,8 @@ * * Compares two unix mounts. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ @@ -32246,7 +37177,8 @@ * Guesses the name of a Unix mount. * The result is a translated string. * - * Returns: A newly allocated string that must be freed with g_free() + * Returns: A newly allocated string that must + * be freed with g_free() */ @@ -32306,7 +37238,8 @@ /** * g_unix_mount_monitor_set_rate_limit: * @mount_monitor: a #GUnixMountMonitor - * @limit_msec: a integer with the limit in milliseconds to poll for changes. + * @limit_msec: a integer with the limit in milliseconds to + * poll for changes. * * Sets the rate limit to which the @mount_monitor will report * consecutive change events to the mount and mount point entry files. @@ -32322,7 +37255,8 @@ * * Compares two unix mount points. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ @@ -32402,7 +37336,8 @@ * Guesses the name of a Unix mount point. * The result is a translated string. * - * Returns: A newly allocated string that must be freed with g_free() + * Returns: A newly allocated string that must + * be freed with g_free() */ @@ -32466,7 +37401,8 @@ * allowing for checking if the mounts have changed with * g_unix_mount_points_changed_since(). * - * Returns: (element-type GUnixMountPoint) (transfer full): a #GList of the UNIX mountpoints. + * Returns: (element-type GUnixMountPoint) (transfer full): + * a #GList of the UNIX mountpoints. */ @@ -32489,7 +37425,8 @@ * timestamp, allowing for checking if the mounts have changed * with g_unix_mounts_changed_since(). * - * Returns: (element-type GUnixMountEntry) (transfer full): a #GList of the UNIX mounts. + * Returns: (element-type GUnixMountEntry) (transfer full): + * a #GList of the UNIX mounts. */ @@ -32656,7 +37593,7 @@ * 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. * @@ -32687,7 +37624,8 @@ * * Gets a #GFile for @path. * - * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ @@ -32702,7 +37640,8 @@ * might not support any I/O operation if the URI * is malformed or if the URI scheme is not supported. * - * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ @@ -32721,7 +37660,9 @@ * * Gets a list of URI schemes supported by @vfs. * - * Returns: (transfer none): a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. + * Returns: (transfer none): a %NULL-terminated array of strings. + * The returned array belongs to GIO and must + * not be freed or modified. */ @@ -32731,7 +37672,8 @@ * * Checks if the VFS is active. * - * Returns: %TRUE if construction of the @vfs was successful and it is now active. + * Returns: %TRUE if construction of the @vfs was successful + * and it is now active. */ @@ -32744,36 +37686,37 @@ * not support any I/O operations if the @parse_name cannot * be parsed by the #GVfs module. * - * Returns: (transfer full): a #GFile for the given @parse_name. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile for the given @parse_name. + * Free the returned object with g_object_unref(). */ /** * g_volume_can_eject: - * @volume: a #GVolume. + * @volume: a #GVolume * * Checks if a volume can be ejected. * - * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise. + * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise */ /** * g_volume_can_mount: - * @volume: a #GVolume. + * @volume: a #GVolume * * Checks if a volume can be mounted. * - * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise. + * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise */ /** * g_volume_eject: - * @volume: a #GVolume. + * @volume: a #GVolume * @flags: flags affecting the unmount if required for eject - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL * @user_data: user data that gets passed to @callback * * Ejects a volume. This is an asynchronous operation, and is @@ -32786,26 +37729,27 @@ /** * g_volume_eject_finish: - * @volume: pointer to a #GVolume. - * @result: a #GAsyncResult. + * @volume: pointer to a #GVolume + * @result: a #GAsyncResult * @error: a #GError location to store an error, or %NULL to ignore * * Finishes ejecting a volume. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. * - * Returns: %TRUE, %FALSE if operation failed. + * Returns: %TRUE, %FALSE if operation failed * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead. */ /** * g_volume_eject_with_operation: - * @volume: a #GVolume. + * @volume: a #GVolume * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. - * @user_data: user data passed to @callback. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to + * avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL + * @user_data: user data passed to @callback * * Ejects a volume. This is an asynchronous operation, and is * finished by calling g_volume_eject_with_operation_finish() with the @volume @@ -32817,14 +37761,14 @@ /** * g_volume_eject_with_operation_finish: - * @volume: a #GVolume. - * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @volume: a #GVolume + * @result: a #GAsyncResult + * @error: a #GError location to store the error occurring, or %NULL * * Finishes ejecting a volume. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. * - * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise. + * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise * Since: 2.22 */ @@ -32833,11 +37777,11 @@ * g_volume_enumerate_identifiers: * @volume: a #GVolume * - * 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. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array + * of strings containing kinds of identifiers. Use g_strfreev() to free. */ @@ -32852,51 +37796,53 @@ * 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 * implementations to find the underlying mount to shadow, see * g_mount_is_shadowed() for more details. * - * Returns: (transfer full): the activation root of @volume or %NULL. Use g_object_unref() to free. + * Returns: (transfer full): the activation root of @volume or %NULL. Use + * g_object_unref() to free. * Since: 2.18 */ /** * g_volume_get_drive: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the drive for the @volume. * - * Returns: (transfer full): 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. + * Returns: (transfer full): 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. */ /** * g_volume_get_icon: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the icon for @volume. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ @@ -32906,65 +37852,74 @@ * @kind: the kind of identifier to return * * 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. * - * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GVolume doesn't have this kind of identifier + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GVolume + * doesn't have this kind of identifier */ /** * g_volume_get_mount: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the mount for the @volume. * - * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ /** * g_volume_get_name: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the name of @volume. * - * Returns: the name for the given @volume. The returned string should be freed with g_free() when no longer needed. + * Returns: the name for the given @volume. The returned string should + * be freed with g_free() when no longer needed. */ /** * g_volume_get_sort_key: - * @volume: A #GVolume. + * @volume: a #GVolume * * Gets the sort key for @volume, if any. * - * Returns: Sorting key for @volume or %NULL if no such key is available. + * Returns: Sorting key for @volume or %NULL if no such key is available * Since: 2.32 */ /** * g_volume_get_symbolic_icon: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the symbolic icon for @volume. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. * Since: 2.34 */ /** * g_volume_get_uuid: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the UUID for the @volume. The reference is typically based on * the file system UUID for the volume in question and should be * considered an opaque string. Returns %NULL if there is no UUID * available. * - * Returns: the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed. + * Returns: the UUID for @volume or %NULL if no UUID can be computed. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -33001,8 +37956,13 @@ * is to return #GVolume objects representing entries in the users * "favorite servers" list or similar. * - * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount. - * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions. + * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL + * if no wants to adopt the #GMount. + * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor + * implementations should instead create shadow mounts with the URI of + * the mount they intend to adopt. See the proxy volume monitor in + * gvfs for an example of this. Also see g_mount_is_shadowed(), + * g_mount_shadow() and g_mount_unshadow() functions. */ @@ -33011,7 +37971,8 @@ * * Gets the volume monitor used by gio. * - * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it. + * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call + * g_object_unref() when done with it. */ @@ -33035,7 +37996,8 @@ * * Finds a #GMount object by its UUID (see g_mount_get_uuid()) * - * Returns: (transfer full): a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GMount or %NULL if no such mount is available. + * Free the returned object with g_object_unref(). */ @@ -33059,7 +38021,8 @@ * * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) * - * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. + * Free the returned object with g_object_unref(). */ @@ -33077,19 +38040,17 @@ /** - * g_volume_mount: - * @volume: a #GVolume. + * g_volume_mount: (virtual mount_fn) + * @volume: a #GVolume * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL * @user_data: user data that gets passed to @callback * * Mounts a volume. This is an asynchronous operation, and is * finished by calling g_volume_mount_finish() with the @volume * and #GAsyncResult returned in the @callback. - * - * Virtual: mount_fn */ @@ -33107,7 +38068,7 @@ * function; there's no need to listen for the 'mount-added' signal on * #GVolumeMonitor. * - * Returns: %TRUE, %FALSE if operation failed. + * Returns: %TRUE, %FALSE if operation failed */ @@ -33117,7 +38078,7 @@ * * Returns whether the volume should be automatically mounted. * - * Returns: %TRUE if the volume should be automatically mounted. + * Returns: %TRUE if the volume should be automatically mounted */ @@ -33302,7 +38263,8 @@ * * Optionally doesn't list the desktop ids given in the @except * - * Returns: a #GList containing the desktop ids which claim to handle @mime_type. + * Returns: a #GList containing the desktop ids which claim + * to handle @mime_type. */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 90ec0003..31029d81 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -44,15 +44,14 @@ * used as a context. This is mainly useful for short strings which * may need different translations, depending on the context in which * they are used. - * |[ + * |[<!-- language="C" --> * label1 = C_("Navigation", "Back"); * label2 = C_("Body part", "Back"); * ]| * - * <note><para>If you are using the C_() macro, you need to make sure - * that you pass <option>--keyword=C_:1c,2</option> to xgettext when - * extracting messages. Note that this only works with GNU - * gettext >= 0.15.</para></note> + * If you are using the C_() macro, you need to make sure that you pass + * `--keyword=C_:1c,2` to xgettext when extracting messages. + * Note that this only works with GNU gettext >= 0.15. * * Returns: the translated message * Since: 2.16 @@ -68,10 +67,12 @@ /** * GArray: - * @data: a pointer to the element data. The data may be moved as elements are added to the #GArray. - * @len: the number of elements in the #GArray not including the possible terminating zero element. + * @data: a pointer to the element data. The data may be moved as + * elements are added to the #GArray. + * @len: the number of elements in the #GArray not including the + * possible terminating zero element. * - * Contains the public fields of an <link linkend="glib-Arrays">Array</link>. + * Contains the public fields of a GArray. */ @@ -80,25 +81,25 @@ * * The GAsyncQueue struct is an opaque data structure which represents * an asynchronous queue. It should only be accessed through the - * <function>g_async_queue_*</function> functions. + * g_async_queue_* functions. */ /** * GByteArray: - * @data: a pointer to the element data. The data may be moved as elements are added to the #GByteArray. - * @len: the number of elements in the #GByteArray. + * @data: a pointer to the element data. The data may be moved as + * elements are added to the #GByteArray + * @len: the number of elements in the #GByteArray * - * The <structname>GByteArray</structname> struct allows access to the - * public fields of a <structname>GByteArray</structname>. + * Contains the public fields of a GByteArray. */ /** * GBytes: * - * A simple refcounted data type representing an immutable byte sequence - * from an unspecified origin. + * A simple refcounted data type representing an immutable sequence of zero or + * more bytes from an unspecified origin. * * The purpose of a #GBytes is to keep the memory region that it holds * alive for as long as anyone holds a reference to the bytes. When @@ -128,30 +129,32 @@ /** * GCompareDataFunc: - * @a: a value. - * @b: a value to compare with. - * @user_data: user data to pass to comparison function. + * @a: a value + * @b: a value to compare with + * @user_data: user data * * Specifies the type of a comparison function used to compare two * values. The function should return a negative integer if the first * value comes before the second, 0 if they are equal, or a positive * integer if the first value comes after the second. * - * Returns: negative value if @a < @b; zero if @a = @b; positive value if @a > @b. + * Returns: negative value if @a < @b; zero if @a = @b; positive + * value if @a > @b */ /** * GCompareFunc: - * @a: a value. - * @b: a value to compare with. + * @a: a value + * @b: a value to compare with * * Specifies the type of a comparison function used to compare two * values. The function should return a negative integer if the first * value comes before the second, 0 if they are equal, or a positive * integer if the first value comes after the second. * - * Returns: negative value if @a < @b; zero if @a = @b; positive value if @a > @b. + * Returns: negative value if @a < @b; zero if @a = @b; positive + * value if @a > @b */ @@ -169,11 +172,9 @@ * another thread publishes the data, it can signal one of the waiting * threads to wake up to collect the data. * - * <example> - * <title> - * Using GCond to block a thread until a condition is satisfied - * </title> - * <programlisting> + * Here is an example for using GCond to block a thread until a condition + * is satisfied: + * |[<!-- language="C" --> * gpointer current_data = NULL; * GMutex data_mutex; * GCond data_cond; @@ -201,21 +202,19 @@ * * return data; * } - * </programlisting> - * </example> - * + * ]| * Whenever a thread calls pop_data() now, it will wait until * current_data is non-%NULL, i.e. until some other thread * has called push_data(). * * The example shows that use of a condition variable must always be * paired with a mutex. Without the use of a mutex, there would be a - * race between the check of <varname>current_data</varname> by the - * while loop in <function>pop_data</function> and waiting. - * Specifically, another thread could set <varname>pop_data</varname> - * after the check, and signal the cond (with nobody waiting on it) - * before the first thread goes to sleep. #GCond is specifically useful - * for its ability to release the mutex and go to sleep atomically. + * race between the check of @current_data by the while loop in + * pop_data() and waiting. Specifically, another thread could set + * @current_data after the check, and signal the cond (with nobody + * waiting on it) before the first thread goes to sleep. #GCond is + * specifically useful for its ability to release the mutex and go + * to sleep atomically. * * It is also important to use the g_cond_wait() and g_cond_wait_until() * functions only inside a loop which checks for the condition to be @@ -223,20 +222,19 @@ * not be true even after it returns. * * If a #GCond is allocated in static storage then it can be used - * without initialisation. Otherwise, you should call g_cond_init() on - * it and g_cond_clear() when done. + * without initialisation. Otherwise, you should call g_cond_init() + * on it and g_cond_clear() when done. * - * A #GCond should only be accessed via the <function>g_cond_</function> - * functions. + * A #GCond should only be accessed via the g_cond_ functions. */ /** * GData: * - * The #GData struct is an opaque data structure to represent a <link - * linkend="glib-Keyed-Data-Lists">Keyed Data List</link>. It should - * only be accessed via the following functions. + * The #GData struct is an opaque data structure to represent a + * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be + * accessed via the following functions. */ @@ -257,19 +255,23 @@ * @julian_days: the Julian representation of the date * @julian: this bit is set if @julian_days is valid * @dmy: this is set if @day, @month and @year are valid - * @day: the day of the day-month-year representation of the date, as a number between 1 and 31 - * @month: the day of the day-month-year representation of the date, as a number between 1 and 12 + * @day: the day of the day-month-year representation of the date, + * as a number between 1 and 31 + * @month: the day of the day-month-year representation of the date, + * as a number between 1 and 12 * @year: the day of the day-month-year representation of the date * * Represents a day between January 1, Year 1 and a few thousand years in - * the future. None of its members should be accessed directly. If the - * <structname>GDate</structname> is obtained from g_date_new(), it will - * be safe to mutate but invalid and thus not safe for calendrical - * computations. If it's declared on the stack, it will contain garbage - * so must be initialized with g_date_clear(). g_date_clear() makes the - * date invalid but sane. An invalid date doesn't represent a day, it's - * "empty." A date becomes valid after you set it to a Julian day or you - * set a day, month, and year. + * the future. None of its members should be accessed directly. + * + * If the #GDate-struct is obtained from g_date_new(), it will be safe + * to mutate but invalid and thus not safe for calendrical computations. + * + * If it's declared on the stack, it will contain garbage so must be + * initialized with g_date_clear(). g_date_clear() makes the date invalid + * but sane. An invalid date doesn't represent a day, it's "empty." A date + * becomes valid after you set it to a Julian day or you set a day, month, + * and year. */ @@ -287,8 +289,8 @@ /** * GDateDay: * - * Integer representing a day of the month; between 1 and - * 31. #G_DATE_BAD_DAY represents an invalid day of the month. + * Integer representing a day of the month; between 1 and 31. + * #G_DATE_BAD_DAY represents an invalid day of the month. */ @@ -411,31 +413,73 @@ /** * GFileError: - * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. - * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory for writing, or create or remove hard links to it. - * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not allow the attempted operation. + * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of + * the file (or other resource) or processes with special privileges + * can perform the operation. + * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory + * for writing, or create or remove hard links to it. + * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not + * allow the attempted operation. * @G_FILE_ERROR_NAMETOOLONG: Filename too long. - * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist. - * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when a directory is required. - * @G_FILE_ERROR_NXIO: No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or not correctly attached to the computer. - * @G_FILE_ERROR_NODEV: The underlying file system of the specified file does not support memory mapping. - * @G_FILE_ERROR_ROFS: The directory containing the new link can't be modified because it's on a read-only file system. + * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file + * doesn't exist" error for ordinary files that are referenced in + * contexts where they are expected to already exist. + * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when + * a directory is required. + * @G_FILE_ERROR_NXIO: No such device or address. The system tried to + * use the device represented by a file you specified, and it + * couldn't find the device. This can mean that the device file was + * installed incorrectly, or that the physical device is missing or + * not correctly attached to the computer. + * @G_FILE_ERROR_NODEV: The underlying file system of the specified file + * does not support memory mapping. + * @G_FILE_ERROR_ROFS: The directory containing the new link can't be + * modified because it's on a read-only file system. * @G_FILE_ERROR_TXTBSY: Text file busy. - * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. (GLib won't reliably return this, don't pass in pointers to bad memory.) - * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links. - * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a file failed because the disk is full. - * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate more virtual memory because its capacity is full. - * @G_FILE_ERROR_MFILE: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. - * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the entire system. - * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa). - * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function. - * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a `SIGPIPE' signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see this code unless it has handled or blocked `SIGPIPE'. - * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might work if you try again later. - * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again. - * @G_FILE_ERROR_IO: Input/output error; usually used for physical read or write errors. i.e. the disk or other physical device hardware is returning errors. - * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. - * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that the system is missing some functionality. - * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this is the standard "failed for unspecified reason" error code present in all #GError error code enumerations. Returned if no specific code applies. + * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. + * (GLib won't reliably return this, don't pass in pointers to bad + * memory.) + * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered + * in looking up a file name. This often indicates a cycle of symbolic + * links. + * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a + * file failed because the disk is full. + * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate + * more virtual memory because its capacity is full. + * @G_FILE_ERROR_MFILE: The current process has too many files open and + * can't open any more. Duplicate descriptors do count toward this + * limit. + * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the + * entire system. + * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a + * descriptor that has been closed or reading from a descriptor open + * only for writing (or vice versa). + * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate + * various kinds of problems with passing the wrong argument to a + * library function. + * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the + * other end of a pipe. Every library function that returns this + * error code also generates a 'SIGPIPE' signal; this signal + * terminates the program if not handled or blocked. Thus, your + * program will never actually see this code unless it has handled + * or blocked 'SIGPIPE'. + * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might + * work if you try again later. + * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal + * occurred and prevented completion of the call. When this + * happens, you should try the call again. + * @G_FILE_ERROR_IO: Input/output error; usually used for physical read + * or write errors. i.e. the disk or other physical device hardware + * is returning errors. + * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the + * file (or other resource) or processes with special privileges can + * perform the operation. + * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that + * the system is missing some functionality. + * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this + * is the standard "failed for unspecified reason" error code present + * in all #GError error code enumerations. Returned if no specific + * code applies. * * Values corresponding to @errno codes returned from file operations * on UNIX. Unlike @errno codes, GFileError values are available on @@ -454,11 +498,14 @@ /** * GFileTest: - * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a directory). Note that this test will also return %TRUE if the tested file is a symlink to a regular file. + * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file + * (not a directory). Note that this test will also return %TRUE + * if the tested file is a symlink to a regular file. * @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink. * @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory. * @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable. - * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not be a regular file. + * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not + * be a regular file. * * A test to perform on a file using g_file_test(). */ @@ -478,8 +525,12 @@ /** * GFormatSizeFlags: * @G_FORMAT_SIZE_DEFAULT: behave the same as g_format_size() - * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part of the returned string. For example, "45.6 kB (45,612 bytes)". - * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style suffixes. IEC units should only be used for reporting things with a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. Network and storage sizes should be reported in the normal SI units. + * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part + * of the returned string. For example, "45.6 kB (45,612 bytes)". + * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style + * suffixes. IEC units should only be used for reporting things with + * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. + * Network and storage sizes should be reported in the normal SI units. * * Flags to modify the format of the string returned by g_format_size_full(). */ @@ -487,8 +538,8 @@ /** * GFunc: - * @data: the element's data. - * @user_data: user data passed to g_list_foreach() or g_slist_foreach(). + * @data: the element's data + * @user_data: user data passed to g_list_foreach() or g_slist_foreach() * * Specifies the type of functions passed to g_list_foreach() and * g_slist_foreach(). @@ -519,7 +570,8 @@ * g_hash_table_foreach_remove(). It should return %TRUE if the * key/value pair should be removed from the #GHashTable. * - * Returns: %TRUE if the key/value pair should be removed from the #GHashTable + * Returns: %TRUE if the key/value pair should be removed from the + * #GHashTable */ @@ -536,7 +588,7 @@ * and #gchar* respectively. * * g_direct_hash() is also the appropriate hash function for keys - * of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros). + * of the form `GINT_TO_POINTER (n)` (or similar macros). * * <!-- FIXME: Need more here. --> A good hash functions should produce * hash values that are evenly distributed over a fairly large range. @@ -550,7 +602,8 @@ * a more secure hash function when using a GHashTable with keys * that originate in untrusted data (such as HTTP requests). * Using g_str_hash() in that situation might make your application - * vulerable to <ulink url="https://lwn.net/Articles/474912/">Algorithmic Complexity Attacks</ulink>. + * vulerable to + * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). * * The key to choosing a good hash is unpredictability. Even * cryptographic hashes are very easy to find collisions for when the @@ -565,8 +618,8 @@ * GHashTable: * * The #GHashTable struct is an opaque data structure to represent a - * <link linkend="glib-Hash-Tables">Hash Table</link>. It should only be - * accessed via the following functions. + * [Hash Table][glib-Hash-Tables]. It should only be accessed via the + * following functions. */ @@ -587,12 +640,14 @@ * @prev: pointer to the previous hook in the list * @ref_count: the reference count of this hook * @hook_id: the id of this hook, which is unique within its list - * @flags: flags which are set for this hook. See #GHookFlagMask for predefined flags - * @func: the function to call when this hook is invoked. The possible signatures for this function are #GHookFunc and #GHookCheckFunc - * @destroy: the default @finalize_hook function of a #GHookList calls this member of the hook that is being finalized + * @flags: flags which are set for this hook. See #GHookFlagMask for + * predefined flags + * @func: the function to call when this hook is invoked. The possible + * signatures for this function are #GHookFunc and #GHookCheckFunc + * @destroy: the default @finalize_hook function of a #GHookList calls + * this member of the hook that is being finalized * - * The <structname>GHook</structname> struct represents a single hook - * function in a #GHookList. + * The #GHook struct represents a single hook function in a #GHookList. */ @@ -626,7 +681,7 @@ * Defines the type of function used to compare #GHook elements in * g_hook_insert_sorted(). * - * Returns: a value <= 0 if @new_hook should be before @sibling + * Returns: a value <= 0 if @new_hook should be before @sibling */ @@ -655,7 +710,8 @@ * GHookFlagMask: * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run - * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for hook flags; see %G_HOOK_FLAG_USER_SHIFT + * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for + * hook flags; see %G_HOOK_FLAG_USER_SHIFT * * Flags used internally in the #GHook implementation. */ @@ -677,11 +733,11 @@ * @is_setup: 1 if the #GHookList has been initialized * @hooks: the first #GHook element in the list * @dummy3: unused - * @finalize_hook: the function to call to finalize a #GHook element. The default behaviour is to call the hooks @destroy function + * @finalize_hook: the function to call to finalize a #GHook element. + * The default behaviour is to call the hooks @destroy function * @dummy: unused * - * The <structname>GHookList</structname> struct represents a - * list of hook functions. + * The #GHookList struct represents a list of hook functions. */ @@ -861,9 +917,9 @@ * Stuffs an integer into a pointer type. * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros <emphasis>only</emphasis> allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ @@ -898,7 +954,8 @@ * @G_IO_OUT: Data can be written (without blocking). * @G_IO_PRI: There is urgent data to read. * @G_IO_ERR: Error condition. - * @G_IO_HUP: Hung up (the connection has been broken, usually for pipes and sockets). + * @G_IO_HUP: Hung up (the connection has been broken, usually for + * pipes and sockets). * @G_IO_NVAL: Invalid request. The file descriptor is not open. * * A bitwise combination representing a condition to watch for on an @@ -920,14 +977,26 @@ /** * GIOFlags: - * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal> (see the documentation of the UNIX open() syscall). - * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> (see the documentation of the UNIX open() syscall). - * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag cannot be changed. - * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. This flag cannot be changed. - * @G_IO_FLAG_IS_SEEKABLE: 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. + * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND + * (see the documentation of the UNIX open() syscall) + * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to + * %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open() + * syscall) + * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. + * This flag cannot be changed. + * @G_IO_FLAG_IS_WRITABLE: 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 + * @G_IO_FLAG_IS_SEEKABLE: 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. * @G_IO_FLAG_MASK: the mask that specifies all the valid flags. - * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from g_io_channel_get_flags(). - * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify with g_io_channel_set_flags(). + * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from + * g_io_channel_get_flags() + * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify + * with g_io_channel_set_flags() * * Specifies properties of a #GIOChannel. Some of the flags can only be * read with g_io_channel_get_flags(), but not changed with @@ -945,20 +1014,41 @@ * g_io_add_watch_full(), which is called when the requested condition * on a #GIOChannel is satisfied. * - * Returns: the function should return %FALSE if the event source should be removed + * Returns: the function should return %FALSE if the event source + * should be removed */ /** * GIOFuncs: - * @io_read: reads raw bytes from the channel. This is called from various functions such as g_io_channel_read_chars() to read raw bytes from the channel. Encoding and buffering issues are dealt with at a higher level. - * @io_write: writes raw bytes to the channel. This is called from various functions such as g_io_channel_write_chars() to write raw bytes to the channel. Encoding and buffering issues are dealt with at a higher level. - * @io_seek: (optional) seeks the channel. This is called from g_io_channel_seek() on channels that support it. - * @io_close: closes the channel. This is called from g_io_channel_close() after flushing the buffers. - * @io_create_watch: creates a watch on the channel. This call corresponds directly to g_io_create_watch(). - * @io_free: called from g_io_channel_unref() when the channel needs to be freed. This function must free the memory associated with the channel, including freeing the #GIOChannel structure itself. The channel buffers have been flushed and possibly @io_close has been called by the time this function is called. - * @io_set_flags: sets the #GIOFlags on the channel. This is called from g_io_channel_set_flags() with all flags except for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked out. - * @io_get_flags: gets the #GIOFlags for the channel. This function need only return the %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() automatically adds the others as appropriate. + * @io_read: reads raw bytes from the channel. This is called from + * various functions such as g_io_channel_read_chars() to + * read raw bytes from the channel. Encoding and buffering + * issues are dealt with at a higher level. + * @io_write: writes raw bytes to the channel. This is called from + * various functions such as g_io_channel_write_chars() to + * write raw bytes to the channel. Encoding and buffering + * issues are dealt with at a higher level. + * @io_seek: (optional) seeks the channel. This is called from + * g_io_channel_seek() on channels that support it. + * @io_close: closes the channel. This is called from + * g_io_channel_close() after flushing the buffers. + * @io_create_watch: creates a watch on the channel. This call + * corresponds directly to g_io_create_watch(). + * @io_free: called from g_io_channel_unref() when the channel needs to + * be freed. This function must free the memory associated + * with the channel, including freeing the #GIOChannel + * structure itself. The channel buffers have been flushed + * and possibly @io_close has been called by the time this + * function is called. + * @io_set_flags: sets the #GIOFlags on the channel. This is called + * from g_io_channel_set_flags() with all flags except + * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked + * out. + * @io_get_flags: gets the #GIOFlags for the channel. This function + * need only return the %G_IO_FLAG_APPEND and + * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() + * automatically adds the others as appropriate. * * A table of functions used to handle different types of #GIOChannel * in a generic way. @@ -986,7 +1076,8 @@ /** * GKeyFileError: - * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding + * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in + * an unknown encoding * @G_KEY_FILE_ERROR_PARSE: document was ill-formed * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found @@ -1000,8 +1091,14 @@ /** * GKeyFileFlags: * @G_KEY_FILE_NONE: No flags, default behaviour - * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise all comments will be lost when the key file is written back. - * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise only the translations for the current language will be written back. + * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the + * (possibly modified) contents of the key file back to a file; + * otherwise all comments will be lost when the key file is + * written back. + * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the + * (possibly modified) contents of the key file back to a file; + * otherwise only the translations for the current language will be + * written back. * * Flags which influence the parsing. */ @@ -1014,19 +1111,10 @@ * @micro: the micro version to check for * * Checks the version of the GLib library that is being compiled - * against. - * - * <example> - * <title>Checking the version of the GLib library</title> - * <programlisting> - * if (!GLIB_CHECK_VERSION (1, 2, 0)) - * g_error ("GLib version 1.2.0 or above is needed"); - * </programlisting> - * </example> + * against. See glib_check_version() for a runtime check. * - * See glib_check_version() for a runtime check. - * - * Returns: %TRUE if the version of the GLib header files is the same as or newer than the passed-in version. + * Returns: %TRUE if the version of the GLib header files + * is the same as or newer than the passed-in version. */ @@ -1114,9 +1202,11 @@ /** * GList: - * @data: holds the element's data, which can be a pointer to any kind of data, or any integer value using the <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>. - * @next: contains the link to the next element in the list. - * @prev: contains the link to the previous element in the list. + * @data: holds the element's data, which can be a pointer to any kind + * of data, or any integer value using the + * [Type Conversion Macros][glib-Type-Conversion-Macros] + * @next: contains the link to the next element in the list + * @prev: contains the link to the previous element in the list * * The #GList struct is used for each element in a doubly-linked list. */ @@ -1125,11 +1215,18 @@ /** * GLogFunc: * @log_domain: the log domain of the message - * @log_level: the log level of the message (including the fatal and recursion flags) + * @log_level: the log level of the message (including the + * fatal and recursion flags) * @message: the message to process * @user_data: user data, set in g_log_set_handler() * * Specifies the prototype of log handler functions. + * + * The default log handler, g_log_default_handler(), automatically appends a + * new-line character to @message when printing it. It is advised that any + * custom log handler functions behave similarly, so that logging calls in user + * code do not need modifying to add a new-line character to the message if the + * log handler is changed. */ @@ -1137,11 +1234,14 @@ * GLogLevelFlags: * @G_LOG_FLAG_RECURSION: internal flag * @G_LOG_FLAG_FATAL: internal flag - * @G_LOG_LEVEL_ERROR: log level for errors, see g_error(). This level is also used for messages produced by g_assert(). - * @G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical(). This level is also used for messages produced by g_return_if_fail() and g_return_val_if_fail(). + * @G_LOG_LEVEL_ERROR: log level for errors, see g_error(). + * This level is also used for messages produced by g_assert(). + * @G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical(). + * This level is also used for messages produced by g_return_if_fail() + * and g_return_val_if_fail(). * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning() * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message() - * @G_LOG_LEVEL_INFO: log level for informational messages + * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info() * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug() * @G_LOG_LEVEL_MASK: a mask including all log levels * @@ -1163,12 +1263,27 @@ /** * GMarkupCollectType: - * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes to collect - * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from the attribute_values[] array. Expects a parameter of type (const char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the attribute isn't present then the pointer will be set to %NULL - * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but expects a parameter of type (char **) and g_strdup()s the returned pointer. The pointer must be freed with g_free() - * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *) and parses the attribute value as a boolean. Sets %FALSE if the attribute isn't present. Valid boolean values consist of (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", "yes", "y", "1" - * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but in the case of a missing attribute a value is set that compares equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is implied - * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. If present, allows the attribute not to appear. A default value is set depending on what value type is used + * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes + * to collect + * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from + * the attribute_values[] array. Expects a parameter of type (const + * char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the + * attribute isn't present then the pointer will be set to %NULL + * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but + * expects a parameter of type (char **) and g_strdup()s the + * returned pointer. The pointer must be freed with g_free() + * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *) + * and parses the attribute value as a boolean. Sets %FALSE if the + * attribute isn't present. Valid boolean values consist of + * (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", + * "yes", "y", "1" + * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but + * in the case of a missing attribute a value is set that compares + * equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is + * implied + * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. + * If present, allows the attribute not to appear. A default value + * is set depending on what value type is used * * A mixed enumerated type and flags field. You must specify one type * (string, strdup, boolean, tristate). Additionally, you may optionally @@ -1184,33 +1299,26 @@ * * The #GMutex struct is an opaque data structure to represent a mutex * (mutual exclusion). It can be used to protect data against shared - * access. Take for example the following function: + * access. * - * <example> - * <title>A function which will not work in a threaded environment</title> - * <programlisting> + * Take for example the following function: + * |[<!-- language="C" --> * int * give_me_next_number (void) * { * static int current_number = 0; * - * /<!-- -->* now do a very complicated calculation to calculate the new - * * number, this might for example be a random number generator - * *<!-- -->/ + * // now do a very complicated calculation to calculate the new + * // number, this might for example be a random number generator * current_number = calc_next_number (current_number); * * return current_number; * } - * </programlisting> - * </example> - * + * ]| * It is easy to see that this won't work in a multi-threaded * application. There current_number must be protected against shared * access. A #GMutex can be used as a solution to this problem: - * - * <example> - * <title>Using GMutex to protected a shared variable</title> - * <programlisting> + * |[<!-- language="C" --> * int * give_me_next_number (void) * { @@ -1218,15 +1326,13 @@ * static int current_number = 0; * int ret_val; * - * g_mutex_lock (&mutex); + * g_mutex_lock (&mutex); * ret_val = current_number = calc_next_number (current_number); - * g_mutex_unlock (&mutex); + * g_mutex_unlock (&mutex); * * return ret_val; * } - * </programlisting> - * </example> - * + * ]| * Notice that the #GMutex is not initialised to any particular value. * Its placement in static storage ensures that it will be initialised * to all-zeros, which is appropriate. @@ -1234,21 +1340,23 @@ * If a #GMutex is placed in other contexts (eg: embedded in a struct) * then it must be explicitly initialised using g_mutex_init(). * - * A #GMutex should only be accessed via <function>g_mutex_</function> - * functions. + * A #GMutex should only be accessed via g_mutex_ functions. */ /** * GNode: * @data: contains the actual data of the node. - * @next: points to the node's next sibling (a sibling is another #GNode with the same parent). + * @next: points to the node's next sibling (a sibling is another + * #GNode with the same parent). * @prev: points to the node's previous sibling. - * @parent: points to the parent of the #GNode, or is %NULL if the #GNode is the root of the tree. - * @children: points to the first child of the #GNode. The other children are accessed by using the @next pointer of each child. + * @parent: points to the parent of the #GNode, or is %NULL if the + * #GNode is the root of the tree. + * @children: points to the first child of the #GNode. The other + * children are accessed by using the @next pointer of each + * child. * - * The #GNode struct represents one node in a - * <link linkend="glib-N-ary-Trees">N-ary Tree</link>. fields + * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. */ @@ -1280,7 +1388,8 @@ /** * GOnce: * @status: the status of the #GOnce - * @retval: the value returned by the call to the function, if @status is %G_ONCE_STATUS_READY + * @retval: the value returned by the call to the function, if @status + * is %G_ONCE_STATUS_READY * * A #GOnce struct controls a one-time initialization function. Any * one-time initialization function must have its own unique #GOnce @@ -1311,9 +1420,9 @@ * been stored in the pointer with GINT_TO_POINTER(). * * Remember, you may not store pointers in integers. This is not portable - * in any way, shape or form. These macros <emphasis>only</emphasis> allow - * storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. + * in any way, shape or form. These macros only allow storing integers in + * pointers, and only preserve 32 bits of the integer; values outside the + * range of a 32-bit integer will be mangled. */ @@ -1338,9 +1447,8 @@ /** * GPatternSpec: * - * A <structname>GPatternSpec</structname> is the 'compiled' form of a - * pattern. This structure is opaque and its fields cannot be accessed - * directly. + * A GPatternSpec struct is the 'compiled' form of a pattern. This + * structure is opaque and its fields cannot be accessed directly. */ @@ -1363,14 +1471,15 @@ * See G_PRIVATE_INIT() for a couple of examples. * * The #GPrivate structure should be considered opaque. It should only - * be accessed via the <function>g_private_</function> functions. + * be accessed via the g_private_ functions. */ /** * GPtrArray: - * @pdata: points to the array of pointers, which may be moved when the array grows. - * @len: number of pointers in the array. + * @pdata: points to the array of pointers, which may be moved when the + * array grows + * @len: number of pointers in the array * * Contains the public fields of a pointer array. */ @@ -1398,9 +1507,8 @@ * simultaneous read-only access (by holding the 'reader' lock via * g_rw_lock_reader_lock()). * - * <example> - * <title>An array with access functions</title> - * <programlisting> + * Here is an example for an array with access functions: + * |[<!-- language="C" --> * GRWLock lock; * GPtrArray *array; * @@ -1412,10 +1520,10 @@ * if (!array) * return NULL; * - * g_rw_lock_reader_lock (&lock); - * if (index < array->len) + * g_rw_lock_reader_lock (&lock); + * if (index < array->len) * retval = g_ptr_array_index (array, index); - * g_rw_lock_reader_unlock (&lock); + * g_rw_lock_reader_unlock (&lock); * * return retval; * } @@ -1423,35 +1531,30 @@ * void * my_array_set (guint index, gpointer data) * { - * g_rw_lock_writer_lock (&lock); + * g_rw_lock_writer_lock (&lock); * * if (!array) - * array = g_ptr_array_new (<!-- -->); + * array = g_ptr_array_new (); * * if (index >= array->len) * g_ptr_array_set_size (array, index+1); * g_ptr_array_index (array, index) = data; * - * g_rw_lock_writer_unlock (&lock); + * g_rw_lock_writer_unlock (&lock); * } - * </programlisting> - * <para> - * This example shows an array which can be accessed by many readers - * (the <function>my_array_get()</function> function) simultaneously, - * whereas the writers (the <function>my_array_set()</function> - * function) will only be allowed once at a time and only if no readers - * currently access the array. This is because of the potentially - * dangerous resizing of the array. Using these functions is fully - * multi-thread safe now. - * </para> - * </example> + * ]| + * This example shows an array which can be accessed by many readers + * (the my_array_get() function) simultaneously, whereas the writers + * (the my_array_set() function) will only be allowed one at a time + * and only if no readers currently access the array. This is because + * of the potentially dangerous resizing of the array. Using these + * functions is fully multi-thread safe now. * * If a #GRWLock is allocated in static storage then it can be used * without initialisation. Otherwise, you should call * g_rw_lock_init() on it and g_rw_lock_clear() when done. * - * A GRWLock should only be accessed with the - * <function>g_rw_lock_</function> functions. + * A GRWLock should only be accessed with the g_rw_lock_ functions. * * Since: 2.32 */ @@ -1460,8 +1563,8 @@ /** * GRand: * - * The #GRand struct is an opaque data structure. It should only be - * accessed through the <function>g_rand_*</function> functions. + * The GRand struct is an opaque data structure. It should only be + * accessed through the g_rand_* functions. */ @@ -1479,7 +1582,7 @@ * g_rec_mutex_init() on it and g_rec_mutex_clear() when done. * * A GRecMutex should only be accessed with the - * <function>g_rec_mutex_</function> functions. + * g_rec_mutex_ functions. * * Since: 2.32 */ @@ -1535,7 +1638,9 @@ /** * GSList: - * @data: holds the element's data, which can be a pointer to any kind of data, or any integer value using the <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>. + * @data: holds the element's data, which can be a pointer to any kind + * of data, or any integer value using the + * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list. * * The #GSList struct is used for each element in the singly-linked @@ -1620,31 +1725,61 @@ /** * GScannerConfig: - * @cset_skip_characters: specifies which characters should be skipped by the scanner (the default is the whitespace characters: space, tab, carriage-return and line-feed). - * @cset_identifier_first: specifies the characters which can start identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). - * @cset_identifier_nth: specifies the characters which can be used in identifiers, after the first character (the default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, #G_CSET_LATINC). - * @cpair_comment_single: specifies the characters at the start and end of single-line comments. The default is "#\n" which means that single-line comments start with a '#' and continue until a '\n' (end of line). - * @case_sensitive: specifies if symbols are case sensitive (the default is %FALSE). - * @skip_comment_multi: specifies if multi-line comments are skipped and not returned as tokens (the default is %TRUE). - * @skip_comment_single: specifies if single-line comments are skipped and not returned as tokens (the default is %TRUE). - * @scan_comment_multi: specifies if multi-line comments are recognized (the default is %TRUE). - * @scan_identifier: specifies if identifiers are recognized (the default is %TRUE). - * @scan_identifier_1char: specifies if single-character identifiers are recognized (the default is %FALSE). - * @scan_identifier_NULL: specifies if %NULL is reported as %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). - * @scan_symbols: specifies if symbols are recognized (the default is %TRUE). - * @scan_binary: specifies if binary numbers are recognized (the default is %FALSE). - * @scan_octal: specifies if octal numbers are recognized (the default is %TRUE). - * @scan_float: specifies if floating point numbers are recognized (the default is %TRUE). - * @scan_hex: specifies if hexadecimal numbers are recognized (the default is %TRUE). - * @scan_hex_dollar: specifies if '$' is recognized as a prefix for hexadecimal numbers (the default is %FALSE). - * @scan_string_sq: specifies if strings can be enclosed in single quotes (the default is %TRUE). - * @scan_string_dq: specifies if strings can be enclosed in double quotes (the default is %TRUE). - * @numbers_2_int: specifies if binary, octal and hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE). - * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT (the default is %FALSE). - * @identifier_2_string: specifies if identifiers are reported as strings (the default is %FALSE). - * @char_2_token: specifies if characters are reported by setting <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default is %TRUE). - * @symbol_2_token: specifies if symbols are reported by setting <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the default is %FALSE). - * @scope_0_fallback: specifies if a symbol is searched for in the default scope in addition to the current scope (the default is %FALSE). + * @cset_skip_characters: specifies which characters should be skipped + * by the scanner (the default is the whitespace characters: space, + * tab, carriage-return and line-feed). + * @cset_identifier_first: specifies the characters which can start + * identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). + * @cset_identifier_nth: specifies the characters which can be used + * in identifiers, after the first character (the default is + * #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, + * #G_CSET_LATINC). + * @cpair_comment_single: specifies the characters at the start and + * end of single-line comments. The default is "#\n" which means + * that single-line comments start with a '#' and continue until + * a '\n' (end of line). + * @case_sensitive: specifies if symbols are case sensitive (the + * default is %FALSE). + * @skip_comment_multi: specifies if multi-line comments are skipped + * and not returned as tokens (the default is %TRUE). + * @skip_comment_single: specifies if single-line comments are skipped + * and not returned as tokens (the default is %TRUE). + * @scan_comment_multi: specifies if multi-line comments are recognized + * (the default is %TRUE). + * @scan_identifier: specifies if identifiers are recognized (the + * default is %TRUE). + * @scan_identifier_1char: specifies if single-character + * identifiers are recognized (the default is %FALSE). + * @scan_identifier_NULL: specifies if %NULL is reported as + * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). + * @scan_symbols: specifies if symbols are recognized (the default + * is %TRUE). + * @scan_binary: specifies if binary numbers are recognized (the + * default is %FALSE). + * @scan_octal: specifies if octal numbers are recognized (the + * default is %TRUE). + * @scan_float: specifies if floating point numbers are recognized + * (the default is %TRUE). + * @scan_hex: specifies if hexadecimal numbers are recognized (the + * default is %TRUE). + * @scan_hex_dollar: specifies if '$' is recognized as a prefix for + * hexadecimal numbers (the default is %FALSE). + * @scan_string_sq: specifies if strings can be enclosed in single + * quotes (the default is %TRUE). + * @scan_string_dq: specifies if strings can be enclosed in double + * quotes (the default is %TRUE). + * @numbers_2_int: specifies if binary, octal and hexadecimal numbers + * are reported as #G_TOKEN_INT (the default is %TRUE). + * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT + * (the default is %FALSE). + * @identifier_2_string: specifies if identifiers are reported as strings + * (the default is %FALSE). + * @char_2_token: specifies if characters are reported by setting + * `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE). + * @symbol_2_token: specifies if symbols are reported by setting + * `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE). + * @scope_0_fallback: specifies if a symbol is searched for in the + * default scope in addition to the current scope (the default is %FALSE). * @store_int64: use value.v_int64 rather than v_int * * Specifies the #GScanner parser configuration. Most settings can @@ -1657,7 +1792,8 @@ * GScannerMsgFunc: * @scanner: a #GScanner * @message: the message - * @error: %TRUE if the message signals an error, %FALSE if it signals a warning. + * @error: %TRUE if the message signals an error, + * %FALSE if it signals a warning. * * Specifies the type of the message handler function. */ @@ -1678,7 +1814,7 @@ * GSequence: * * The #GSequence struct is an opaque data type representing a - * <link linkend="glib-Sequences">Sequence</link> data type. + * [sequence][glib-Sequences] data type. */ @@ -1700,7 +1836,8 @@ * It must return zero if the iterators compare equal, a negative value * if @a comes before @b, and a positive value if @b comes before @a. * - * Returns: zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before @a. + * Returns: zero if the iterators are equal, a negative value if @a + * comes before @b, and a positive value if @b comes before @a. */ @@ -1717,7 +1854,7 @@ /** * GStatBuf: * - * A type corresponding to the appropriate struct type for the stat + * A type corresponding to the appropriate struct type for the stat() * system call, depending on the platform and/or compiler being used. * * See g_stat() for more information. @@ -1726,9 +1863,13 @@ /** * GString: - * @str: points to the character data. It may move as text is added. The @str field is null-terminated and so can be used as an ordinary C string. - * @len: contains the length of the string, not including the terminating nul byte. - * @allocated_len: the number of bytes that can be stored in the string before it needs to be reallocated. May be larger than @len. + * @str: points to the character data. It may move as text is added. + * The @str field is null-terminated and so + * can be used as an ordinary C string. + * @len: contains the length of the string, not including the + * terminating nul byte. + * @allocated_len: the number of bytes that can be stored in the + * string before it needs to be reallocated. May be larger than @len. * * The GString struct contains the public fields of a GString. */ @@ -1761,6 +1902,32 @@ /** + * GTestFileType: + * @G_TEST_DIST: a file that was included in the distribution tarball + * @G_TEST_BUILT: a file that was built on the compiling machine + * + * The type of file to return the filename for, when used with + * g_test_build_filename(). + * + * 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 + * `DIST_EXTRA` or `dist_schema_DATA` + * sense, in which case they will always be in the srcdir) or built (in + * 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 + * part of the build-from-git process (but then are distributed with the + * tarball) always go in srcdir (even if doing a srcdir != builddir + * build from git) and are considered as distributed files. + * + * Since: 2.38 + */ + + +/** * GTestFixtureFunc: * @fixture: the test fixture * @user_data: the data provided when registering the test @@ -1790,6 +1957,27 @@ /** + * GTestSubprocessFlags: + * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child + * process will inherit the parent's stdin. Otherwise, the child's + * stdin is redirected to `/dev/null`. + * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child + * process will inherit the parent's stdout. Otherwise, the child's + * stdout will not be visible, but it will be captured to allow + * later tests with g_test_trap_assert_stdout(). + * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child + * process will inherit the parent's stderr. Otherwise, the child's + * stderr will not be visible, but it will be captured to allow + * later tests with g_test_trap_assert_stderr(). + * + * Flags to pass to g_test_trap_subprocess() to control input and output. + * + * Note that in contrast with g_test_trap_fork(), the default is to + * not show stdout and stderr. + */ + + +/** * GTestSuite: * * An opaque structure representing a test suite. @@ -1798,12 +1986,24 @@ /** * GTestTrapFlags: - * @G_TEST_TRAP_SILENCE_STDOUT: 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(). - * @G_TEST_TRAP_SILENCE_STDERR: 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(). - * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the forked child process is shared with stdin of its parent process. It is redirected to <filename>/dev/null</filename> otherwise. + * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to + * `/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(). + * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to + * `/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(). + * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the + * child process is shared with stdin of its parent process. + * It is redirected to `/dev/null` otherwise. * * Test traps are guards around forked tests. * These flags determine what traps to set. + * + * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), + * which is deprecated. g_test_trap_subprocess() uses + * #GTestTrapSubprocessFlags. */ @@ -1812,7 +2012,7 @@ * * The #GThread struct represents a running thread. This struct * is returned by g_thread_new() or g_thread_try_new(). You can - * obtain the #GThread struct representing the current thead by + * obtain the #GThread struct representing the current thread by * calling g_thread_self(). * * GThread is refcounted, see g_thread_ref() and g_thread_unref(). @@ -1828,7 +2028,8 @@ /** * GThreadError: - * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource shortage. Try again later. + * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource + * shortage. Try again later. * * Possible errors of thread related functions. */ @@ -1860,21 +2061,22 @@ /** * GTime: * - * Simply a replacement for <type>time_t</type>. It has been deprecated - * since it is <emphasis>not</emphasis> equivalent to <type>time_t</type> - * on 64-bit platforms with a 64-bit <type>time_t</type>. - * Unrelated to #GTimer. + * Simply a replacement for time_t. It has been deprecated + * since it is not equivalent to time_t on 64-bit platforms + * with a 64-bit time_t. Unrelated to #GTimer. * - * Note that <type>GTime</type> is defined to always be a 32bit integer, - * unlike <type>time_t</type> which may be 64bit on some systems. - * Therefore, <type>GTime</type> will overflow in the year 2038, and - * you cannot use the address of a <type>GTime</type> variable as argument - * to the UNIX time() function. Instead, do the following: - * |[ + * Note that #GTime is defined to always be a 32-bit integer, + * unlike time_t which may be 64-bit on some systems. Therefore, + * #GTime will overflow in the year 2038, and you cannot use the + * address of a #GTime variable as argument to the UNIX time() + * function. + * + * Instead, do the following: + * |[<!-- language="C" --> * time_t ttime; * GTime gtime; * - * time (&ttime); + * time (&ttime); * gtime = (GTime)ttime; * ]| */ @@ -1886,8 +2088,8 @@ * @tv_usec: microseconds * * Represents a precise time, with seconds and microseconds. - * Similar to the <structname>struct timeval</structname> returned by - * the gettimeofday() UNIX system call. + * Similar to the struct timeval returned by the gettimeofday() + * UNIX system call. * * GLib is attempting to unify around the use of 64bit integers to * represent microsecond-precision time. As such, this type will be @@ -1898,7 +2100,7 @@ /** * GTimeZone: * - * #GDateTime is an opaque structure whose members cannot be accessed + * #GTimeZone is an opaque structure whose members cannot be accessed * directly. * * Since: 2.26 @@ -1964,17 +2166,23 @@ /** * GTrashStack: - * @next: pointer to the previous element of the stack, gets stored in the first <literal>sizeof (gpointer)</literal> bytes of the element + * @next: pointer to the previous element of the stack, + * gets stored in the first `sizeof (gpointer)` + * bytes of the element * * Each piece of memory that is pushed onto the stack - * is cast to a <structname>GTrashStack*</structname>. + * is cast to a GTrashStack*. */ /** * GTraverseFlags: - * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_LEAFS. - * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_NON_LEAFS. + * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has + * been introduced in 2.6, for older version use + * %G_TRAVERSE_LEAFS. + * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This + * name has been introduced in 2.6, for older + * version use %G_TRAVERSE_NON_LEAFS. * @G_TRAVERSE_ALL: all nodes should be visited. * @G_TRAVERSE_MASK: a mask of all traverse flags. * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES. @@ -1987,38 +2195,54 @@ /** * GTraverseFunc: - * @key: a key of a #GTree node. - * @value: the value corresponding to the key. - * @data: user data passed to g_tree_traverse(). + * @key: a key of a #GTree node + * @value: the value corresponding to the key + * @data: user data passed to g_tree_traverse() * * Specifies the type of function passed to g_tree_traverse(). It is * passed the key and value of each node, together with the @user_data * parameter passed to g_tree_traverse(). If the function returns * %TRUE, the traversal is stopped. * - * Returns: %TRUE to stop the traversal. + * Returns: %TRUE to stop the traversal */ /** * GTraverseType: - * @G_IN_ORDER: vists a node's left child first, then the node itself, then its right child. This is the one to use if you want the output sorted according to the compare function. + * @G_IN_ORDER: vists a node's left child first, then the node itself, + * then its right child. This is the one to use if you + * want the output sorted according to the compare + * function. * @G_PRE_ORDER: visits a node, then its children. * @G_POST_ORDER: visits the node's children, then the node itself. - * @G_LEVEL_ORDER: 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 vists the root node first, then its children, then its grandchildren, and so on. Note that this is less efficient than the other orders. + * @G_LEVEL_ORDER: 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. * * 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 + *  */ /** * GTree: * - * The <structname>GTree</structname> struct is an opaque data - * structure representing a <link - * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It - * should be accessed only by using the following functions. + * The GTree struct is an opaque data structure representing a + * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be + * accessed only by using the following functions. */ @@ -2341,9 +2565,11 @@ * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer. * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer. * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index. - * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating point value. + * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating + * point value. * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string. - * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path string. + * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path + * string. * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string. * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant. * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value. @@ -2358,6 +2584,103 @@ /** + * GVariantDict: (skip) + * + * #GVariantDict is a mutable interface to #GVariant dictionaries. + * + * It can be used for doing a sequence of dictionary lookups in an + * efficient way on an existing #GVariant dictionary or it can be used + * to construct new dictionaries with a hashtable-like interface. It + * can also be used for taking existing dictionaries and modifying them + * in order to create new ones. + * + * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT + * dictionaries. + * + * It is possible to use #GVariantDict allocated on the stack or on the + * heap. When using a stack-allocated #GVariantDict, you begin with a + * call to g_variant_dict_init() and free the resources with a call to + * g_variant_dict_clear(). + * + * Heap-allocated #GVariantDict follows normal refcounting rules: you + * allocate it with g_variant_dict_new() and use g_variant_dict_ref() + * and g_variant_dict_unref(). + * + * g_variant_dict_end() is used to convert the #GVariantDict back into a + * dictionary-type #GVariant. When used with stack-allocated instances, + * this also implicitly frees all associated memory, but for + * heap-allocated instances, you must still call g_variant_dict_unref() + * afterwards. + * + * You will typically want to use a heap-allocated #GVariantDict when + * you expose it as part of an API. For most other uses, the + * stack-allocated form will be more convenient. + * + * Consider the following two examples that do the same thing in each + * style: take an existing dictionary and look up the "count" uint32 + * key, adding 1 to it if it is found, or returning an error if the + * key is not found. Each returns the new dictionary as a floating + * #GVariant. + * + * ## Using a stack-allocated GVariantDict + * + * |[ + * GVariant * + * add_to_count (GVariant *orig, + * GError **error) + * { + * GVariantDict dict; + * guint32 count; + * + * g_variant_dict_init (&dict, orig); + * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) + * { + * g_set_error (...); + * g_variant_dict_clear (&dict); + * return NULL; + * } + * + * g_variant_dict_insert (&dict, "count", "u", count + 1); + * + * return g_variant_dict_end (&dict); + * } + * ]| + * + * ## Using heap-allocated GVariantDict + * + * |[ + * GVariant * + * add_to_count (GVariant *orig, + * GError **error) + * { + * GVariantDict *dict; + * GVariant *result; + * guint32 count; + * + * dict = g_variant_dict_new (orig); + * + * if (g_variant_dict_lookup (dict, "count", "u", &count)) + * { + * g_variant_dict_insert (dict, "count", "u", count + 1); + * result = g_variant_dict_end (dict); + * } + * else + * { + * g_set_error (...); + * result = NULL; + * } + * + * g_variant_dict_unref (dict); + * + * return result; + * } + * ]| + * + * Since: 2.40 + */ + + +/** * GVariantIter: (skip) * * #GVariantIter is an opaque data structure and can only be accessed @@ -2398,10 +2721,10 @@ * on systems with 64bit IEEE-compatible doubles. * * The typical usage would be something like: - * |[ + * |[<!-- language="C" --> * char buf[G_ASCII_DTOSTR_BUF_SIZE]; * - * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); + * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); * ]| */ @@ -2424,7 +2747,7 @@ * G_BEGIN_DECLS: * * Used (along with #G_END_DECLS) to bracket header files. If the - * compiler in use is a C++ compiler, adds <literal>extern "C"</literal> + * compiler in use is a C++ compiler, adds extern "C" * around the header. */ @@ -2449,17 +2772,17 @@ /** * G_CONST_RETURN: * - * If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands - * to nothing. By default, the macro expands to <literal>const</literal>. - * The macro should be used in place of <literal>const</literal> for - * functions that return a value that should not be modified. The - * purpose of this macro is to allow us to turn on <literal>const</literal> - * for returned constant strings by default, while allowing programmers - * who find that annoying to turn it off. This macro should only be used - * for return values and for <emphasis>out</emphasis> parameters, it doesn't - * make sense for <emphasis>in</emphasis> parameters. + * If %G_DISABLE_CONST_RETURNS is defined, this macro expands + * to nothing. By default, the macro expands to const. The macro + * can be used in place of const for functions that return a value + * that should not be modified. The purpose of this macro is to allow + * us to turn on const for returned constant strings by default, while + * allowing programmers who find that annoying to turn it off. This macro + * should only be used for return values and for "out" parameters, it + * doesn't make sense for "in" parameters. * - * Deprecated: 2.30: API providers should replace all existing uses with <literal>const</literal> and API consumers should adjust their code accordingly + * Deprecated: 2.30: API providers should replace all existing uses with + * const and API consumers should adjust their code accordingly */ @@ -2529,9 +2852,10 @@ * * A convenience macro which defines a function returning the * #GQuark for the name @QN. The function will be named - * @q_n<!-- -->_quark(). - * Note that the quark name will be stringified automatically in the - * macro, so you shouldn't use double quotes. + * @q_n_quark(). + * + * Note that the quark name will be stringified automatically + * in the macro, so you shouldn't use double quotes. * * Since: 2.34 */ @@ -2554,8 +2878,8 @@ * @f: the name of the function that this function was deprecated for * * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark - * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it is - * meant to be portable across different compilers and must be placed + * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it + * is meant to be portable across different compilers and must be placed * before the function declaration. * * Since: 2.32 @@ -2589,7 +2913,7 @@ * G_END_DECLS: * * Used (along with #G_BEGIN_DECLS) to bracket header files. If the - * compiler in use is a C++ compiler, adds <literal>extern "C"</literal> + * compiler in use is a C++ compiler, adds extern "C" * around the header. */ @@ -2611,10 +2935,10 @@ * include the percent-sign, such that you can add precision and length * modifiers between percent-sign and conversion specifier. * - * |[ + * |[<!-- language="C" --> * gint16 in; * gint32 out; - * sscanf ("42", "%" G_GINT16_FORMAT, &in) + * sscanf ("42", "%" G_GINT16_FORMAT, &in) * out = in * 1000; * g_print ("%" G_GINT32_FORMAT, out); * ]| @@ -2631,7 +2955,7 @@ * and conversion specifier and append a conversion specifier. * * The following example prints "0x7b"; - * |[ + * |[<!-- language="C" --> * gint16 value = 123; * g_print ("%#" G_GINT16_MODIFIER "x", value); * ]| @@ -2674,14 +2998,12 @@ * This is the platform dependent conversion specifier for scanning * and printing values of type #gint64. See also #G_GINT16_FORMAT. * - * <note><para> - * Some platforms do not support scanning and printing 64 bit integers, - * even though the types are supported. On such platforms #G_GINT64_FORMAT - * is not defined. Note that scanf() may not support 64 bit integers, even - * if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() + * Some platforms do not support scanning and printing 64-bit integers, + * even though the types are supported. On such platforms %G_GINT64_FORMAT + * is not defined. Note that scanf() may not support 64-bit integers, even + * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() * is not recommended for parsing anyway; consider using g_ascii_strtoull() * instead. - * </para></note> */ @@ -2692,11 +3014,9 @@ * for scanning and printing values of type #gint64 or #guint64. * It is a string literal. * - * <note><para> - * Some platforms do not support printing 64 bit integers, even - * though the types are supported. On such platforms #G_GINT64_MODIFIER + * Some platforms do not support printing 64-bit integers, even + * though the types are supported. On such platforms %G_GINT64_MODIFIER * is not defined. - * </para></note> * * Since: 2.4 */ @@ -2727,10 +3047,10 @@ * G_GNUC_ALLOC_SIZE: * @x: the index of the argument specifying the allocation size * - * Expands to the GNU C <literal>alloc_size</literal> function attribute - * if the compiler is a new enough <command>gcc</command>. This attribute - * tells the compiler that the function returns a pointer to memory of a - * size that is specified by the @x<!-- -->th function parameter. + * Expands to the GNU C alloc_size function attribute if the compiler + * is a new enough gcc. This attribute tells the compiler that the + * function returns a pointer to memory of a size that is specified + * by the @xth function parameter. * * Place the attribute after the function declaration, just before the * semicolon. @@ -2746,10 +3066,10 @@ * @x: the index of the argument specifying one factor of the allocation size * @y: the index of the argument specifying the second factor of the allocation size * - * Expands to the GNU C <literal>alloc_size</literal> function attribute - * if the compiler is a new enough <command>gcc</command>. This attribute - * tells the compiler that the function returns a pointer to memory of a - * size that is specified by the product of two function parameters. + * Expands to the GNU C alloc_size function attribute if the compiler is a + * new enough gcc. This attribute tells the compiler that the function returns + * a pointer to memory of a size that is specified by the product of two + * function parameters. * * Place the attribute after the function declaration, just before the * semicolon. @@ -2763,16 +3083,15 @@ /** * G_GNUC_BEGIN_IGNORE_DEPRECATIONS: * - * Tells <command>gcc</command> (if it is a new enough version) to - * temporarily stop emitting warnings when functions marked with - * %G_GNUC_DEPRECATED or %G_GNUC_DEPRECATED_FOR are called. This is - * useful for when you have one deprecated function calling another - * one, or when you still have regression tests for deprecated - * functions. + * Tells gcc (if it is a new enough version) to temporarily stop emitting + * warnings when functions marked with %G_GNUC_DEPRECATED or + * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have + * one deprecated function calling another one, or when you still have + * regression tests for deprecated functions. * * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you - * are not compiling with <literal>-Wdeprecated-declarations</literal> - * then neither macro has any effect.) + * are not compiling with `-Wdeprecated-declarations` then neither macro + * has any effect.) * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. @@ -2784,33 +3103,29 @@ /** * G_GNUC_CONST: * - * Expands to the GNU C <literal>const</literal> function attribute if - * the compiler is <command>gcc</command>. Declaring a function as const - * enables better optimization of calls to the function. A const function - * doesn't examine any values except its parameters, and has no effects - * except its return value. + * Expands to the GNU C const function attribute if the compiler is gcc. + * Declaring a function as const enables better optimization of calls to + * the function. A const function doesn't examine any values except its + * parameters, and has no effects except its return value. * * Place the attribute after the declaration, just before the semicolon. * * See the GNU C documentation for more details. * - * <note><para> * A function that has pointer arguments and examines the data pointed to - * must <emphasis>not</emphasis> be declared const. Likewise, a function - * that calls a non-const function usually must not be const. It doesn't - * make sense for a const function to return void. - * </para></note> + * must not be declared const. Likewise, a function that calls a non-const + * function usually must not be const. It doesn't make sense for a const + * function to return void. */ /** * G_GNUC_DEPRECATED: * - * Expands to the GNU C <literal>deprecated</literal> attribute if the - * compiler is <command>gcc</command>. It can be used to mark typedefs, - * variables and functions as deprecated. When called with the - * <option>-Wdeprecated-declarations</option> option, the compiler will - * generate warnings when deprecated interfaces are used. + * Expands to the GNU C deprecated attribute if the compiler is gcc. + * It can be used to mark typedefs, variables and functions as deprecated. + * When called with the `-Wdeprecated-declarations` option, + * gcc will generate warnings when deprecated interfaces are used. * * Place the attribute after the declaration, just before the semicolon. * @@ -2822,11 +3137,12 @@ /** * G_GNUC_DEPRECATED_FOR: - * @f: the intended replacement for the deprecated symbol, such as the name of a function + * @f: the intended replacement for the deprecated symbol, + * such as the name of a function * * Like %G_GNUC_DEPRECATED, but names the intended replacement for the - * deprecated symbol if the version of <command>gcc</command> in use is - * new enough to support custom deprecation messages. + * deprecated symbol if the version of gcc in use is new enough to support + * custom deprecation messages. * * Place the attribute after the declaration, just before the semicolon. * @@ -2844,8 +3160,8 @@ * G_GNUC_END_IGNORE_DEPRECATIONS: * * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling - * <command>gcc</command> to begin outputting warnings again - * (assuming those warnings had been enabled to begin with). + * gcc to begin outputting warnings again (assuming those warnings + * had been enabled to begin with). * * This macro can be used either inside or outside of a function body, * but must appear on a line by itself. @@ -2857,10 +3173,9 @@ /** * G_GNUC_EXTENSION: * - * Expands to <literal>__extension__</literal> when <command>gcc</command> - * is used as the compiler. This simply tells <command>gcc</command> not - * to warn about the following non-standard code when compiling with the - * <option>-pedantic</option> option. + * Expands to __extension__ when gcc is used as the compiler. This simply + * tells gcc not to warn about the following non-standard code when compiling + * with the `-pedantic` option. */ @@ -2868,21 +3183,20 @@ * G_GNUC_FORMAT: * @arg_idx: the index of the argument * - * Expands to the GNU C <literal>format_arg</literal> function attribute - * if the compiler is <command>gcc</command>. This function attribute - * specifies that a function takes a format string for a printf(), - * scanf(), strftime() or strfmon() style function and modifies it, - * so that the result can be passed to a printf(), scanf(), strftime() - * or strfmon() style function (with the remaining arguments to the - * format function the same as they would have been for the unmodified - * string). + * Expands to the GNU C format_arg function attribute if the compiler + * is gcc. This function attribute specifies that a function takes a + * format string for a printf(), scanf(), strftime() or strfmon() style + * function and modifies it, so that the result can be passed to a printf(), + * scanf(), strftime() or strfmon() style function (with the remaining + * arguments to the format function the same as they would have been + * for the unmodified string). * - * Place the attribute after the function declaration, just after the + * Place the attribute after the function declaration, just before the * semicolon. * * See the GNU C documentation for more details. * - * |[ + * |[<!-- language="C" --> * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2); * ]| */ @@ -2891,11 +3205,10 @@ /** * G_GNUC_FUNCTION: * - * Expands to "" on all modern compilers, and to - * <literal>__FUNCTION__</literal> on <command>gcc</command> version 2.x. - * Don't use it. + * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc + * version 2.x. Don't use it. * - * Deprecated: 2.16: Use #G_STRFUNC instead + * Deprecated: 2.16: Use G_STRFUNC() instead */ @@ -2909,14 +3222,14 @@ * details. * * When using a compiler that supports the GNU C hidden visibility attribute, - * this macro expands to <literal>__attribute__((visibility("hidden")))</literal>. - * When using the Sun Studio compiler, it expands to <literal>__hidden</literal>. + * this macro expands to __attribute__((visibility("hidden"))). + * When using the Sun Studio compiler, it expands to __hidden. * * Note that for portability, the attribute should be placed before the * function declaration. While GCC allows the macro after the declaration, * Sun Studio does not. * - * |[ + * |[<!-- language="C" --> * G_GNUC_INTERNAL * void _g_log_fallback_handler (const gchar *log_domain, * GLogLevelFlags log_level, @@ -2931,12 +3244,11 @@ /** * G_GNUC_MALLOC: * - * Expands to the GNU C <literal>malloc</literal> function attribute if the - * compiler is <command>gcc</command>. Declaring a function as malloc enables - * better optimization of the function. A function can have the malloc - * attribute if it returns a pointer which is guaranteed to not alias with - * any other pointer when the function returns (in practice, this means newly - * allocated memory). + * Expands to the GNU C malloc function attribute if the compiler is gcc. + * Declaring a function as malloc enables better optimization of the function. + * A function can have the malloc attribute if it returns a pointer which is + * guaranteed to not alias with any other pointer when the function returns + * (in practice, this means newly allocated memory). * * Place the attribute after the declaration, just before the semicolon. * @@ -2949,10 +3261,10 @@ /** * G_GNUC_MAY_ALIAS: * - * Expands to the GNU C <literal>may_alias</literal> type attribute - * if the compiler is <command>gcc</command>. Types with this attribute - * will not be subjected to type-based alias analysis, but are assumed - * to alias with any other type, just like char. + * Expands to the GNU C may_alias type attribute if the compiler is gcc. + * Types with this attribute will not be subjected to type-based alias + * analysis, but are assumed to alias with any other type, just like char. + * * See the GNU C documentation for details. * * Since: 2.14 @@ -2962,10 +3274,9 @@ /** * G_GNUC_NORETURN: * - * Expands to the GNU C <literal>noreturn</literal> function attribute - * if the compiler is <command>gcc</command>. It is used for declaring - * functions which never return. It enables optimization of the function, - * and avoids possible compiler warnings. + * Expands to the GNU C noreturn function attribute if the compiler is gcc. + * It is used for declaring functions which never return. It enables + * optimization of the function, and avoids possible compiler warnings. * * Place the attribute after the declaration, just before the semicolon. * @@ -2976,10 +3287,10 @@ /** * G_GNUC_NO_INSTRUMENT: * - * Expands to the GNU C <literal>no_instrument_function</literal> function - * attribute if the compiler is <command>gcc</command>. Functions with this - * attribute will not be instrumented for profiling, when the compiler is - * called with the <option>-finstrument-functions</option> option. + * Expands to the GNU C no_instrument_function function attribute if the + * compiler is gcc. Functions with this attribute will not be instrumented + * for profiling, when the compiler is called with the + * `-finstrument-functions` option. * * Place the attribute after the declaration, just before the semicolon. * @@ -2990,9 +3301,8 @@ /** * G_GNUC_NULL_TERMINATED: * - * Expands to the GNU C <literal>sentinel</literal> function attribute - * if the compiler is <command>gcc</command>, or "" if it isn't. This - * function attribute only applies to variadic functions and instructs + * Expands to the GNU C sentinel function attribute if the compiler is gcc. + * This function attribute only applies to variadic functions and instructs * the compiler to check that the argument list is terminated with an * explicit %NULL. * @@ -3007,31 +3317,30 @@ /** * G_GNUC_PRETTY_FUNCTION: * - * Expands to "" on all modern compilers, and to - * <literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command> - * version 2.x. Don't use it. + * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__ + * on gcc version 2.x. Don't use it. * - * Deprecated: 2.16: Use #G_STRFUNC instead + * Deprecated: 2.16: Use G_STRFUNC() instead */ /** * G_GNUC_PRINTF: - * @format_idx: the index of the argument corresponding to the format string (The arguments are numbered from 1) + * @format_idx: the index of the argument corresponding to the + * format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * - * Expands to the GNU C <literal>format</literal> function attribute - * if the compiler is <command>gcc</command>. This is used for declaring - * functions which take a variable number of arguments, with the same - * syntax as printf(). It allows the compiler to type-check the arguments - * passed to the function. + * Expands to the GNU C format function attribute if the compiler is gcc. + * This is used for declaring functions which take a variable number of + * arguments, with the same syntax as printf(). It allows the compiler + * to type-check the arguments passed to the function. * * Place the attribute after the function declaration, just before the * semicolon. * * See the GNU C documentation for more details. * - * |[ + * |[<!-- language="C" --> * gint g_snprintf (gchar *string, * gulong n, * gchar const *format, @@ -3043,11 +3352,11 @@ /** * G_GNUC_PURE: * - * Expands to the GNU C <literal>pure</literal> function attribute if the - * compiler is <command>gcc</command>. Declaring a function as pure enables - * better optimization of calls to the function. A pure function has no - * effects except its return value and the return value depends only on - * the parameters and/or global variables. + * Expands to the GNU C pure function attribute if the compiler is gcc. + * Declaring a function as pure enables better optimization of calls to + * the function. A pure function has no effects except its return value + * and the return value depends only on the parameters and/or global + * variables. * * Place the attribute after the declaration, just before the semicolon. * @@ -3057,30 +3366,31 @@ /** * G_GNUC_SCANF: - * @format_idx: the index of the argument corresponding to the format string (The arguments are numbered from 1) + * @format_idx: the index of the argument corresponding to + * the format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * - * Expands to the GNU C <literal>format</literal> function attribute - * if the compiler is <command>gcc</command>. This is used for declaring - * functions which take a variable number of arguments, with the same - * syntax as scanf(). It allows the compiler to type-check the arguments - * passed to the function. See the GNU C documentation for details. + * Expands to the GNU C format function attribute if the compiler is gcc. + * This is used for declaring functions which take a variable number of + * arguments, with the same syntax as scanf(). It allows the compiler + * to type-check the arguments passed to the function. + * + * See the GNU C documentation for details. */ /** * G_GNUC_UNUSED: * - * Expands to the GNU C <literal>unused</literal> function attribute if - * the compiler is <command>gcc</command>. It is used for declaring - * functions and arguments which may never be used. It avoids possible compiler - * warnings. + * Expands to the GNU C unused function attribute if the compiler is gcc. + * It is used for declaring functions and arguments which may never be used. + * It avoids possible compiler warnings. * * For functions, place the attribute after the declaration, just before the * semicolon. For arguments, place the attribute at the beginning of the * argument declaration. * - * |[ + * |[<!-- language="C" --> * void my_unused_function (G_GNUC_UNUSED gint unused_argument, * gint other_argument) G_GNUC_UNUSED; * ]| @@ -3092,10 +3402,9 @@ /** * G_GNUC_WARN_UNUSED_RESULT: * - * Expands to the GNU C <literal>warn_unused_result</literal> function - * attribute if the compiler is <command>gcc</command>, or "" if it isn't. - * This function attribute makes the compiler emit a warning if the result - * of a function call is ignored. + * Expands to the GNU C warn_unused_result function attribute if the compiler + * is gcc. This function attribute makes the compiler emit a warning if the + * result of a function call is ignored. * * Place the attribute after the declaration, just before the semicolon. * @@ -3203,14 +3512,12 @@ * This is the platform dependent conversion specifier for scanning * and printing values of type #guint64. See also #G_GINT16_FORMAT. * - * <note><para> - * Some platforms do not support scanning and printing 64 bit integers, - * even though the types are supported. On such platforms #G_GUINT64_FORMAT - * is not defined. Note that scanf() may not support 64 bit integers, even - * if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() + * Some platforms do not support scanning and printing 64-bit integers, + * even though the types are supported. On such platforms %G_GUINT64_FORMAT + * is not defined. Note that scanf() may not support 64-bit integers, even + * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() * is not recommended for parsing anyway; consider using g_ascii_strtoull() * instead. - * </para></note> */ @@ -3228,7 +3535,7 @@ * G_HOOK: * @hook: a pointer * - * Casts a pointer to a <literal>GHook*</literal>. + * Casts a pointer to a `GHook*`. */ @@ -3256,7 +3563,7 @@ * * The position of the first bit which is not reserved for internal * use be the #GHook implementation, i.e. - * <literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first + * `1 << G_HOOK_FLAG_USER_SHIFT` is the first * bit which can be used for application-defined flags. */ @@ -3311,7 +3618,7 @@ * * This macro is used to export function prototypes so they can be linked * with an external version when no inlining is performed. The file which - * implements the functions should define <literal>G_IMPLEMENTS_INLINES</literal> + * implements the functions should define %G_IMPLEMENTS_INLINES * before including the headers which contain %G_INLINE_FUNC declarations. * Since inlining is very compiler-dependent using these macros correctly * is very difficult. Their use is strongly discouraged. @@ -3332,17 +3639,6 @@ /** - * G_IO_FLAG_IS_WRITEABLE: - * - * This is 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: 2.30:Use G_IO_FLAG_IS_WRITABLE instead. - */ - - -/** * G_IS_DIR_SEPARATOR: * @c: a character * @@ -3358,8 +3654,8 @@ * G_KEY_FILE_DESKTOP_GROUP: * * The name of the main group of a desktop entry file, as defined in the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink>. Consult the specification for more + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec). + * Consult the specification for more * details about the meanings of the keys below. * * Since: 2.14 @@ -3392,7 +3688,7 @@ * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the command line to execute. It is only valid for desktop - * entries with the <literal>Application</literal> type. + * entries with the `Application` type. * * Since: 2.14 */ @@ -3486,7 +3782,7 @@ * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * containing the working directory to run the program in. It is only - * valid for desktop entries with the <literal>Application</literal> type. + * valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -3496,9 +3792,8 @@ * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean - * stating whether the application supports the <ulink - * url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup - * Notification Protocol Specification</ulink>. + * stating whether the application supports the + * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). * * Since: 2.14 */ @@ -3522,7 +3817,7 @@ * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the program should be run in a terminal window. * It is only valid for desktop entries with the - * <literal>Application</literal> type. + * `Application` type. * * Since: 2.14 */ @@ -3534,7 +3829,7 @@ * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the file name of a binary on disk used to determine if the * program is actually installed. It is only valid for desktop entries - * with the <literal>Application</literal> type. + * with the `Application` type. * * Since: 2.14 */ @@ -3558,7 +3853,7 @@ * * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the URL to access. It is only valid for desktop entries - * with the <literal>Link</literal> type. + * with the `Link` type. * * Since: 2.14 */ @@ -3622,7 +3917,7 @@ * Hints the compiler that the expression is likely to evaluate to * a true value. The compiler may use this information for optimizations. * - * |[ + * |[<!-- language="C" --> * if (G_LIKELY (random () != 1)) * g_print ("not one"); * ]| @@ -3667,19 +3962,17 @@ * G_LOCK_DEFINE: * @name: the name of the lock * - * The <literal>G_LOCK_*</literal> macros provide a convenient interface to #GMutex. + * The #G_LOCK_ macros provide a convenient interface to #GMutex. * #G_LOCK_DEFINE defines a lock. It can appear in any place where * variable definitions may appear in programs, i.e. in the first block * of a function or outside of functions. The @name parameter will be * mangled to get the name of the #GMutex. This means that you * can use names of existing variables as the parameter - e.g. the name * of the variable you intend to protect with the lock. Look at our - * <function>give_me_next_number()</function> example using the - * <literal>G_LOCK_*</literal> macros: + * give_me_next_number() example using the #G_LOCK macros: * - * <example> - * <title>Using the <literal>G_LOCK_*</literal> convenience macros</title> - * <programlisting> + * Here is an example for using the #G_LOCK convenience macros: + * |[<!-- language="C" --> * G_LOCK_DEFINE (current_number); * * int @@ -3694,8 +3987,7 @@ * * return ret_val; * } - * </programlisting> - * </example> + * ]| */ @@ -3903,7 +4195,7 @@ * The minimum positive value which can be held in a #gdouble. * * If you are interested in the smallest value which can be held - * in a #gdouble, use -G_MAXDOUBLE. + * in a #gdouble, use -%G_MAXDOUBLE. */ @@ -3913,7 +4205,7 @@ * The minimum positive value which can be held in a #gfloat. * * If you are interested in the smallest value which can be held - * in a #gfloat, use -G_MAXFLOAT. + * in a #gfloat, use -%G_MAXFLOAT. */ @@ -4004,7 +4296,7 @@ * * A #GOnce must be initialized with this macro before it can be used. * - * |[ + * |[<!-- language="C" --> * GOnce my_once = G_ONCE_INIT; * ]| * @@ -4013,18 +4305,10 @@ /** - * G_OS_BEOS: - * - * This macro is defined only on BeOS. So you can bracket - * BeOS-specific code in "#ifdef G_OS_BEOS". - */ - - -/** * G_OS_UNIX: * * This macro is defined only on UNIX. So you can bracket - * UNIX-specific code in "#ifdef G_OS_UNIX". + * UNIX-specific code in "\#ifdef G_OS_UNIX". */ @@ -4032,7 +4316,7 @@ * G_OS_WIN32: * * This macro is defined only on Windows. So you can bracket - * Windows-specific code in "#ifdef G_OS_WIN32". + * Windows-specific code in "\#ifdef G_OS_WIN32". */ @@ -4042,10 +4326,10 @@ * @identifier2: an identifier * * Yields a new preprocessor pasted identifier - * <code>identifier1identifier2</code> from its expanded + * @identifier1identifier2 from its expanded * arguments @identifier1 and @identifier2. For example, * the following code: - * |[ + * |[<!-- language="C" --> * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) * const gchar *name = GET (traveller, name); * const gchar *quest = GET (traveller, quest); @@ -4053,7 +4337,7 @@ * ]| * * is transformed by the preprocessor into: - * |[ + * |[<!-- language="C" --> * const gchar *name = traveller_get_name (traveller); * const gchar *quest = traveller_get_quest (traveller); * GdkColor *favourite = traveller_get_favourite_colour (traveller); @@ -4111,7 +4395,7 @@ * be properly initialised by default (ie: to all zeros). See the * examples below. * - * |[ + * |[<!-- language="C" --> * static GPrivate name_key = G_PRIVATE_INIT (g_free); * * // return value should not be freed @@ -4183,18 +4467,14 @@ * G_STATIC_ASSERT: * @expr: a constant expression * - * The G_STATIC_ASSERT macro lets the programmer check + * The G_STATIC_ASSERT() macro lets the programmer check * a condition at compile time, the condition needs to * be compile time computable. The macro can be used in - * any place where a <literal>typedef</literal> is valid. + * any place where a typedef is valid. * - * <note><para> - * A <literal>typedef</literal> is generally allowed in - * exactly the same places that a variable declaration is - * allowed. For this reason, you should not use - * <literal>G_STATIC_ASSERT</literal> in the middle of - * blocks of code. - * </para></note> + * A typedef is generally allowed in exactly the same places that + * a variable declaration is allowed. For this reason, you should + * not use G_STATIC_ASSERT() in the middle of blocks of code. * * The macro should only be used once per source code line. * @@ -4206,17 +4486,16 @@ * G_STATIC_ASSERT_EXPR: * @expr: a constant expression * - * The G_STATIC_ASSERT_EXPR macro lets the programmer check + * The G_STATIC_ASSERT_EXPR() macro lets the programmer check * a condition at compile time. The condition needs to be * compile time computable. * - * Unlike <literal>G_STATIC_ASSERT</literal>, this macro - * evaluates to an expression and, as such, can be used in - * the middle of other expressions. Its value should be - * ignored. This can be accomplished by placing it as - * the first argument of a comma expression. + * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression + * and, as such, can be used in the middle of other expressions. + * Its value should be ignored. This can be accomplished by placing + * it as the first argument of a comma expression. * - * |[ + * |[<!-- language="C" --> * #define ADD_ONE_TO_INT(x) \ * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) * ]| @@ -4257,14 +4536,14 @@ * Accepts a macro or a string and converts it into a string after * preprocessor argument expansion. For example, the following code: * - * |[ + * |[<!-- language="C" --> * #define AGE 27 * const gchar *greeting = G_STRINGIFY (AGE) " today!"; * ]| * * is transformed by the preprocessor into (code equivalent to): * - * |[ + * |[<!-- language="C" --> * const gchar *greeting = "27 today!"; * ]| */ @@ -4281,7 +4560,8 @@ * G_STRUCT_MEMBER: * @member_type: the type of the struct field * @struct_p: a pointer to a struct - * @struct_offset: the offset of the field from the start of the struct, in bytes + * @struct_offset: the offset of the field from the start of the struct, + * in bytes * * Returns a member of a structure at a given offset, using the given type. * @@ -4302,8 +4582,8 @@ /** * G_STRUCT_OFFSET: - * @struct_type: a structure type, e.g. <structname>GtkWidget</structname> - * @member: a field in the structure, e.g. <structfield>window</structfield> + * @struct_type: a structure type, e.g. #GtkWidget + * @member: a field in the structure, e.g. @window * * Returns the offset, in bytes, of a member of a struct. * @@ -4356,7 +4636,7 @@ * Hints the compiler that the expression is unlikely to evaluate to * a true value. The compiler may use this information for optimizations. * - * |[ + * |[<!-- language="C" --> * if (G_UNLIKELY (random () == 1)) * g_print ("a random one"); * ]| @@ -4394,22 +4674,24 @@ /** * G_VA_COPY: - * @ap1: the <type>va_list</type> variable to place a copy of @ap2 in - * @ap2: a <type>va_list</type> + * @ap1: the va_list variable to place a copy of @ap2 in + * @ap2: a va_list * - * Portable way to copy <type>va_list</type> variables. + * Portable way to copy va_list variables. * - * In order to use this function, you must include - * <filename>string.h</filename> yourself, because this macro may - * use memmove() and GLib does not include <filename>string.h</filename> - * for you. + * In order to use this function, you must include string.h yourself, + * because this macro may use memmove() and GLib does not include + * string.h for you. */ /** * G_WIN32_DLLMAIN_FOR_DLL_NAME: * @static: empty or "static" - * @dll_name: the name of the (pointer to the) char array where the DLL name will be stored. If this is used, you must also include <filename>windows.h</filename>. If you need a more complex DLL entry point function, you cannot use this + * @dll_name: the name of the (pointer to the) char array where + * the DLL name will be stored. If this is used, you must also + * include `windows.h`. If you need a more complex DLL entry + * point function, you cannot use this * * On Windows, this macro defines a DllMain() function that stores * the actual DLL name that the code being compiled will be included in. @@ -4486,7 +4768,7 @@ * be directly used, e.g. in string array initializers. To get the * translated string, you should call g_dpgettext2() at runtime. * - * |[ + * |[<!-- language="C" --> * { * static const char *messages[] = { * NC_("some context", "some very meaningful message"), @@ -4495,19 +4777,18 @@ * const char *string; * ... * string - * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") - * : g_dpgettext2 (NULL, "some context", messages[index]); + * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message") + * : g_dpgettext2 (NULL, "some context", messages[index]); * * fputs (string); * ... * } * ]| * - * <note><para>If you are using the NC_() macro, you need to make sure - * that you pass <option>--keyword=NC_:1c,2</option> to xgettext when - * extracting messages. Note that this only works with GNU gettext >= 0.15. - * Intltool has support for the NC_() macro since version 0.40.1. - * </para></note> + * If you are using the NC_() macro, you need to make sure that you pass + * `--keyword=NC_:1c,2` to xgettext when extracting messages. + * Note that this only works with GNU gettext >= 0.15. Intltool has support + * for the NC_() macro since version 0.40.1. * * Since: 2.18 */ @@ -4528,7 +4809,7 @@ * where the translated strings can't be directly used, e.g. in string * array initializers. To get the translated string, call gettext() * at runtime. - * |[ + * |[<!-- language="C" --> * { * static const char *messages[] = { * N_("some very meaningful message"), @@ -4550,7 +4831,8 @@ /** * Q_: - * @String: the string to be translated, with a '|'-separated prefix which must not be translated + * @String: the string to be translated, with a '|'-separated prefix + * which must not be translated * * Like _(), but handles context in message ids. This has the advantage * that the string can be adorned with a prefix to guarantee uniqueness @@ -4566,11 +4848,11 @@ * See the C_() macro for a different way to mark up translatable strings * with context. * - * <note><para>If you are using the Q_() macro, you need to make sure - * that you pass <option>--keyword=Q_</option> to xgettext when extracting - * messages. If you are using GNU gettext >= 0.15, you can also use - * <option>--keyword=Q_:1g</option> to let xgettext split the context - * string off into a msgctxt line in the po file.</para></note> + * If you are using the Q_() macro, you need to make sure that you pass + * `--keyword=Q_` to xgettext when extracting messages. + * If you are using GNU gettext >= 0.15, you can also use + * `--keyword=Q_:1g` to let xgettext split the context + * string off into a msgctxt line in the po file. * * Returns: the translated message * Since: 2.4 @@ -4580,7 +4862,8 @@ /** * SECTION:arrays * @title: Arrays - * @short_description: arrays of arbitrary elements which grow automatically as elements are added + * @short_description: arrays of arbitrary elements which grow + * automatically as elements are added * * Arrays are similar to standard C arrays, except that they grow * automatically as elements are added. @@ -4601,23 +4884,21 @@ * * To free an array, use g_array_free(). * - * <example> - * <title>Using a #GArray to store #gint values</title> - * <programlisting> + * Here is an example that stores integers in a #GArray: + * |[<!-- language="C" --> * GArray *garray; * gint i; - * /<!-- -->* We create a new array to store gint values. - * We don't want it zero-terminated or cleared to 0's. *<!-- -->/ + * // We create a new array to store gint values. + * // We don't want it zero-terminated or cleared to 0's. * garray = g_array_new (FALSE, FALSE, sizeof (gint)); - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * g_array_append_val (garray, i); - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * if (g_array_index (garray, gint, i) != i) - * g_print ("ERROR: got %d instead of %d\n", + * g_print ("ERROR: got %d instead of %d\n", * g_array_index (garray, gint, i), i); * g_array_free (garray, TRUE); - * </programlisting> - * </example> + * ]| */ @@ -4636,17 +4917,16 @@ * * To free a #GByteArray, use g_byte_array_free(). * - * <example> - * <title>Using a #GByteArray</title> - * <programlisting> + * An example for using a #GByteArray: + * |[<!-- language="C" --> * GByteArray *gbarray; * gint i; * - * gbarray = g_byte_array_new (<!-- -->); - * for (i = 0; i < 10000; i++) + * gbarray = g_byte_array_new (); + * for (i = 0; i < 10000; i++) * g_byte_array_append (gbarray, (guint8*) "abcd", 4); * - * for (i = 0; i < 10000; i++) + * for (i = 0; i < 10000; i++) * { * g_assert (gbarray->data[4*i] == 'a'); * g_assert (gbarray->data[4*i+1] == 'b'); @@ -4655,8 +4935,7 @@ * } * * g_byte_array_free (gbarray, TRUE); - * </programlisting> - * </example> + * ]| * * See #GBytes if you are interested in an immutable object representing a * sequence of bytes. @@ -4666,16 +4945,17 @@ /** * SECTION:arrays_pointer * @title: Pointer Arrays - * @short_description: arrays of pointers to any type of data, which grow automatically as new elements are added + * @short_description: arrays of pointers to any type of data, which + * grow automatically as new elements are added * * Pointer Arrays are similar to Arrays but are used only for storing * pointers. * - * <note><para>If you remove elements from the array, elements at the - * end of the array are moved into the space previously occupied by the - * removed element. This means that you should not rely on the index of - * particular elements remaining the same. You should also be careful - * when deleting elements while iterating over the array.</para></note> + * If you remove elements from the array, elements at the end of the + * array are moved into the space previously occupied by the removed + * element. This means that you should not rely on the index of particular + * elements remaining the same. You should also be careful when deleting + * elements while iterating over the array. * * To create a pointer array, use g_ptr_array_new(). * @@ -4690,24 +4970,22 @@ * * To free a pointer array, use g_ptr_array_free(). * - * <example> - * <title>Using a #GPtrArray</title> - * <programlisting> - * GPtrArray *gparray; + * An example using a #GPtrArray: + * |[<!-- language="C" --> + * GPtrArray *array; * gchar *string1 = "one", *string2 = "two", *string3 = "three"; * - * gparray = g_ptr_array_new (<!-- -->); - * g_ptr_array_add (gparray, (gpointer) string1); - * g_ptr_array_add (gparray, (gpointer) string2); - * g_ptr_array_add (gparray, (gpointer) string3); + * gparray = g_ptr_array_new (); + * g_ptr_array_add (array, (gpointer) string1); + * g_ptr_array_add (array, (gpointer) string2); + * g_ptr_array_add (array, (gpointer) string3); * - * if (g_ptr_array_index (gparray, 0) != (gpointer) string1) - * g_print ("ERROR: got %p instead of %p\n", - * g_ptr_array_index (gparray, 0), string1); + * if (g_ptr_array_index (array, 0) != (gpointer) string1) + * g_print ("ERROR: got %p instead of %p\n", + * g_ptr_array_index (array, 0), string1); * - * g_ptr_array_free (gparray, TRUE); - * </programlisting> - * </example> + * g_ptr_array_free (array, TRUE); + * ]| */ @@ -4798,8 +5076,7 @@ * fall outside of simple reference counting patterns are prone to * subtle bugs and occasionally undefined behaviour. It is also worth * noting that since all of these operations require global - * synchronisation of the entire machine, they can be quite slow. In - * the case of performing multiple atomic operations it can often be + * synchronisation of the entire machine, they can be quite slow. In * the case of performing multiple atomic operations it can often be * faster to simply acquire a mutex lock around the critical area, * perform the operations normally and then release the lock. */ @@ -4812,9 +5089,11 @@ * * Base64 is an encoding that allows a sequence of arbitrary bytes to be * encoded as a sequence of printable ASCII characters. For the definition - * of Base64, see <ulink url="http://www.ietf.org/rfc/rfc1421.txt">RFC - * 1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt">RFC - * 2045</ulink>. Base64 is most commonly used as a MIME transfer encoding + * of Base64, see + * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) + * or + * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). + * Base64 is most commonly used as a MIME transfer encoding * for email. * * GLib supports incremental encoding using g_base64_encode_step() and @@ -4837,26 +5116,27 @@ * like its MIME type, the application that is registering the bookmark and * the icon that should be used to represent the bookmark. The data is stored * using the - * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark - * Specification</ulink>. + * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). * - * The syntax of the bookmark files is described in detail inside the Desktop - * Bookmark Specification, here is a quick summary: bookmark files use a - * sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink> + * The syntax of the bookmark files is described in detail inside the + * Desktop Bookmark Specification, here is a quick summary: bookmark + * files use a sub-class of the XML Bookmark Exchange Language * specification, consisting of valid UTF-8 encoded XML, under the - * <literal>xbel</literal> root element; each bookmark is stored inside a - * <literal>bookmark</literal> element, using its URI: no relative paths can - * be used inside a bookmark file. The bookmark may have a user defined title - * and description, to be used instead of the URI. Under the - * <literal>metadata</literal> element, with its <literal>owner</literal> - * attribute set to <literal>http://freedesktop.org</literal>, is stored the - * meta-data about a resource pointed by its URI. The meta-data consists of - * the resource's MIME type; the applications that have registered a bookmark; - * the groups to which a bookmark belongs to; a visibility flag, used to set - * the bookmark as "private" to the applications and groups that has it - * registered; the URI and MIME type of an icon, to be used when displaying - * the bookmark inside a GUI. - * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]| + * <xbel> root element; each bookmark is stored inside a + * <bookmark> element, using its URI: no relative paths can + * be used inside a bookmark file. The bookmark may have a user defined + * title and description, to be used instead of the URI. Under the + * <metadata> element, with its owner attribute set to + * `http://freedesktop.org`, is stored the meta-data about a resource + * pointed by its URI. The meta-data consists of the resource's MIME + * type; the applications that have registered a bookmark; the groups + * to which a bookmark belongs to; a visibility flag, used to set the + * bookmark as "private" to the applications and groups that has it + * registered; the URI and MIME type of an icon, to be used when + * displaying the bookmark inside a GUI. + * + * Here is an example of a bookmark file: + * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel) * * A bookmark file might contain more than one bookmark; each bookmark * is accessed through its URI. @@ -4936,127 +5216,107 @@ * @title: Character Set Conversion * @short_description: convert strings between different character sets * - * The g_convert() family of function wraps the functionality of iconv(). In - * addition to pure character set conversions, GLib has functions to deal - * with the extra complications of encodings for file names. - * - * <refsect2 id="file-name-encodings"> - * <title>File Name Encodings</title> - * <para> - * Historically, Unix has not had a defined encoding for file - * names: a file name is valid as long as it does not have path - * separators in it ("/"). However, displaying file names may - * require conversion: from the character set in which they were - * created, to the character set in which the application - * operates. Consider the Spanish file name - * "<filename>Presentación.sxi</filename>". If the - * application which created it uses ISO-8859-1 for its encoding, - * </para> - * <programlisting id="filename-iso8859-1"> + * The g_convert() family of function wraps the functionality of iconv(). + * In addition to pure character set conversions, GLib has functions to + * deal with the extra complications of encodings for file names. + * + * ## File Name Encodings + * + * Historically, UNIX has not had a defined encoding for file names: + * a file name is valid as long as it does not have path separators + * in it ("/"). However, displaying file names may require conversion: + * from the character set in which they were created, to the character + * set in which the application operates. Consider the Spanish file name + * "Presentación.sxi". If the application which created it uses + * ISO-8859-1 for its encoding, + * |[ * Character: P r e s e n t a c i ó n . s x i * Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 - * </programlisting> - * <para> + * ]| * However, if the application use UTF-8, the actual file name on * disk would look like this: - * </para> - * <programlisting id="filename-utf-8"> + * |[ * Character: P r e s e n t a c i ó n . s x i * Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 - * </programlisting> - * <para> - * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ - * that use Glib do the same thing. If you get a file name from - * the file system, for example, from readdir(3) or from g_dir_read_name(), - * and you wish to display the file name to the user, you - * <emphasis>will</emphasis> need to convert it into UTF-8. The - * opposite case is when the user types the name of a file he - * wishes to save: the toolkit will give you that string in - * UTF-8 encoding, and you will need to convert it to the - * character set used for file names before you can create the - * file with open(2) or fopen(3). - * </para> - * <para> + * ]| + * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use + * Glib do the same thing. If you get a file name from the file system, + * for example, from readdir() or from g_dir_read_name(), and you wish + * to display the file name to the user, you will need to convert it + * into UTF-8. The opposite case is when the user types the name of a + * file he wishes to save: the toolkit will give you that string in + * UTF-8 encoding, and you will need to convert it to the character + * set used for file names before you can create the file with open() + * or fopen(). + * * By default, Glib assumes that file names on disk are in UTF-8 - * encoding. This is a valid assumption for file systems which - * were created relatively recently: most applications use UTF-8 + * encoding. This is a valid assumption for file systems which + * were created relatively recently: most applications use UTF-8 * encoding for their strings, and that is also what they use for - * the file names they create. However, older file systems may + * the file names they create. However, older file systems may * still contain file names created in "older" encodings, such as - * ISO-8859-1. In this case, for compatibility reasons, you may - * want to instruct Glib to use that particular encoding for file - * names rather than UTF-8. You can do this by specifying the - * encoding for file names in the <link - * linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link> - * environment variable. For example, if your installation uses - * ISO-8859-1 for file names, you can put this in your - * <filename>~/.profile</filename>: - * </para> - * <programlisting> + * ISO-8859-1. In this case, for compatibility reasons, you may want + * to instruct Glib to use that particular encoding for file names + * rather than UTF-8. You can do this by specifying the encoding for + * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] + * environment variable. For example, if your installation uses + * ISO-8859-1 for file names, you can put this in your `~/.profile` + * |[ * export G_FILENAME_ENCODING=ISO-8859-1 - * </programlisting> - * <para> + * ]| * Glib provides the functions g_filename_to_utf8() and - * g_filename_from_utf8() to perform the necessary conversions. These - * functions convert file names from the encoding specified in - * <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa. - * <xref linkend="file-name-encodings-diagram"/> illustrates how + * g_filename_from_utf8() to perform the necessary conversions. + * These functions convert file names from the encoding specified + * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This + * [diagram][file-name-encodings-diagram] illustrates how * these functions are used to convert between UTF-8 and the * encoding for file names in the file system. - * </para> - * <figure id="file-name-encodings-diagram"> - * <title>Conversion between File Name Encodings</title> - * <graphic fileref="file-name-encodings.png" format="PNG"/> - * </figure> - * <refsect3 id="file-name-encodings-checklist"> - * <title>Checklist for Application Writers</title> - * <para> + * + * ## Conversion between file name encodings # {#file-name-encodings-diagram) + * + *  + * + * ## Checklist for Application Writers + * * This section is a practical summary of the detailed - * description above. You can use this as a checklist of + * * things to do to make sure your applications process file * name encodings correctly. - * </para> - * <orderedlist> - * <listitem><para> - * If you get a file name from the file system from a function - * such as readdir(3) or gtk_file_chooser_get_filename(), - * you do not need to do any conversion to pass that - * file name to functions like open(2), rename(2), or - * fopen(3) — those are "raw" file names which the file - * system understands. - * </para></listitem> - * <listitem><para> - * If you need to display a file name, convert it to UTF-8 first by - * using g_filename_to_utf8(). If conversion fails, display a string like - * "<literal>Unknown file name</literal>". <emphasis>Do not</emphasis> - * convert this string back into the encoding used for file names if you - * wish to pass it to the file system; use the original file name instead. - * For example, the document window of a word processor could display - * "Unknown file name" in its title bar but still let the user save the - * file, as it would keep the raw file name internally. This can happen - * if the user has not set the <envar>G_FILENAME_ENCODING</envar> - * environment variable even though he has files whose names are not - * encoded in UTF-8. - * </para></listitem> - * <listitem><para> - * If your user interface lets the user type a file name for saving or - * renaming, convert it to the encoding used for file names in the file - * system by using g_filename_from_utf8(). Pass the converted file name - * to functions like fopen(3). If conversion fails, ask the user to enter - * a different file name. This can happen if the user types Japanese - * characters when <envar>G_FILENAME_ENCODING</envar> is set to - * <literal>ISO-8859-1</literal>, for example. - * </para></listitem> - * </orderedlist> - * </refsect3> - * </refsect2> + * + * 1. If you get a file name from the file system from a function + * such as readdir() or gtk_file_chooser_get_filename(), you do + * not need to do any conversion to pass that file name to + * functions like open(), rename(), or fopen() -- those are "raw" + * file names which the file system understands. + * + * 2. If you need to display a file name, convert it to UTF-8 first + * by using g_filename_to_utf8(). If conversion fails, display a + * string like "Unknown file name". Do not convert this string back + * into the encoding used for file names if you wish to pass it to + * the file system; use the original file name instead. + * + * For example, the document window of a word processor could display + * "Unknown file name" in its title bar but still let the user save + * the file, as it would keep the raw file name internally. This + * can happen if the user has not set the `G_FILENAME_ENCODING` + * environment variable even though he has files whose names are + * not encoded in UTF-8. + * + * 3. If your user interface lets the user type a file name for saving + * or renaming, convert it to the encoding used for file names in + * the file system by using g_filename_from_utf8(). Pass the converted + * file name to functions like fopen(). If conversion fails, ask the + * user to enter a different file name. This can happen if the user + * types Japanese characters when `G_FILENAME_ENCODING` is set to + * `ISO-8859-1`, for example. */ /** * SECTION:datalist * @title: Keyed Data Lists - * @short_description: lists of data elements which are accessible by a string or GQuark identifier + * @short_description: lists of data elements which are accessible by a + * string or GQuark identifier * * Keyed data lists provide lists of arbitrary data elements which can * be accessed either with a string or with a #GQuark corresponding to @@ -5090,7 +5350,8 @@ /** * SECTION:datasets * @title: Datasets - * @short_description: associate groups of data elements with particular memory locations + * @short_description: associate groups of data elements with + * particular memory locations * * Datasets associate groups of data elements with particular memory * locations. These are useful if you need to associate data with a @@ -5139,7 +5400,7 @@ * or ISO timestamps or the like. It extrapolates the current Gregorian * calendar forward and backward in time; there is no attempt to change * the calendar to match time periods or locations. #GDate does not store - * time information; it represents a <emphasis>day</emphasis>. + * time information; it represents a day. * * The #GDate implementation has several nice features; it is only a * 64-bit struct, so storing large numbers of dates is very efficient. It @@ -5157,16 +5418,16 @@ * calling g_date_clear(). A cleared date is sane; it's safe to call * g_date_set_dmy() and the other mutator functions to initialize the * value of a cleared date. However, a cleared date is initially - * <emphasis>invalid</emphasis>, meaning that it doesn't represent a day - * that exists. It is undefined to call any of the date calculation - * routines on an invalid date. If you obtain a date from a user or other + * invalid, meaning that it doesn't represent a day that exists. + * It is undefined to call any of the date calculation routines on an + * invalid date. If you obtain a date from a user or other * unpredictable source, you should check its validity with the * g_date_valid() predicate. g_date_valid() is also used to check for * errors with g_date_set_parse() and other functions that can * fail. Dates can be invalidated by calling g_date_clear() again. * - * <emphasis>It is very important to use the API to access the #GDate - * struct.</emphasis> Often only the day-month-year or only the Julian + * It is very important to use the API to access the #GDate + * struct. Often only the day-month-year or only the Julian * representation is valid. Sometimes neither is valid. Use the API. * * GLib also features #GDateTime which represents a precise time. @@ -5215,18 +5476,18 @@ * GLib provides a standard method of reporting errors from a called * function to the calling code. (This is the same problem solved by * exceptions in other languages.) It's important to understand that - * this method is both a <emphasis>data type</emphasis> (the #GError - * object) and a <emphasis>set of rules.</emphasis> If you use #GError - * incorrectly, then your code will not properly interoperate with other - * code that uses #GError, and users of your API will probably get confused. - * - * First and foremost: <emphasis>#GError should only be used to report - * recoverable runtime errors, never to report programming - * errors.</emphasis> If the programmer has screwed up, then you should - * use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some - * similar facility. (Incidentally, remember that the g_error() function - * should <emphasis>only</emphasis> be used for programming errors, it - * should not be used to print any error reportable via #GError.) + * this method is both a data type (the #GError struct) and a set of + * rules. If you use #GError incorrectly, then your code will not + * properly interoperate with other code that uses #GError, and users + * of your API will probably get confused. + * + * First and foremost: #GError should only be used to report recoverable + * runtime errors, never to report programming errors. If the programmer + * has screwed up, then you should use g_warning(), g_return_if_fail(), + * g_assert(), g_error(), or some similar facility. (Incidentally, + * remember that the g_error() function should only be used for + * programming errors, it should not be used to print any error + * reportable via #GError.) * * Examples of recoverable runtime errors are "file not found" or * "failed to parse input." Examples of programming errors are "NULL @@ -5238,71 +5499,70 @@ * * Functions that can fail take a return location for a #GError as their * last argument. For example: - * |[ + * |[<!-- language="C" --> * gboolean g_file_get_contents (const gchar *filename, * gchar **contents, * gsize *length, * GError **error); * ]| - * If you pass a non-%NULL value for the <literal>error</literal> - * argument, it should point to a location where an error can be placed. - * For example: - * |[ + * If you pass a non-%NULL value for the `error` argument, it should + * point to a location where an error can be placed. For example: + * |[<!-- language="C" --> * gchar *contents; * GError *err = NULL; - * g_file_get_contents ("foo.txt", &contents, NULL, &err); - * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); + * + * g_file_get_contents ("foo.txt", &contents, NULL, &err); + * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); * if (err != NULL) * { - * /* Report error to user, and free error */ + * // Report error to user, and free error * g_assert (contents == NULL); - * fprintf (stderr, "Unable to read file: %s\n", err->message); + * fprintf (stderr, "Unable to read file: %s\n", err->message); * g_error_free (err); * } * else * { - * /* Use file contents */ + * // Use file contents * g_assert (contents != NULL); * } * ]| - * Note that <literal>err != NULL</literal> in this example is a - * <emphasis>reliable</emphasis> indicator of whether - * g_file_get_contents() failed. Additionally, g_file_get_contents() - * returns a boolean which indicates whether it was successful. + * Note that `err != NULL` in this example is a reliable indicator + * of whether g_file_get_contents() failed. Additionally, + * g_file_get_contents() returns a boolean which + * indicates whether it was successful. * * Because g_file_get_contents() returns %FALSE on failure, if you * are only interested in whether it failed and don't need to display - * an error message, you can pass %NULL for the <literal>error</literal> - * argument: - * |[ - * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ - * /* no error occurred */ ; + * an error message, you can pass %NULL for the @error argument: + * |[<!-- language="C" --> + * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors + * // no error occurred + * ; * else - * /* error */ ; + * // error + * ; * ]| * - * The #GError object contains three fields: <literal>domain</literal> - * indicates the module the error-reporting function is located in, - * <literal>code</literal> indicates the specific error that occurred, - * and <literal>message</literal> is a user-readable error message with + * The #GError object contains three fields: @domain indicates the module + * the error-reporting function is located in, @code indicates the specific + * error that occurred, and @message is a user-readable error message with * as many details as possible. Several functions are provided to deal * with an error received from a called function: g_error_matches() * returns %TRUE if the error matches a given domain and code, * g_propagate_error() copies an error into an error location (so the * calling function will receive it), and g_clear_error() clears an * error location by freeing the error and resetting the location to - * %NULL. To display an error to the user, simply display - * <literal>error->message</literal>, perhaps along with additional - * context known only to the calling function (the file being opened, - * or whatever -- though in the g_file_get_contents() case, - * <literal>error->message</literal> already contains a filename). + * %NULL. To display an error to the user, simply display the @message, + * perhaps along with additional context known only to the calling + * function (the file being opened, or whatever - though in the + * g_file_get_contents() case, the @message already contains a filename). * * When implementing a function that can report errors, the basic * tool is g_set_error(). Typically, if a fatal error occurs you * want to g_set_error(), then return immediately. g_set_error() * does nothing if the error location passed to it is %NULL. * Here's an example: - * |[ + * |[<!-- language="C" --> * gint * foo_open_file (GError **error) * { @@ -5310,12 +5570,12 @@ * * fd = open ("file.txt", O_RDONLY); * - * if (fd < 0) + * if (fd < 0) * { * g_set_error (error, - * FOO_ERROR, /* error domain */ - * FOO_ERROR_BLAH, /* error code */ - * "Failed to open file: %s", /* error message format string */ + * FOO_ERROR, // error domain + * FOO_ERROR_BLAH, // error code + * "Failed to open file: %s", // error message format string * g_strerror (errno)); * return -1; * } @@ -5328,7 +5588,7 @@ * function that can report a #GError. If the sub-function indicates * fatal errors in some way other than reporting a #GError, such as * by returning %TRUE on success, you can simply do the following: - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5336,12 +5596,12 @@ * * if (!sub_function_that_can_fail (err)) * { - * /* assert that error was set by the sub-function */ + * // assert that error was set by the sub-function * g_assert (err == NULL || *err != NULL); * return FALSE; * } * - * /* otherwise continue, no error occurred */ + * // otherwise continue, no error occurred * g_assert (err == NULL || *err == NULL); * } * ]| @@ -5350,7 +5610,7 @@ * reporting a #GError, you need to create a temporary #GError * since the passed-in one may be %NULL. g_propagate_error() is * intended for use in this case. - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5359,23 +5619,22 @@ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * tmp_error = NULL; - * sub_function_that_can_fail (&tmp_error); + * sub_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { - * /* store tmp_error in err, if err != NULL, - * * otherwise call g_error_free() on tmp_error - * */ + * // store tmp_error in err, if err != NULL, + * // otherwise call g_error_free() on tmp_error * g_propagate_error (err, tmp_error); * return FALSE; * } * - * /* otherwise continue, no error occurred */ + * // otherwise continue, no error occurred * } * ]| * * Error pileups are always a bug. For example, this code is incorrect: - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5384,8 +5643,8 @@ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * * tmp_error = NULL; - * sub_function_that_can_fail (&tmp_error); - * other_function_that_can_fail (&tmp_error); + * sub_function_that_can_fail (&tmp_error); + * other_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { @@ -5394,15 +5653,15 @@ * } * } * ]| - * <literal>tmp_error</literal> should be checked immediately after - * sub_function_that_can_fail(), and either cleared or propagated - * upward. The rule is: <emphasis>after each error, you must either - * handle the error, or return it to the calling function</emphasis>. + * @tmp_error should be checked immediately after sub_function_that_can_fail(), + * and either cleared or propagated upward. The rule is: after each error, + * you must either handle the error, or return it to the calling function. + * * Note that passing %NULL for the error location is the equivalent * of handling an error by always doing nothing about it. So the * following code is fine, assuming errors in sub_function_that_can_fail() * are not fatal to my_function_that_can_fail(): - * |[ + * |[<!-- language="C" --> * gboolean * my_function_that_can_fail (GError **err) * { @@ -5410,10 +5669,10 @@ * * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * - * sub_function_that_can_fail (NULL); /* ignore errors */ + * sub_function_that_can_fail (NULL); // ignore errors * * tmp_error = NULL; - * other_function_that_can_fail (&tmp_error); + * other_function_that_can_fail (&tmp_error); * * if (tmp_error != NULL) * { @@ -5423,116 +5682,107 @@ * } * ]| * - * Note that passing %NULL for the error location - * <emphasis>ignores</emphasis> errors; it's equivalent to - * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal> - * in C++. It does <emphasis>not</emphasis> mean to leave errors - * unhandled; it means to handle them by doing nothing. + * Note that passing %NULL for the error location ignores errors; + * it's equivalent to + * `try { sub_function_that_can_fail (); } catch (...) {}` + * in C++. It does not mean to leave errors unhandled; it means + * to handle them by doing nothing. * * Error domains and codes are conventionally named as follows: - * <itemizedlist> - * <listitem><para> - * The error domain is called - * <literal><NAMESPACE>_<MODULE>_ERROR</literal>, + * + * - The error domain is called <NAMESPACE>_<MODULE>_ERROR, * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - * |[ - * #define G_SPAWN_ERROR g_spawn_error_quark () + * |[<!-- language="C" --> + * #define G_SPAWN_ERROR g_spawn_error_quark () * - * GQuark - * g_spawn_error_quark (void) - * { - * return g_quark_from_static_string ("g-spawn-error-quark"); - * } + * GQuark + * g_spawn_error_quark (void) + * { + * return g_quark_from_static_string ("g-spawn-error-quark"); + * } * ]| - * </para></listitem> - * <listitem><para> - * The quark function for the error domain is called - * <literal><namespace>_<module>_error_quark</literal>, + * + * - The quark function for the error domain is called + * <namespace>_<module>_error_quark, * for example g_spawn_error_quark() or g_thread_error_quark(). - * </para></listitem> - * <listitem><para> - * The error codes are in an enumeration called - * <literal><Namespace><Module>Error</literal>; - * for example,#GThreadError or #GSpawnError. - * </para></listitem> - * <listitem><para> - * Members of the error code enumeration are called - * <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>, + * + * - The error codes are in an enumeration called + * <Namespace><Module>Error; + * for example, #GThreadError or #GSpawnError. + * + * - Members of the error code enumeration are called + * <NAMESPACE>_<MODULE>_ERROR_<CODE>, * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. - * </para></listitem> - * <listitem><para> - * If there's a "generic" or "unknown" error code for unrecoverable + * + * - If there's a "generic" or "unknown" error code for unrecoverable * errors it doesn't make sense to distinguish with specific codes, - * it should be called <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>, + * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, * for example %G_SPAWN_ERROR_FAILED. - * </para></listitem> - * </itemizedlist> * * Summary of rules for use of #GError: - * <itemizedlist> - * <listitem><para> - * Do not report programming errors via #GError. - * </para></listitem> - * <listitem><para> - * The last argument of a function that returns an error should + * + * - Do not report programming errors via #GError. + * + * - The last argument of a function that returns an error should * be a location where a #GError can be placed (i.e. "#GError** error"). * If #GError is used with varargs, the #GError** should be the last * argument before the "...". - * </para></listitem> - * <listitem><para> - * The caller may pass %NULL for the #GError** if they are not interested + * + * - The caller may pass %NULL for the #GError** if they are not interested * in details of the exact error that occurred. - * </para></listitem> - * <listitem><para> - * If %NULL is passed for the #GError** argument, then errors should + * + * - If %NULL is passed for the #GError** argument, then errors should * not be returned to the caller, but your function should still * abort and return if an error occurs. That is, control flow should * not be affected by whether the caller wants to get a #GError. - * </para></listitem> - * <listitem><para> - * If a #GError is reported, then your function by definition - * <emphasis>had a fatal failure and did not complete whatever - * it was supposed to do</emphasis>. If the failure was not fatal, - * then you handled it and you should not report it. If it was fatal, - * then you must report it and discontinue whatever you were doing - * immediately. - * </para></listitem> - * <listitem><para> - * If a #GError is reported, out parameters are not guaranteed to + * + * - If a #GError is reported, then your function by definition had a + * fatal failure and did not complete whatever it was supposed to do. + * If the failure was not fatal, then you handled it and you should not + * report it. If it was fatal, then you must report it and discontinue + * whatever you were doing immediately. + * + * - If a #GError is reported, out parameters are not guaranteed to * be set to any defined value. - * </para></listitem> - * <listitem><para> - * A #GError* must be initialized to %NULL before passing its address + * + * - A #GError* must be initialized to %NULL before passing its address * to a function that can report errors. - * </para></listitem> - * <listitem><para> - * "Piling up" errors is always a bug. That is, if you assign a + * + * - "Piling up" errors is always a bug. That is, if you assign a * new #GError to a #GError* that is non-%NULL, thus overwriting * the previous error, it indicates that you should have aborted * the operation instead of continuing. If you were able to continue, * you should have cleared the previous error with g_clear_error(). * g_set_error() will complain if you pile up errors. - * </para></listitem> - * <listitem><para> - * By convention, if you return a boolean value indicating success - * then %TRUE means success and %FALSE means failure. If %FALSE is - * returned, the error <emphasis>must</emphasis> be set to a non-%NULL - * value. - * </para></listitem> - * <listitem><para> - * A %NULL return value is also frequently used to mean that an error + * + * - By convention, if you return a boolean value indicating success + * then %TRUE means success and %FALSE means failure. + * <footnote><para>Avoid creating functions which have a boolean + * return value and a GError parameter, but where the boolean does + * something other than signal whether the GError is set. Among other + * problems, it requires C callers to allocate a temporary error. Instead, + * provide a "gboolean *" out parameter. There are functions in GLib + * itself such as g_key_file_has_key() that are deprecated because of this. + * </para></footnote> + * If %FALSE is + * returned, the error must be set to a non-%NULL value. + * <footnote><para>One exception to this is that in situations that are + * already considered to be undefined behaviour (such as when a + * g_return_val_if_fail() check fails), the error need not be set. + * Instead of checking separately whether the error is set, callers + * should ensure that they do not provoke undefined behaviour, then + * assume that the error will be set on failure.</para></footnote> + * + * - A %NULL return value is also frequently used to mean that an error * occurred. You should make clear in your documentation whether %NULL * is a valid return value in non-error cases; if %NULL is a valid value, * then users must check whether an error was returned to see if the * function succeeded. - * </para></listitem> - * <listitem><para> - * When implementing a function that can report errors, you may want + * + * - When implementing a function that can report errors, you may want * to add a check at the top of your function that the error return * location is either %NULL or contains a %NULL error (e.g. - * <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>). - * </para></listitem> - * </itemizedlist> + * `g_return_if_fail (error == NULL || *error == NULL);`). */ @@ -5550,8 +5800,8 @@ * * The pathname argument should be in the GLib file name encoding. * On POSIX this is the actual on-disk encoding which might correspond - * to the locale settings of the process (or the - * <envar>G_FILENAME_ENCODING</envar> environment variable), or not. + * to the locale settings of the process (or the `G_FILENAME_ENCODING` + * environment variable), or not. * * On Windows the GLib file name encoding is UTF-8. Note that the * Microsoft C library does not use UTF-8, but has separate APIs for @@ -5573,9 +5823,9 @@ * converting between Unicode and ASCII-encoded forms of * Internationalized Domain Names (IDNs). * - * The <ulink - * url="http://www.ietf.org/rfc/rfc3490.txt">Internationalized Domain - * Names for Applications (IDNA)</ulink> standards allow for the use + * The + * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) + * standards allow for the use * of Unicode domain names in applications, while providing * backward-compatibility with the old ASCII-only DNS, by defining an * ASCII-Compatible Encoding of any given Unicode name, which can be @@ -5588,9 +5838,9 @@ * SECTION:gregex * @title: Perl-compatible regular expressions * @short_description: matches strings against regular expressions - * @see_also: <xref linkend="glib-regex-syntax"/> + * @see_also: [Regular expression syntax][glib-regex-syntax] * - * The <function>g_regex_*()</function> functions implement regular + * The g_regex_*() functions implement regular * expression pattern matching using syntax and semantics similar to * Perl regular expression. * @@ -5644,7 +5894,7 @@ * '\U' always matches 'U' instead of being an error in the pattern. Finally, * pattern matching is modified so that back references to an unset subpattern * group produces a match with the empty string instead of an error. See - * <ulink>man:pcreapi(3)</ulink> for more information. + * pcreapi(3) for more information. * * Creating and manipulating the same #GRegex structure from different * threads is not a problem as #GRegex does not modify its internal @@ -5652,8 +5902,9 @@ * is not threadsafe. * * The regular expressions low-level functionalities are obtained through - * the excellent <ulink url="http://www.pcre.org/">PCRE</ulink> library - * written by Philip Hazel. + * the excellent + * [PCRE](http://www.pcre.org/) + * library written by Philip Hazel. */ @@ -5679,8 +5930,9 @@ * @short_description: manipulating URIs * * Functions for manipulating Universal Resource Identifiers (URIs) as - * defined by <ulink url="http://www.ietf.org/rfc/rfc3986.txt"> - * RFC 3986</ulink>. It is highly recommended that you have read and + * defined by + * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt). + * It is highly recommended that you have read and * understand RFC 3986 for understanding this API. */ @@ -5742,201 +5994,169 @@ * values. #GVariant includes a printer for this language and a parser * with type inferencing. * - * <refsect2> - * <title>Memory Use</title> - * <para> - * #GVariant tries to be quite efficient with respect to memory use. - * This section gives a rough idea of how much memory is used by the - * current implementation. The information here is subject to change - * in the future. - * </para> - * <para> - * The memory allocated by #GVariant can be grouped into 4 broad - * purposes: memory for serialised data, memory for the type - * information cache, buffer management memory and memory for the - * #GVariant structure itself. - * </para> - * <refsect3 id="gvariant-serialised-data-memory"> - * <title>Serialised Data Memory</title> - * <para> - * This is the memory that is used for storing GVariant data in - * serialised form. This is what would be sent over the network or - * what would end up on disk. - * </para> - * <para> - * The amount of memory required to store a boolean is 1 byte. 16, - * 32 and 64 bit integers and double precision floating point numbers - * use their "natural" size. Strings (including object path and - * signature strings) are stored with a nul terminator, and as such - * use the length of the string plus 1 byte. - * </para> - * <para> - * Maybe types use no space at all to represent the null value and - * use the same amount of space (sometimes plus one byte) as the - * equivalent non-maybe-typed value to represent the non-null case. - * </para> - * <para> - * Arrays use the amount of space required to store each of their - * members, concatenated. Additionally, if the items stored in an - * array are not of a fixed-size (ie: strings, other arrays, etc) - * then an additional framing offset is stored for each item. The - * size of this offset is either 1, 2 or 4 bytes depending on the - * overall size of the container. Additionally, extra padding bytes - * are added as required for alignment of child values. - * </para> - * <para> - * Tuples (including dictionary entries) use the amount of space - * required to store each of their members, concatenated, plus one - * framing offset (as per arrays) for each non-fixed-sized item in - * the tuple, except for the last one. Additionally, extra padding - * bytes are added as required for alignment of child values. - * </para> - * <para> - * Variants use the same amount of space as the item inside of the - * variant, plus 1 byte, plus the length of the type string for the - * item inside the variant. - * </para> - * <para> - * As an example, consider a dictionary mapping strings to variants. - * In the case that the dictionary is empty, 0 bytes are required for - * the serialisation. - * </para> - * <para> - * If we add an item "width" that maps to the int32 value of 500 then - * we will use 4 byte to store the int32 (so 6 for the variant - * containing it) and 6 bytes for the string. The variant must be - * aligned to 8 after the 6 bytes of the string, so that's 2 extra - * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used - * for the dictionary entry. An additional 1 byte is added to the - * array as a framing offset making a total of 15 bytes. - * </para> - * <para> - * If we add another entry, "title" that maps to a nullable string - * that happens to have a value of null, then we use 0 bytes for the - * null value (and 3 bytes for the variant to contain it along with - * its type string) plus 6 bytes for the string. Again, we need 2 - * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. - * </para> - * <para> - * We now require extra padding between the two items in the array. - * After the 14 bytes of the first item, that's 2 bytes required. We - * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 - * + 2 = 29 bytes to encode the entire two-item dictionary. - * </para> - * </refsect3> - * <refsect3> - * <title>Type Information Cache</title> - * <para> - * For each GVariant type that currently exists in the program a type - * information structure is kept in the type information cache. The - * type information structure is required for rapid deserialisation. - * </para> - * <para> - * Continuing with the above example, if a #GVariant exists with the - * type "a{sv}" then a type information struct will exist for - * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type - * will share the same type information. Additionally, all - * single-digit types are stored in read-only static memory and do - * not contribute to the writable memory footprint of a program using - * #GVariant. - * </para> - * <para> - * Aside from the type information structures stored in read-only - * memory, there are two forms of type information. One is used for - * container types where there is a single element type: arrays and - * maybe types. The other is used for container types where there - * are multiple element types: tuples and dictionary entries. - * </para> - * <para> - * Array type info structures are 6 * sizeof (void *), plus the - * memory required to store the type string itself. This means that - * on 32bit systems, the cache entry for "a{sv}" would require 30 - * bytes of memory (plus malloc overhead). - * </para> - * <para> - * Tuple type info structures are 6 * sizeof (void *), plus 4 * - * sizeof (void *) for each item in the tuple, plus the memory - * required to store the type string itself. A 2-item tuple, for - * example, would have a type information structure that consumed - * writable memory in the size of 14 * sizeof (void *) (plus type - * string) This means that on 32bit systems, the cache entry for - * "{sv}" would require 61 bytes of memory (plus malloc overhead). - * </para> - * <para> - * This means that in total, for our "a{sv}" example, 91 bytes of - * type information would be allocated. - * </para> - * <para> - * The type information cache, additionally, uses a #GHashTable to - * store and lookup the cached items and stores a pointer to this - * hash table in static storage. The hash table is freed when there - * are zero items in the type cache. - * </para> - * <para> - * Although these sizes may seem large it is important to remember - * that a program will probably only have a very small number of - * different types of values in it and that only one type information - * structure is required for many different values of the same type. - * </para> - * </refsect3> - * <refsect3> - * <title>Buffer Management Memory</title> - * <para> - * #GVariant uses an internal buffer management structure to deal - * with the various different possible sources of serialised data - * that it uses. The buffer is responsible for ensuring that the - * correct call is made when the data is no longer in use by - * #GVariant. This may involve a g_free() or a g_slice_free() or - * even g_mapped_file_unref(). - * </para> - * <para> - * One buffer management structure is used for each chunk of - * serialised data. The size of the buffer management structure is 4 - * * (void *). On 32bit systems, that's 16 bytes. - * </para> - * </refsect3> - * <refsect3> - * <title>GVariant structure</title> - * <para> - * The size of a #GVariant structure is 6 * (void *). On 32 bit - * systems, that's 24 bytes. - * </para> - * <para> - * #GVariant structures only exist if they are explicitly created - * with API calls. For example, if a #GVariant is constructed out of - * serialised data for the example given above (with the dictionary) - * then although there are 9 individual values that comprise the - * entire dictionary (two keys, two values, two variants containing - * the values, two dictionary entries, plus the dictionary itself), - * only 1 #GVariant instance exists -- the one referring to the - * dictionary. - * </para> - * <para> - * If calls are made to start accessing the other values then - * #GVariant instances will exist for those values only for as long - * as they are in use (ie: until you call g_variant_unref()). The - * type information is shared. The serialised data and the buffer - * management structure for that serialised data is shared by the - * child. - * </para> - * </refsect3> - * <refsect3> - * <title>Summary</title> - * <para> - * To put the entire example together, for our dictionary mapping - * strings to variants (with two entries, as given above), we are - * using 91 bytes of memory for type information, 29 byes of memory - * for the serialised data, 16 bytes for buffer management and 24 - * bytes for the #GVariant instance, or a total of 160 bytes, plus - * malloc overhead. If we were to use g_variant_get_child_value() to - * access the two dictionary entries, we would use an additional 48 - * bytes. If we were to have other dictionaries of the same type, we - * would use more memory for the serialised data and buffer - * management for those dictionaries, but the type information would - * be shared. - * </para> - * </refsect3> - * </refsect2> + * ## Memory Use + * + * #GVariant tries to be quite efficient with respect to memory use. + * This section gives a rough idea of how much memory is used by the + * current implementation. The information here is subject to change + * in the future. + * + * The memory allocated by #GVariant can be grouped into 4 broad + * purposes: memory for serialised data, memory for the type + * information cache, buffer management memory and memory for the + * #GVariant structure itself. + * + * ## Serialised Data Memory + * + * This is the memory that is used for storing GVariant data in + * serialised form. This is what would be sent over the network or + * what would end up on disk. + * + * The amount of memory required to store a boolean is 1 byte. 16, + * 32 and 64 bit integers and double precision floating point numbers + * use their "natural" size. Strings (including object path and + * signature strings) are stored with a nul terminator, and as such + * use the length of the string plus 1 byte. + * + * Maybe types use no space at all to represent the null value and + * use the same amount of space (sometimes plus one byte) as the + * equivalent non-maybe-typed value to represent the non-null case. + * + * Arrays use the amount of space required to store each of their + * members, concatenated. Additionally, if the items stored in an + * array are not of a fixed-size (ie: strings, other arrays, etc) + * then an additional framing offset is stored for each item. The + * size of this offset is either 1, 2 or 4 bytes depending on the + * overall size of the container. Additionally, extra padding bytes + * are added as required for alignment of child values. + * + * Tuples (including dictionary entries) use the amount of space + * required to store each of their members, concatenated, plus one + * framing offset (as per arrays) for each non-fixed-sized item in + * the tuple, except for the last one. Additionally, extra padding + * bytes are added as required for alignment of child values. + * + * Variants use the same amount of space as the item inside of the + * variant, plus 1 byte, plus the length of the type string for the + * item inside the variant. + * + * As an example, consider a dictionary mapping strings to variants. + * In the case that the dictionary is empty, 0 bytes are required for + * the serialisation. + * + * If we add an item "width" that maps to the int32 value of 500 then + * we will use 4 byte to store the int32 (so 6 for the variant + * containing it) and 6 bytes for the string. The variant must be + * aligned to 8 after the 6 bytes of the string, so that's 2 extra + * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used + * for the dictionary entry. An additional 1 byte is added to the + * array as a framing offset making a total of 15 bytes. + * + * If we add another entry, "title" that maps to a nullable string + * that happens to have a value of null, then we use 0 bytes for the + * null value (and 3 bytes for the variant to contain it along with + * its type string) plus 6 bytes for the string. Again, we need 2 + * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. + * + * We now require extra padding between the two items in the array. + * After the 14 bytes of the first item, that's 2 bytes required. + * We now require 2 framing offsets for an extra two + * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item + * dictionary. + * + * ## Type Information Cache + * + * For each GVariant type that currently exists in the program a type + * information structure is kept in the type information cache. The + * type information structure is required for rapid deserialisation. + * + * Continuing with the above example, if a #GVariant exists with the + * type "a{sv}" then a type information struct will exist for + * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type + * will share the same type information. Additionally, all + * single-digit types are stored in read-only static memory and do + * not contribute to the writable memory footprint of a program using + * #GVariant. + * + * Aside from the type information structures stored in read-only + * memory, there are two forms of type information. One is used for + * container types where there is a single element type: arrays and + * maybe types. The other is used for container types where there + * are multiple element types: tuples and dictionary entries. + * + * Array type info structures are 6 * sizeof (void *), plus the + * memory required to store the type string itself. This means that + * on 32-bit systems, the cache entry for "a{sv}" would require 30 + * bytes of memory (plus malloc overhead). + * + * Tuple type info structures are 6 * sizeof (void *), plus 4 * + * sizeof (void *) for each item in the tuple, plus the memory + * required to store the type string itself. A 2-item tuple, for + * example, would have a type information structure that consumed + * writable memory in the size of 14 * sizeof (void *) (plus type + * string) This means that on 32-bit systems, the cache entry for + * "{sv}" would require 61 bytes of memory (plus malloc overhead). + * + * This means that in total, for our "a{sv}" example, 91 bytes of + * type information would be allocated. + * + * The type information cache, additionally, uses a #GHashTable to + * store and lookup the cached items and stores a pointer to this + * hash table in static storage. The hash table is freed when there + * are zero items in the type cache. + * + * Although these sizes may seem large it is important to remember + * that a program will probably only have a very small number of + * different types of values in it and that only one type information + * structure is required for many different values of the same type. + * + * ## Buffer Management Memory + * + * #GVariant uses an internal buffer management structure to deal + * with the various different possible sources of serialised data + * that it uses. The buffer is responsible for ensuring that the + * correct call is made when the data is no longer in use by + * #GVariant. This may involve a g_free() or a g_slice_free() or + * even g_mapped_file_unref(). + * + * One buffer management structure is used for each chunk of + * serialised data. The size of the buffer management structure + * is 4 * (void *). On 32-bit systems, that's 16 bytes. + * + * ## GVariant structure + * + * The size of a #GVariant structure is 6 * (void *). On 32-bit + * systems, that's 24 bytes. + * + * #GVariant structures only exist if they are explicitly created + * with API calls. For example, if a #GVariant is constructed out of + * serialised data for the example given above (with the dictionary) + * then although there are 9 individual values that comprise the + * entire dictionary (two keys, two values, two variants containing + * the values, two dictionary entries, plus the dictionary itself), + * only 1 #GVariant instance exists -- the one referring to the + * dictionary. + * + * If calls are made to start accessing the other values then + * #GVariant instances will exist for those values only for as long + * as they are in use (ie: until you call g_variant_unref()). The + * type information is shared. The serialised data and the buffer + * management structure for that serialised data is shared by the + * child. + * + * ## Summary + * + * To put the entire example together, for our dictionary mapping + * strings to variants (with two entries, as given above), we are + * using 91 bytes of memory for type information, 29 byes of memory + * for the serialised data, 16 bytes for buffer management and 24 + * bytes for the #GVariant instance, or a total of 160 bytes, plus + * malloc overhead. If we were to use g_variant_get_child_value() to + * access the two dictionary entries, we would use an additional 48 + * bytes. If we were to have other dictionaries of the same type, we + * would use more memory for the serialised data and buffer + * management for those dictionaries, but the type information would + * be shared. */ @@ -5946,18 +6166,18 @@ * @short_description: introduction to the GVariant type system * @see_also: #GVariantType, #GVariant * - * This section introduces the GVariant type system. It is based, in - * large part, on the D-Bus type system, with two major changes and some minor - * lifting of restrictions. The <ulink - * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus - * specification</ulink>, therefore, provides a significant amount of + * This section introduces the GVariant type system. It is based, in + * large part, on the D-Bus type system, with two major changes and + * some minor lifting of restrictions. The + * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), + * therefore, provides a significant amount of * information that is useful when working with GVariant. * * The first major change with respect to the D-Bus type system is the * introduction of maybe (or "nullable") types. Any type in GVariant can be * converted to a maybe type, in which case, "nothing" (or "null") becomes a * valid value. Maybe types have been added by introducing the - * character "<literal>m</literal>" to type strings. + * character "m" to type strings. * * The second major change is that the GVariant type system supports the * concept of "indefinite types" -- types that are less specific than @@ -5965,8 +6185,7 @@ * of "an array of any type" in GVariant, where the D-Bus type system * would require you to speak of "an array of integers" or "an array of * strings". Indefinite types have been added by introducing the - * characters "<literal>*</literal>", "<literal>?</literal>" and - * "<literal>r</literal>" to type strings. + * characters "*", "?" and "r" to type strings. * * Finally, all arbitrary restrictions relating to the complexity of * types are lifted along with the restriction that dictionary entries @@ -6004,399 +6223,101 @@ * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of * #GtkBin). * - * A detailed description of GVariant type strings is given here: - * - * <refsect2 id='gvariant-typestrings'> - * <title>GVariant Type Strings</title> - * <para> - * A GVariant type string can be any of the following: - * </para> - * <itemizedlist> - * <listitem> - * <para> - * any basic type string (listed below) - * </para> - * </listitem> - * <listitem> - * <para> - * "<literal>v</literal>", "<literal>r</literal>" or - * "<literal>*</literal>" - * </para> - * </listitem> - * <listitem> - * <para> - * one of the characters '<literal>a</literal>' or - * '<literal>m</literal>', followed by another type string - * </para> - * </listitem> - * <listitem> - * <para> - * the character '<literal>(</literal>', followed by a concatenation - * of zero or more other type strings, followed by the character - * '<literal>)</literal>' - * </para> - * </listitem> - * <listitem> - * <para> - * the character '<literal>{</literal>', followed by a basic type - * string (see below), followed by another type string, followed by - * the character '<literal>}</literal>' - * </para> - * </listitem> - * </itemizedlist> - * <para> - * A basic type string describes a basic type (as per - * g_variant_type_is_basic()) and is always a single - * character in length. The valid basic type strings are - * "<literal>b</literal>", "<literal>y</literal>", - * "<literal>n</literal>", "<literal>q</literal>", - * "<literal>i</literal>", "<literal>u</literal>", - * "<literal>x</literal>", "<literal>t</literal>", - * "<literal>h</literal>", "<literal>d</literal>", - * "<literal>s</literal>", "<literal>o</literal>", - * "<literal>g</literal>" and "<literal>?</literal>". - * </para> - * <para> - * The above definition is recursive to arbitrary depth. - * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>" - * are both valid type strings, as is - * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>". - * </para> - * <para> - * The meaning of each of the characters is as follows: - * </para> - * <informaltable> - * <tgroup cols='2'> - * <tbody> - * <row> - * <entry> - * <para> - * <emphasis role='strong'>Character</emphasis> - * </para> - * </entry> - * <entry> - * <para> - * <emphasis role='strong'>Meaning</emphasis> - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>b</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>y</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_BYTE; a byte. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>n</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit - * integer. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>q</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit - * integer. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>i</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit - * integer. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>u</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit - * integer. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>x</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit - * integer. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>t</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit - * integer. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>h</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit - * value that, by convention, is used as an index into an array - * of file descriptors that are sent alongside a D-Bus message. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>d</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision - * floating point value. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>s</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_STRING; a string. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>o</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in - * the form of a D-Bus object path. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>g</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_STRING; a string in the - * form of a D-Bus type signature. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>?</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type - * that is a supertype of any of the basic types. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>v</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_VARIANT; a container type - * that contain any other type of value. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>a</literal> - * </para> - * </entry> - * <entry> - * <para> - * used as a prefix on another type string to mean an array of - * that type; the type string "<literal>ai</literal>", for - * example, is the type of an array of 32 bit signed integers. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>m</literal> - * </para> - * </entry> - * <entry> - * <para> - * used as a prefix on another type string to mean a "maybe", or - * "nullable", version of that type; the type string - * "<literal>ms</literal>", for example, is the type of a value - * that maybe contains a string, or maybe contains nothing. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>()</literal> - * </para> - * </entry> - * <entry> - * <para> - * used to enclose zero or more other concatenated type strings - * to create a tuple type; the type string - * "<literal>(is)</literal>", for example, is the type of a pair - * of an integer and a string. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>r</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type - * that is a supertype of any tuple type, regardless of the - * number of items. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>{}</literal> - * </para> - * </entry> - * <entry> - * <para> - * used to enclose a basic type string concatenated with another - * type string to create a dictionary entry type, which usually - * appears inside of an array to form a dictionary; the type - * string "<literal>a{sd}</literal>", for example, is the type of - * a dictionary that maps strings to double precision floating - * point values. - * </para> - * <para> - * The first type (the basic type) is the key type and the second - * type is the value type. The reason that the first type is - * restricted to being a basic type is so that it can easily be - * hashed. - * </para> - * </entry> - * </row> - * <row> - * <entry> - * <para> - * <literal>*</literal> - * </para> - * </entry> - * <entry> - * <para> - * the type string of %G_VARIANT_TYPE_ANY; the indefinite type - * that is a supertype of all types. Note that, as with all type - * strings, this character represents exactly one type. It - * cannot be used inside of tuples to mean "any number of items". - * </para> - * </entry> - * </row> - * </tbody> - * </tgroup> - * </informaltable> - * <para> - * Any type string of a container that contains an indefinite type is, - * itself, an indefinite type. For example, the type string - * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is - * an indefinite type that is a supertype of every array type. - * "<literal>(*s)</literal>" is a supertype of all tuples that - * contain exactly two items where the second item is a string. - * </para> - * <para> - * "<literal>a{?*}</literal>" is an indefinite type that is a - * supertype of all arrays containing dictionary entries where the key - * is any basic type and the value is any type at all. This is, by - * definition, a dictionary, so this type string corresponds to - * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that - * the key of a dictionary entry must be a basic type, - * "<literal>{**}</literal>" is not a valid type string. - * </para> - * </refsect2> + * ## GVariant Type Strings + * + * A GVariant type string can be any of the following: + * + * - any basic type string (listed below) + * + * - "v", "r" or "*" + * + * - one of the characters 'a' or 'm', followed by another type string + * + * - the character '(', followed by a concatenation of zero or more other + * type strings, followed by the character ')' + * + * - the character '{', followed by a basic type string (see below), + * followed by another type string, followed by the character '}' + * + * A basic type string describes a basic type (as per + * g_variant_type_is_basic()) and is always a single character in length. + * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", + * "h", "d", "s", "o", "g" and "?". + * + * The above definition is recursive to arbitrary depth. "aaaaai" and + * "(ui(nq((y)))s)" are both valid type strings, as is + * "a(aa(ui)(qna{ya(yd)}))". + * + * The meaning of each of the characters is as follows: + * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. + * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. + * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. + * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. + * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. + * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. + * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. + * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. + * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value + * that, by convention, is used as an index into an array of file + * descriptors that are sent alongside a D-Bus message. + * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision + * floating point value. + * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string. + * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form + * of a D-Bus object path. + * - `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of + * a D-Bus type signature. + * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that + * is a supertype of any of the basic types. + * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that + * contain any other type of value. + * - `a`: used as a prefix on another type string to mean an array of that + * type; the type string "ai", for example, is the type of an array of + * signed 32-bit integers. + * - `m`: used as a prefix on another type string to mean a "maybe", or + * "nullable", version of that type; the type string "ms", for example, + * is the type of a value that maybe contains a string, or maybe contains + * nothing. + * - `()`: used to enclose zero or more other concatenated type strings to + * create a tuple type; the type string "(is)", for example, is the type of + * a pair of an integer and a string. + * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is + * a supertype of any tuple type, regardless of the number of items. + * - `{}`: used to enclose a basic type string concatenated with another type + * string to create a dictionary entry type, which usually appears inside of + * an array to form a dictionary; the type string "a{sd}", for example, is + * the type of a dictionary that maps strings to double precision floating + * point values. + * + * The first type (the basic type) is the key type and the second type is + * the value type. The reason that the first type is restricted to being a + * basic type is so that it can easily be hashed. + * - `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is + * a supertype of all types. Note that, as with all type strings, this + * character represents exactly one type. It cannot be used inside of tuples + * to mean "any number of items". + * + * Any type string of a container that contains an indefinite type is, + * itself, an indefinite type. For example, the type string "a*" + * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type + * that is a supertype of every array type. "(*s)" is a supertype + * of all tuples that contain exactly two items where the second + * item is a string. + * + * "a{?*}" is an indefinite type that is a supertype of all arrays + * containing dictionary entries where the key is any basic type and + * the value is any type at all. This is, by definition, a dictionary, + * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note + * that, due to the restriction that the key of a dictionary entry must + * be a basic type, "{**}" is not a valid type string. */ /** * SECTION:hash_tables * @title: Hash Tables - * @short_description: associations between keys and values so that given a key the value can be found quickly + * @short_description: associations between keys and values so that + * given a key the value can be found quickly * * A #GHashTable provides associations between keys and values which is * optimized so that given a key, the associated value can be found @@ -6434,50 +6355,14 @@ * * To destroy a #GHashTable use g_hash_table_destroy(). * - * <example> - * <title>Using a GHashTable as a set</title> - * <para> - * A common use-case for hash tables is to store information about - * a set of keys, without associating any particular value with each + * A common use-case for hash tables is to store information about a + * set of keys, without associating any particular value with each * key. GHashTable optimizes one way of doing so: If you store only * key-value pairs where key == value, then GHashTable does not * allocate memory to store the values, which can be a considerable - * space saving, if your set is large. - * </para> - * <programlisting> - * GHashTable * - * set_new (GHashFunc hash_func, - * GEqualFunc equal_func, - * GDestroyNotify destroy) - * { - * return g_hash_table_new_full (hash_func, equal_func, destroy, NULL); - * } - * - * void - * set_add (GHashTable *set, - * gpointer element) - * { - * g_hash_table_replace (set, element, element); - * } - * - * gboolean - * set_contains (GHashTable *set, - * gpointer element) - * { - * return g_hash_table_lookup_extended (set, element, NULL, NULL); - * } - * - * gboolean - * set_remove (GHashTable *set, - * gpointer element) - * { - * return g_hash_table_remove (set, element); - * } - * </programlisting> - * </example> - * - * As of version 2.32, there is also a g_hash_table_add() function to - * add a key to a #GHashTable that is being used as a set. + * space saving, if your set is large. The functions + * g_hash_table_add() and g_hash_table_contains() are designed to be + * used when using #GHashTable this way. */ @@ -6489,7 +6374,8 @@ * HMACs should be used when producing a cookie or hash based on data * and a key. Simple mechanisms for using SHA1 and other algorithms to * digest a key and data together are vulnerable to various security - * issues. <ulink url="http://en.wikipedia.org/wiki/HMAC">HMAC</ulink> + * issues. + * [HMAC](http://en.wikipedia.org/wiki/HMAC) * uses algorithms like SHA1 in a secure way to produce a digest of a * key and data. * @@ -6522,16 +6408,21 @@ * easy-to-use form. * * In order to use these macros in an application, you must include - * <filename>glib/gi18n.h</filename>. For use in a library, must include - * <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining - * the GETTEXT_PACKAGE macro suitably for your library: - * |[ - * #define GETTEXT_PACKAGE "gtk20" - * #include <glib/gi18n-lib.h> + * `<glib/gi18n.h>`. For use in a library, you must include + * `<glib/gi18n-lib.h>` + * after defining the %GETTEXT_PACKAGE macro suitably for your library: + * |[<!-- language="C" --> + * #define GETTEXT_PACKAGE "gtk20" + * #include <glib/gi18n-lib.h> * ]| - * Note that you also have to call setlocale() and textdomain() (as well as - * bindtextdomain() and bind_textdomain_codeset()) early on in your main() - * to make gettext() work. + * For an application, note that you also have to call bindtextdomain(), + * bind_textdomain_codeset(), textdomain() and setlocale() early on in your + * main() to make gettext() work. + * + * For a library, you only have to call bindtextdomain() and + * bind_textdomain_codeset() in your initialization function. If your library + * doesn't have an initialization function, you can call the functions before + * the first translated message. * * The gettext manual covers details of how to set up message extraction * with xgettext. @@ -6542,13 +6433,14 @@ * SECTION:iochannels * @title: IO Channels * @short_description: portable support for using files, pipes and sockets - * @see_also: <para> <variablelist> <varlistentry> <term>g_io_add_watch(), g_io_add_watch_full(), g_source_remove()</term> <listitem><para> Convenience functions for creating #GIOChannel instances and adding them to the <link linkend="glib-The-Main-Event-Loop">main event loop</link>. </para></listitem> </varlistentry> </variablelist> </para> + * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(), + * #GMainLoop * * The #GIOChannel data type aims to provide a portable method for * using file descriptors, pipes, and sockets, and integrating them - * into the <link linkend="glib-The-Main-Event-Loop">main event - * loop</link>. Currently full support is available on UNIX platforms, - * support for Windows is only partially complete. + * into the [main event loop][glib-The-Main-Event-Loop]. Currently, + * full support is available on UNIX platforms, support for Windows + * is only partially complete. * * To create a new #GIOChannel on UNIX systems use * g_io_channel_unix_new(). This works for plain file descriptors, @@ -6560,9 +6452,8 @@ * g_io_channel_write_chars(), g_io_channel_seek_position(), and * g_io_channel_shutdown(). * - * To add a #GIOChannel to the <link - * linkend="glib-The-Main-Event-Loop">main event loop</link> use - * g_io_add_watch() or g_io_add_watch_full(). Here you specify which + * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], + * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which * events you are interested in on the #GIOChannel, and provide a * function to be called whenever these events occur. * @@ -6589,17 +6480,15 @@ * @short_description: parses .ini-like config files * * #GKeyFile lets you parse, edit or create files containing groups of - * key-value pairs, which we call <firstterm>key files</firstterm> for - * lack of a better name. Several freedesktop.org specifications use - * key files now, e.g the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink> and the - * <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon - * Theme Specification</ulink>. + * key-value pairs, which we call "key files" for lack of a better name. + * Several freedesktop.org specifications use key files now, e.g the + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) + * and the + * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). * * The syntax of key files is described in detail in the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink>, here is a quick summary: Key files + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), + * here is a quick summary: Key files * consists of groups of key-value pairs, interspersed with comments. * * |[ @@ -6630,11 +6519,11 @@ * in '[' and ']', and ended implicitly by the start of the next group or * the end of the file. Each key-value pair must be contained in a group. * - * Key-value pairs generally have the form <literal>key=value</literal>, - * with the exception of localized strings, which have the form - * <literal>key[locale]=value</literal>, with a locale identifier of the - * form <literal>lang_COUNTRY@MODIFIER</literal> where - * <literal>COUNTRY</literal> and <literal>MODIFIER</literal> are optional. + * Key-value pairs generally have the form `key=value`, with the + * exception of localized strings, which have the form + * `key[locale]=value`, with a locale identifier of the + * form `lang_COUNTRY\@MODIFIER` where `COUNTRY` and `MODIFIER` + * are optional. * Space before and after the '=' character are ignored. Newline, tab, * carriage return and backslash characters in value are escaped as \n, * \t, \r, and \\, respectively. To preserve leading spaces in values, @@ -6647,24 +6536,25 @@ * * This syntax is obviously inspired by the .ini files commonly met * on Windows, but there are some important differences: - * <itemizedlist> - * <listitem>.ini files use the ';' character to begin comments, - * key files use the '#' character.</listitem> - * <listitem>Key files do not allow for ungrouped keys meaning only - * comments can precede the first group.</listitem> - * <listitem>Key files are always encoded in UTF-8.</listitem> - * <listitem>Key and Group names are case-sensitive. For example, a - * group called <literal>[GROUP]</literal> is a different from - * <literal>[group]</literal>.</listitem> - * <listitem>.ini files don't have a strongly typed boolean entry type, - * they only have GetProfileInt(). In key files, only - * <literal>true</literal> and <literal>false</literal> (in lower case) - * are allowed.</listitem> - * </itemizedlist> + * + * - .ini files use the ';' character to begin comments, + * key files use the '#' character. + * + * - Key files do not allow for ungrouped keys meaning only + * comments can precede the first group. + * + * - Key files are always encoded in UTF-8. + * + * - Key and Group names are case-sensitive. For example, a group called + * [GROUP] is a different from [group]. + * + * - .ini files don't have a strongly typed boolean entry type, + * they only have GetProfileInt(). In key files, only + * true and false (in lower case) are allowed. * * Note that in contrast to the - * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop - * Entry Specification</ulink>, groups in key files may contain the same + * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), + * groups in key files may contain the same * key multiple times; the last entry wins. Key files may also contain * multiple groups with the same name; they are merged together. * Another difference is that keys and group names in key files are not @@ -6683,40 +6573,72 @@ * Each element in the list contains a piece of data, together with * pointers which link to the previous and next elements in the list. * Using these pointers it is possible to move through the list in both - * directions (unlike the <link - * linkend="glib-Singly-Linked-Lists">Singly-Linked Lists</link> which - * only allows movement through the list in the forward direction). + * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], + * which only allows movement through the list in the forward direction). + * + * The double linked list does not keep track of the number of items + * and does not keep track of both the start and end of the list. If + * you want fast access to both the start and the end of the list, + * and/or the number of items in the list, use a + * [GQueue][glib-Double-ended-Queues] instead. * * The data contained in each element can be either integer values, by - * using one of the <link linkend="glib-Type-Conversion-Macros">Type - * Conversion Macros</link>, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * - * List elements are allocated from the <link - * linkend="glib-Memory-Slices">slice allocator</link>, which is more - * efficient than allocating elements individually. + * List elements are allocated from the [slice allocator][glib-Memory-Slices], + * which is more efficient than allocating elements individually. * * Note that most of the #GList functions expect to be passed a pointer * to the first element in the list. The functions which insert * elements return the new start of the list, which may have changed. * * There is no function to create a #GList. %NULL is considered to be - * the empty list so you simply set a #GList* to %NULL. + * a valid, empty list so you simply set a #GList* to %NULL to initialize + * it. * * To add elements, use g_list_append(), g_list_prepend(), * g_list_insert() and g_list_insert_sorted(). * + * To visit all elements in the list, use a loop over the list: + * |[<!-- language="C" --> + * GList *l; + * for (l = list; l != NULL; l = l->next) + * { + * // do something with l->data + * } + * ]| + * + * To call a function for each element in the list, use g_list_foreach(). + * + * To loop over the list and modify it (e.g. remove a certain element) + * a while loop is more appropriate, for example: + * |[<!-- language="C" --> + * GList *l = list; + * while (l != NULL) + * { + * GList *next = l->next; + * if (should_be_removed (l)) + * { + * // possibly free l->data + * list = g_list_delete_link (list, l); + * } + * l = next; + * } + * ]| + * * To remove elements, use g_list_remove(). * - * To find elements in the list use g_list_first(), g_list_last(), - * g_list_next(), g_list_previous(), g_list_nth(), g_list_nth_data(), + * To navigate in a list, use g_list_first(), g_list_last(), + * g_list_next(), g_list_previous(). + * + * To find elements in the list use g_list_nth(), g_list_nth_data(), * g_list_find() and g_list_find_custom(). * * To find the index of an element use g_list_position() and * g_list_index(). * - * To call a function for each element in the list use g_list_foreach(). - * - * To free the entire list, use g_list_free(). + * To free the entire list, use g_list_free() or g_list_free_full(). */ @@ -6731,17 +6653,15 @@ * Each element in the list contains a piece of data, together with a * pointer which links to the next element in the list. Using this * pointer it is possible to move through the list in one direction - * only (unlike the <link - * linkend="glib-Doubly-Linked-Lists">Doubly-Linked Lists</link> which - * allow movement in both directions). + * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], + * which allow movement in both directions). * * The data contained in each element can be either integer values, by - * using one of the <link linkend="glib-Type-Conversion-Macros">Type - * Conversion Macros</link>, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * - * List elements are allocated from the <link - * linkend="glib-Memory-Slices">slice allocator</link>, which is more - * efficient than allocating elements individually. + * List elements are allocated from the [slice allocator][glib-Memory-Slices], + * which is more efficient than allocating elements individually. * * Note that most of the #GSList functions expect to be passed a * pointer to the first element in the list. The functions which insert @@ -6828,42 +6748,46 @@ * GTK+ contains wrappers of some of these functions, e.g. gtk_main(), * gtk_main_quit() and gtk_events_pending(). * - * <refsect2><title>Creating new source types</title> - * <para>One of the unusual features of the #GMainLoop functionality + * ## Creating new source types + * + * One of the unusual features of the #GMainLoop functionality * is that new types of event source can be created and used in * addition to the builtin type of event source. A new event source * type is used for handling GDK events. A new source type is created - * by <firstterm>deriving</firstterm> from the #GSource structure. - * The derived type of source is represented by a structure that has - * the #GSource structure as a first element, and other elements specific - * to the new source type. To create an instance of the new source type, - * call g_source_new() passing in the size of the derived structure and + * by "deriving" from the #GSource structure. The derived type of + * source is represented by a structure that has the #GSource structure + * as a first element, and other elements specific to the new source + * type. To create an instance of the new source type, call + * g_source_new() passing in the size of the derived structure and * a table of functions. These #GSourceFuncs determine the behavior of - * the new source type.</para> - * <para>New source types basically interact with the main context + * the new source type. + * + * New source types basically interact with the main context * in two ways. Their prepare function in #GSourceFuncs can set a timeout * to determine the maximum amount of time that the main loop will sleep * before checking the source again. In addition, or as well, the source * can add file descriptors to the set that the main context checks using - * g_source_add_poll().</para> - * </refsect2> - * <refsect2><title>Customizing the main loop iteration</title> - * <para>Single iterations of a #GMainContext can be run with + * g_source_add_poll(). + * + * ## Customizing the main loop iteration + * + * Single iterations of a #GMainContext can be run with * g_main_context_iteration(). In some cases, more detailed control * of exactly how the details of the main loop work is desired, for * instance, when integrating the #GMainLoop with an external main loop. * In such cases, you can call the component functions of * g_main_context_iteration() directly. These functions are * g_main_context_prepare(), g_main_context_query(), - * g_main_context_check() and g_main_context_dispatch().</para> - * <para>The operation of these functions can best be seen in terms - * of a state diagram, as shown in <xref linkend="mainloop-states"/>.</para> - * <figure id="mainloop-states"><title>States of a Main Context</title> - * <graphic fileref="mainloop-states.gif" format="GIF"></graphic> - * </figure> - * </refsect2> - * - * On Unix, the GLib mainloop is incompatible with fork(). Any program + * g_main_context_check() and g_main_context_dispatch(). + * + * ## State of a Main Context # {#mainloop-states} + * + * The operation of these functions can best be seen in terms + * of a state diagram, as shown in this image. + * + *  + * + * On UNIX, the GLib mainloop is incompatible with fork(). Any program * using the mainloop must either exec() or exit() from the child * without returning to the mainloop. */ @@ -6871,9 +6795,8 @@ /** * SECTION:markup - * @Title: Simple XML Subset Parser - * @Short_description: parses a subset of XML - * @See_also: <ulink url="http://www.w3.org/TR/REC-xml/">XML Specification</ulink> + * @Title: Simple XML Subset Parser * @Short_description: parses a subset of XML + * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/) * * The "GMarkup" parser is intended to parse a simple markup format * that's a subset of XML. This is a small, efficient, easy-to-use @@ -6887,31 +6810,34 @@ * * GMarkup is not guaranteed to signal an error on all invalid XML; * the parser may accept documents that an XML parser would not. - * However, XML documents which are not well-formed<footnote - * id="wellformed">Being wellformed is a weaker condition than being - * valid. See the <ulink url="http://www.w3.org/TR/REC-xml/">XML - * specification</ulink> for definitions of these terms.</footnote> - * are not considered valid GMarkup documents. + * However, XML documents which are not well-formed (which is a + * weaker condition than being valid. See the + * [XML specification](http://www.w3.org/TR/REC-xml/) + * for definitions of these terms.) are not considered valid GMarkup + * documents. * * Simplifications to XML include: - * <itemizedlist> - * <listitem>Only UTF-8 encoding is allowed</listitem> - * <listitem>No user-defined entities</listitem> - * <listitem>Processing instructions, comments and the doctype declaration - * are "passed through" but are not interpreted in any way</listitem> - * <listitem>No DTD or validation.</listitem> - * </itemizedlist> + * + * - Only UTF-8 encoding is allowed + * + * - No user-defined entities + * + * - Processing instructions, comments and the doctype declaration + * are "passed through" but are not interpreted in any way + * + * - No DTD or validation * * The markup format does support: - * <itemizedlist> - * <listitem>Elements</listitem> - * <listitem>Attributes</listitem> - * <listitem>5 standard entities: - * <literal>&amp; &lt; &gt; &quot; &apos;</literal> - * </listitem> - * <listitem>Character references</listitem> - * <listitem>Sections marked as CDATA</listitem> - * </itemizedlist> + * + * - Elements + * + * - Attributes + * + * - 5 standard entities: & < > " ' + * + * - Character references + * + * - Sections marked as CDATA */ @@ -6922,25 +6848,23 @@ * * These functions provide support for allocating and freeing memory. * - * <note> * If any call to allocate memory fails, the application is terminated. * This also means that there is no need to check if the call succeeded. - * </note> * - * <note> - * It's important to match g_malloc() with g_free(), plain malloc() with free(), - * and (if you're using C++) new with delete and new[] with delete[]. Otherwise - * bad things can happen, since these allocators may use different memory - * pools (and new/delete call constructors and destructors). See also - * g_mem_set_vtable(). - * </note> + * It's important to match g_malloc() (and wrappers such as g_new()) with + * g_free(), g_slice_alloc() and wrappers such as g_slice_new()) with + * g_slice_free(), plain malloc() with free(), and (if you're using C++) + * new with delete and new[] with delete[]. Otherwise bad things can happen, + * since these allocators may use different memory pools (and new/delete call + * constructors and destructors). See also g_mem_set_vtable(). */ /** * SECTION:memory_slices * @title: Memory Slices - * @short_description: efficient way to allocate groups of equal-sized chunks of memory + * @short_description: efficient way to allocate groups of equal-sized + * chunks of memory * * Memory slices provide a space-efficient and multi-processing scalable * way to allocate equal-sized pieces of memory, just like the original @@ -6949,12 +6873,13 @@ * * To achieve these goals, the slice allocator uses a sophisticated, * layered design that has been inspired by Bonwick's slab allocator - * <footnote><para> - * <ulink url="http://citeseer.ist.psu.edu/bonwick94slab.html">[Bonwick94]</ulink> Jeff Bonwick, The slab allocator: An object-caching kernel + * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html) + * Jeff Bonwick, The slab allocator: An object-caching kernel * memory allocator. USENIX 1994, and - * <ulink url="http://citeseer.ist.psu.edu/bonwick01magazines.html">[Bonwick01]</ulink> Bonwick and Jonathan Adams, Magazines and vmem: Extending the - * slab allocator to many cpu's and arbitrary resources. USENIX 2001 - * </para></footnote>. + * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html) + * Bonwick and Jonathan Adams, Magazines and vmem: Extending the + * slab allocator to many cpu's and arbitrary resources. USENIX 2001) + * * It uses posix_memalign() to optimize allocations of many equally-sized * chunks, and has per-thread free lists (the so-called magazine layer) * to quickly satisfy allocation requests of already known structure sizes. @@ -6969,42 +6894,39 @@ * unlike malloc(), it does not reserve extra space per block. For large block * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the * system malloc() implementation. For newly written code it is recommended - * to use the new <literal>g_slice</literal> API instead of g_malloc() and + * to use the new `g_slice` API instead of g_malloc() and * friends, as long as objects are not resized during their lifetime and the * object size used at allocation time is still available when freeing. * - * <example> - * <title>Using the slice allocator</title> - * <programlisting> + * Here is an example for using the slice allocator: + * |[<!-- language="C" --> * gchar *mem[10000]; * gint i; * - * /* Allocate 10000 blocks. */ - * for (i = 0; i < 10000; i++) + * // Allocate 10000 blocks. + * for (i = 0; i < 10000; i++) * { * mem[i] = g_slice_alloc (50); * - * /* Fill in the memory with some junk. */ - * for (j = 0; j < 50; j++) + * // Fill in the memory with some junk. + * for (j = 0; j < 50; j++) * mem[i][j] = i * j; * } * - * /* Now free all of the blocks. */ - * for (i = 0; i < 10000; i++) - * { - * g_slice_free1 (50, mem[i]); - * } - * </programlisting></example> + * // Now free all of the blocks. + * for (i = 0; i < 10000; i++) + * g_slice_free1 (50, mem[i]); + * ]| * - * <example> - * <title>Using the slice allocator with data structures</title> - * <programlisting> + * And here is an example for using the using the slice allocator + * with data structures: + * |[<!-- language="C" --> * GRealArray *array; * - * /* Allocate one block, using the g_slice_new() macro. */ + * // Allocate one block, using the g_slice_new() macro. * array = g_slice_new (GRealArray); * - * /* We can now use array just like a normal pointer to a structure. */ + * // We can now use array just like a normal pointer to a structure. * array->data = NULL; * array->len = 0; * array->alloc = 0; @@ -7012,16 +6934,17 @@ * array->clear = (clear ? 1 : 0); * array->elt_size = elt_size; * - * /* We can free the block, so it can be reused. */ + * // We can free the block, so it can be reused. * g_slice_free (GRealArray, array); - * </programlisting></example> + * ]| */ /** * SECTION:messages * @title: Message Logging - * @short_description: versatile support for logging messages with different levels of importance + * @short_description: versatile support for logging messages + * with different levels of importance * * These functions provide support for logging error messages * or messages used for debugging. @@ -7053,7 +6976,7 @@ * sign, mantissa and exponent of IEEE floats and doubles. These unions are * defined as appropriate for a given platform. IEEE floats and doubles are * supported (used for storage) by at least Intel, PPC and Sparc. See - * <ulink url="http://en.wikipedia.org/wiki/IEEE_float">IEEE 754-2008</ulink> + * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) * for more information about IEEE number formats. */ @@ -7067,48 +6990,45 @@ * for the popt library. It supports short and long commandline options, * as shown in the following example: * - * <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal> + * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` * * The example demonstrates a number of features of the GOption - * commandline parser - * <itemizedlist><listitem><para> - * Options can be single letters, prefixed by a single dash. Multiple - * short options can be grouped behind a single dash. - * </para></listitem><listitem><para> - * Long options are prefixed by two consecutive dashes. - * </para></listitem><listitem><para> - * Options can have an extra argument, which can be a number, a string or + * commandline parser: + * + * - Options can be single letters, prefixed by a single dash. + * + * - Multiple short options can be grouped behind a single dash. + * + * - Long options are prefixed by two consecutive dashes. + * + * - Options can have an extra argument, which can be a number, a string or * a filename. For long options, the extra argument can be appended with * an equals sign after the option name, which is useful if the extra * argument starts with a dash, which would otherwise cause it to be * interpreted as another option. - * </para></listitem><listitem><para> - * Non-option arguments are returned to the application as rest arguments. - * </para></listitem><listitem><para> - * An argument consisting solely of two dashes turns off further parsing, + * + * - Non-option arguments are returned to the application as rest arguments. + * + * - An argument consisting solely of two dashes turns off further parsing, * any remaining arguments (even those starting with a dash) are returned * to the application as rest arguments. - * </para></listitem></itemizedlist> * * Another important feature of GOption is that it can automatically * generate nicely formatted help output. Unless it is explicitly turned * off with g_option_context_set_help_enabled(), GOption will recognize - * the <option>--help</option>, <option>-?</option>, - * <option>--help-all</option> and - * <option>--help-</option><replaceable>groupname</replaceable> options - * (where <replaceable>groupname</replaceable> is the name of a - * #GOptionGroup) and write a text similar to the one shown in the - * following example to stdout. - * - * <informalexample><screen> + * the `--help`, `-?`, `--help-all` and `--help-groupname` options + * (where `groupname` is the name of a #GOptionGroup) and write a text + * similar to the one shown in the following example to stdout. + * + * |[ * Usage: * testtreemodel [OPTION...] - test tree model performance - * + * * Help Options: * -h, --help Show help options * --help-all Show all help options * --help-gtk Show GTK+ Options - * + * * Application Options: * -r, --repeats=N Average over N repetitions * -m, --max-size=M Test up to 2^M items @@ -7116,9 +7036,9 @@ * -v, --verbose Be verbose * -b, --beep Beep when done * --rand Randomize the data - * </screen></informalexample> + * ]| * - * GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to + * GOption groups options in #GOptionGroups, which makes it easy to * incorporate options from multiple sources. The intended use for this is * to let applications collect option groups from the libraries it uses, * add them to their #GOptionContext, and parse all options by a single call @@ -7132,13 +7052,12 @@ * * Here is a complete example of setting up GOption to parse the example * commandline above and produce the example help output. - * - * <informalexample><programlisting> + * |[<!-- language="C" --> * static gint repeats = 2; * static gint max_size = 8; * static gboolean verbose = FALSE; * static gboolean beep = FALSE; - * static gboolean rand = FALSE; + * static gboolean randomize = FALSE; * * static GOptionEntry entries[] = * { @@ -7146,7 +7065,7 @@ * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, - * { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL }, + * { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, * { NULL } * }; * @@ -7165,28 +7084,78 @@ * exit (1); * } * - * /* ... */ + * ... + * + * } + * ]| + * + * On UNIX systems, the argv that is passed to main() has no particular + * encoding, even to the extent that different parts of it may have + * different encodings. In general, normal arguments and flags will be + * in the current locale and filenames should be considered to be opaque + * byte strings. Proper use of %G_OPTION_ARG_FILENAME vs + * %G_OPTION_ARG_STRING is therefore important. + * + * Note that on Windows, filenames do have an encoding, but using + * #GOptionContext with the argv as passed to main() will result in a + * program that can only accept commandline arguments with characters + * from the system codepage. This can cause problems when attempting to + * deal with filenames containing Unicode characters that fall outside + * of the codepage. + * + * A solution to this is to use g_win32_get_command_line() and + * g_option_context_parse_strv() which will properly handle full Unicode + * filenames. If you are using #GApplication, this is done + * automatically for you. + * + * The following example shows how you can use #GOptionContext directly + * in order to correctly deal with Unicode filenames on Windows: + * + * |[<!-- language="C" --> + * int + * main (int argc, char **argv) + * { + * GError *error = NULL; + * GOptionContext *context; + * gchar **args; + * + * #ifdef G_OS_WIN32 + * args = g_win32_get_command_line (); + * #else + * args = g_strdupv (argv); + * #endif + * + * // set up context + * + * if (!g_option_context_parse_strv (context, &args, &error)) + * { + * // error happened + * } + * + * ... + * + * g_strfreev (args); * + * ... * } - * </programlisting></informalexample> + * ]| */ /** * SECTION:patterns * @title: Glob-style pattern matching - * @short_description: matches strings against patterns containing '*' (wildcard) and '?' (joker) + * @short_description: matches strings against patterns containing '*' + * (wildcard) and '?' (joker) * - * The <function>g_pattern_match*</function> functions match a string + * The g_pattern_match* functions match a string * against a pattern containing '*' and '?' wildcards with similar * semantics as the standard glob() function: '*' matches an arbitrary, * possibly empty, string, '?' matches an arbitrary character. * - * Note that in contrast to glob(), the '/' character - * <emphasis>can</emphasis> be matched by the wildcards, there are no - * '[...]' character ranges and '*' and '?' can - * <emphasis>not</emphasis> be escaped to include them literally in a - * pattern. + * Note that in contrast to glob(), the '/' character can be matched by + * the wildcards, there are no '[...]' character ranges and '*' and '?' + * can not be escaped to include them literally in a pattern. * * When multiple strings must be matched against the same pattern, it * is better to compile the pattern to a #GPatternSpec using @@ -7199,15 +7168,15 @@ /** * SECTION:quarks * @title: Quarks - * @short_description: a 2-way association between a string and a unique integer identifier + * @short_description: a 2-way association between a string and a + * unique integer identifier * * Quarks are associations between strings and integer identifiers. * Given either the string or the #GQuark identifier it is possible to * retrieve the other. * - * Quarks are used for both <link - * linkend="glib-Datasets">Datasets</link> and <link - * linkend="glib-Keyed-Data-Lists">Keyed Data Lists</link>. + * Quarks are used for both [datasets][glib-Datasets] and + * [keyed data lists][glib-Keyed-Data-Lists]. * * To create a new quark from a string, use g_quark_from_string() or * g_quark_from_static_string(). @@ -7237,8 +7206,8 @@ * as #GList to store elements. * * The data contained in each element can be either integer values, by - * using one of the <link linkend="glib-Type-Conversion-Macros">Type - * Conversion Macros</link>, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * * To create a new GQueue, use g_queue_new(). * @@ -7260,41 +7229,49 @@ * @short_description: pseudo-random number generator * * The following functions allow you to use a portable, fast and good - * pseudo-random number generator (PRNG). It uses the Mersenne Twister - * PRNG, which was originally developed by Makoto Matsumoto and Takuji - * Nishimura. Further information can be found at - * <ulink url="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html"> - * http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html</ulink>. - * - * If you just need a random number, you simply call the - * <function>g_random_*</function> functions, which will create a - * globally used #GRand and use the according - * <function>g_rand_*</function> functions internally. Whenever you - * need a stream of reproducible random numbers, you better create a - * #GRand yourself and use the <function>g_rand_*</function> functions - * directly, which will also be slightly faster. Initializing a #GRand - * with a certain seed will produce exactly the same series of random - * numbers on all platforms. This can thus be used as a seed for e.g. - * games. - * - * The <function>g_rand*_range</function> functions will return high - * quality equally distributed random numbers, whereas for example the - * <literal>(g_random_int()%max)</literal> approach often + * pseudo-random number generator (PRNG). + * + * Do not use this API for cryptographic purposes such as key + * generation, nonces, salts or one-time pads. + * + * This PRNG is suitable for non-cryptographic use such as in games + * (shuffling a card deck, generating levels), generating data for + * a test suite, etc. If you need random data for cryptographic + * purposes, it is recommended to use platform-specific APIs such + * as `/dev/random` on UNIX, or CryptGenRandom() on Windows. + * + * GRand uses the Mersenne Twister PRNG, which was originally + * developed by Makoto Matsumoto and Takuji Nishimura. Further + * information can be found at + * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). + * + * If you just need a random number, you simply call the g_random_* + * functions, which will create a globally used #GRand and use the + * according g_rand_* functions internally. Whenever you need a + * stream of reproducible random numbers, you better create a + * #GRand yourself and use the g_rand_* functions directly, which + * will also be slightly faster. Initializing a #GRand with a + * certain seed will produce exactly the same series of random + * numbers on all platforms. This can thus be used as a seed for + * e.g. games. + * + * The g_rand*_range functions will return high quality equally + * distributed random numbers, whereas for example the + * `(g_random_int()\%max)` approach often * doesn't yield equally distributed numbers. * * GLib changed the seeding algorithm for the pseudo-random number - * generator Mersenne Twister, as used by - * <structname>GRand</structname> and <structname>GRandom</structname>. - * This was necessary, because some seeds would yield very bad - * pseudo-random streams. Also the pseudo-random integers generated by - * <function>g_rand*_int_range()</function> will have a slightly better - * equal distribution with the new version of GLib. + * generator Mersenne Twister, as used by #GRand. This was necessary, + * because some seeds would yield very bad pseudo-random streams. + * Also the pseudo-random integers generated by g_rand*_int_range() + * will have a slightly better equal distribution with the new + * version of GLib. * - * The original seeding and generation algorithms, as found in GLib - * 2.0.x, can be used instead of the new ones by setting the - * environment variable <envar>G_RANDOM_VERSION</envar> to the value of - * '2.0'. Use the GLib-2.0 algorithms only if you have sequences of - * numbers generated with Glib-2.0 that you need to reproduce exactly. + * The original seeding and generation algorithms, as found in + * GLib 2.0.x, can be used instead of the new ones by setting the + * environment variable `G_RANDOM_VERSION` to the value of '2.0'. + * Use the GLib-2.0 algorithms only if you have sequences of numbers + * generated with Glib-2.0 that you need to reproduce exactly. */ @@ -7315,18 +7292,16 @@ * * The #GSequence data structure has the API of a list, but is * implemented internally with a balanced binary tree. This means that - * it is possible to maintain a sorted list of n elements in time O(n - * log n). The data contained in each element can be either integer - * values, by using of the <link - * linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>, - * or simply pointers to any type of data. - * - * A #GSequence is accessed through <firstterm>iterators</firstterm>, - * represented by a #GSequenceIter. An iterator represents a position - * between two elements of the sequence. For example, the - * <firstterm>begin</firstterm> iterator represents the gap immediately - * before the first element of the sequence, and the - * <firstterm>end</firstterm> iterator represents the gap immediately + * it is possible to maintain a sorted list of n elements in time O(n log n). + * The data contained in each element can be either integer values, by using + * of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply + * pointers to any type of data. + * + * A #GSequence is accessed through "iterators", represented by a + * #GSequenceIter. An iterator represents a position between two + * elements of the sequence. For example, the "begin" iterator + * represents the gap immediately before the first element of the + * sequence, and the "end" iterator represents the gap immediately * after the last element. In an empty sequence, the begin and end * iterators are the same. * @@ -7339,7 +7314,7 @@ * * The function g_sequence_get() is used with an iterator to access the * element immediately following the gap that the iterator represents. - * The iterator is said to <firstterm>point</firstterm> to that element. + * The iterator is said to "point" to that element. * * Iterators are stable across most operations on a #GSequence. For * example an iterator pointing to some element of a sequence will @@ -7355,8 +7330,6 @@ * SECTION:shell * @title: Shell-related Utilities * @short_description: shell-like commandline handling - * - * */ @@ -7364,8 +7337,6 @@ * SECTION:spawn * @Short_description: process launching * @Title: Spawning Processes - * - * */ @@ -7409,34 +7380,33 @@ * * Note that the functions g_printf(), g_fprintf(), g_sprintf(), * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() - * are declared in the header <filename>gprintf.h</filename> which is - * <emphasis>not</emphasis> included in <filename>glib.h</filename> - * (otherwise using <filename>glib.h</filename> would drag in - * <filename>stdio.h</filename>), so you'll have to explicitly include - * <literal><glib/gprintf.h></literal> in order to use the GLib + * are declared in the header `gprintf.h` which is not included in `glib.h` + * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to + * explicitly include `<glib/gprintf.h>` in order to use the GLib * printf() functions. * - * <para id="string-precision">While you may use the printf() functions - * to format UTF-8 strings, notice that the precision of a - * <literal>%Ns</literal> parameter is interpreted as the - * number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> - * to print. On top of that, the GNU libc implementation of the printf() - * functions has the "feature" that it checks that the string given for - * the <literal>%Ns</literal> parameter consists of a whole number - * of characters in the current encoding. So, unless you are sure you are - * always going to be in an UTF-8 locale or your know your text is restricted - * to ASCII, avoid using <literal>%Ns</literal>. If your intention is - * to format strings for a certain number of columns, then - * <literal>%Ns</literal> is not a correct solution anyway, since it - * fails to take wide characters (see g_unichar_iswide()) into account. - * </para> + * ## String precision pitfalls # {#string-precision} + * + * While you may use the printf() functions to format UTF-8 strings, + * notice that the precision of a \%Ns parameter is interpreted + * as the number of bytes, not characters to print. On top of that, + * the GNU libc implementation of the printf() functions has the + * "feature" that it checks that the string given for the \%Ns + * parameter consists of a whole number of characters in the current + * encoding. So, unless you are sure you are always going to be in an + * UTF-8 locale or your know your text is restricted to ASCII, avoid + * using \%Ns. If your intention is to format strings for a + * certain number of columns, then \%Ns is not a correct solution + * anyway, since it fails to take wide characters (see g_unichar_iswide()) + * into account. */ /** * SECTION:strings * @title: Strings - * @short_description: text buffers which grow automatically as text is added + * @short_description: text buffers which grow automatically + * as text is added * * A #GString is an object that handles the memory management of a C * string for you. The emphasis of #GString is on text, typically @@ -7456,37 +7426,29 @@ * SECTION:testing * @title: Testing * @short_description: a test framework - * @see_also: <link linkend="gtester">gtester</link>, <link linkend="gtester-report">gtester-report</link> + * @see_also: [gtester][gtester], [gtester-report][gtester-report] * * GLib provides a framework for writing and maintaining unit tests * in parallel to the code they are testing. The API is designed according * to established concepts found in the other test frameworks (JUnit, NUnit, * RUnit), which in turn is based on smalltalk unit testing concepts. * - * <variablelist> - * <varlistentry> - * <term>Test case</term> - * <listitem>Tests (test methods) are grouped together with their - * fixture into test cases.</listitem> - * </varlistentry> - * <varlistentry> - * <term>Fixture</term> - * <listitem>A test fixture consists of fixture data and setup and - * teardown methods to establish the environment for the test - * functions. We use fresh fixtures, i.e. fixtures are newly set - * up and torn down around each test invocation to avoid dependencies - * between tests.</listitem> - * </varlistentry> - * <varlistentry> - * <term>Test suite</term> - * <listitem>Test cases can be grouped into test suites, to allow - * subsets of the available tests to be run. Test suites can be - * grouped into other test suites as well.</listitem> - * </varlistentry> - * </variablelist> + * - Test case: Tests (test methods) are grouped together with their + * fixture into test cases. + * + * - Fixture: A test fixture consists of fixture data and setup and + * teardown methods to establish the environment for the test + * functions. We use fresh fixtures, i.e. fixtures are newly set + * up and torn down around each test invocation to avoid dependencies + * between tests. + * + * - Test suite: Test cases can be grouped into test suites, to allow + * subsets of the available tests to be run. Test suites can be + * grouped into other test suites as well. + * * The API is designed to handle creation and registration of test suites * and test cases implicitly. A simple call like - * |[ + * |[<!-- language="C" --> * g_test_add_func ("/misc/assertions", test_assertions); * ]| * creates a test suite called "misc" with a single test case named @@ -7545,7 +7507,8 @@ /** * SECTION:threads * @title: Threads - * @short_description: portable support for threads, mutexes, locks, conditions and thread private data + * @short_description: portable support for threads, mutexes, locks, + * conditions and thread private data * @see_also: #GThreadPool, #GAsyncQueue * * Threads act almost like processes, but unlike processes all threads @@ -7583,54 +7546,46 @@ * Originally, UNIX did not have threads, and therefore some traditional * UNIX APIs are problematic in threaded programs. Some notable examples * are - * <itemizedlist> - * <listitem> - * C library functions that return data in statically allocated - * buffers, such as strtok() or strerror(). For many of these, - * there are thread-safe variants with a _r suffix, or you can - * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). - * </listitem> - * <listitem> - * setenv() and unsetenv() manipulate the process environment in - * a not thread-safe way, and may interfere with getenv() calls - * in other threads. Note that getenv() calls may be - * <quote>hidden</quote> behind other APIs. For example, GNU gettext() - * calls getenv() under the covers. In general, it is best to treat - * the environment as readonly. If you absolutely have to modify the - * environment, do it early in main(), when no other threads are around yet. - * </listitem> - * <listitem> - * setlocale() changes the locale for the entire process, affecting - * all threads. Temporary changes to the locale are often made to - * change the behavior of string scanning or formatting functions - * like scanf() or printf(). GLib offers a number of string APIs - * (like g_ascii_formatd() or g_ascii_strtod()) that can often be - * used as an alternative. Or you can use the uselocale() function - * to change the locale only for the current thread. - * </listitem> - * <listitem> - * fork() only takes the calling thread into the child's copy of the - * process image. If other threads were executing in critical - * sections they could have left mutexes locked which could easily - * cause deadlocks in the new child. For this reason, you should - * call exit() or exec() as soon as possible in the child and only - * make signal-safe library calls before that. - * </listitem> - * <listitem> - * daemon() uses fork() in a way contrary to what is described - * above. It should not be used with GLib programs. - * </listitem> - * </itemizedlist> + * + * - C library functions that return data in statically allocated + * buffers, such as strtok() or strerror(). For many of these, + * there are thread-safe variants with a _r suffix, or you can + * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). + * + * - The functions setenv() and unsetenv() manipulate the process + * environment in a not thread-safe way, and may interfere with getenv() + * calls in other threads. Note that getenv() calls may be hidden behind + * other APIs. For example, GNU gettext() calls getenv() under the + * covers. In general, it is best to treat the environment as readonly. + * If you absolutely have to modify the environment, do it early in + * main(), when no other threads are around yet. + * + * - The setlocale() function changes the locale for the entire process, + * affecting all threads. Temporary changes to the locale are often made + * to change the behavior of string scanning or formatting functions + * like scanf() or printf(). GLib offers a number of string APIs + * (like g_ascii_formatd() or g_ascii_strtod()) that can often be + * used as an alternative. Or you can use the uselocale() function + * to change the locale only for the current thread. + * + * - The fork() function only takes the calling thread into the child's + * copy of the process image. If other threads were executing in critical + * sections they could have left mutexes locked which could easily + * cause deadlocks in the new child. For this reason, you should + * call exit() or exec() as soon as possible in the child and only + * make signal-safe library calls before that. + * + * - The daemon() function uses fork() in a way contrary to what is + * described above. It should not be used with GLib programs. * * GLib itself is internally completely thread-safe (all global data is * automatically locked), but individual data structure instances are * not automatically locked for performance reasons. For example, * you must coordinate accesses to the same #GHashTable from multiple * threads. The two notable exceptions from this rule are #GMainLoop - * and #GAsyncQueue, which <emphasis>are</emphasis> thread-safe and - * need no further application-level locking to be accessed from - * multiple threads. Most refcounting functions such as g_object_ref() - * are also thread-safe. + * and #GAsyncQueue, which are thread-safe and need no further + * application-level locking to be accessed from multiple threads. + * Most refcounting functions such as g_object_ref() are also thread-safe. */ @@ -7693,7 +7648,8 @@ /** * SECTION:trees-binary * @title: Balanced Binary Trees - * @short_description: a sorted collection of key/value pairs optimized for searching and traversing in order + * @short_description: a sorted collection of key/value pairs optimized + * for searching and traversing in order * * The #GTree structure and its associated functions provide a sorted * collection of key/value pairs optimized for searching and traversing @@ -7765,7 +7721,7 @@ * data" to a callback, in the form of a void pointer. From time to time * you want to pass an integer instead of a pointer. You could allocate * an integer, with something like: - * |[ + * |[<!-- language="C" --> * int *ip = g_new (int, 1); * *ip = 42; * ]| @@ -7775,15 +7731,15 @@ * Pointers are always at least 32 bits in size (on all platforms GLib * intends to support). Thus you can store at least 32-bit integer values * in a pointer value. Naively, you might try this, but it's incorrect: - * |[ + * |[<!-- language="C" --> * gpointer p; * int i; * p = (void*) 42; * i = (int) p; * ]| - * Again, that example was <emphasis>not</emphasis> correct, don't copy it. + * Again, that example was not correct, don't copy it. * The problem is that on some systems you need to do this: - * |[ + * |[<!-- language="C" --> * gpointer p; * int i; * p = (void*) (long) 42; @@ -7792,18 +7748,18 @@ * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care * to do the right thing on the every platform. * - * <warning><para>You may not store pointers in integers. This is not - * portable in any way, shape or form. These macros <emphasis>only</emphasis> - * allow storing integers in pointers, and only preserve 32 bits of the - * integer; values outside the range of a 32-bit integer will be mangled. - * </para></warning> + * Warning: You may not store pointers in integers. This is not + * portable in any way, shape or form. These macros only allow storing + * integers in pointers, and only preserve 32 bits of the integer; values + * outside the range of a 32-bit integer will be mangled. */ /** * SECTION:types * @title: Basic Types - * @short_description: standard GLib types, defined for ease-of-use and portability + * @short_description: standard GLib types, defined for ease-of-use + * and portability * * GLib defines a number of commonly used types, which can be divided * into 4 groups: @@ -7828,20 +7784,21 @@ /** * SECTION:unicode * @Title: Unicode Manipulation - * @Short_description: functions operating on Unicode characters and UTF-8 strings + * @Short_description: functions operating on Unicode characters and + * UTF-8 strings * @See_also: g_locale_to_utf8(), g_locale_from_utf8() * * This section describes a number of functions for dealing with - * Unicode characters and strings. There are analogues of the - * traditional <filename>ctype.h</filename> character classification - * and case conversion functions, UTF-8 analogues of some string utility - * functions, functions to perform normalization, case conversion and - * collation on UTF-8 strings and finally functions to convert between - * the UTF-8, UTF-16 and UCS-4 encodings of Unicode. + * Unicode characters and strings. There are analogues of the + * traditional `ctype.h` character classification and case conversion + * functions, UTF-8 analogues of some string utility functions, + * functions to perform normalization, case conversion and collation + * on UTF-8 strings and finally functions to convert between the UTF-8, + * UTF-16 and UCS-4 encodings of Unicode. * * The implementations of the Unicode functions in GLib are based * on the Unicode Character Data tables, which are available from - * <ulink url="http://www.unicode.org/">www.unicode.org</ulink>. + * [www.unicode.org](http://www.unicode.org/). * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1, * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1, * GLib 2.30 supports Unicode 6.0. @@ -7878,15 +7835,16 @@ * * These functions provide support for outputting messages. * - * The <function>g_return</function> family of macros (g_return_if_fail(), - * g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached()) - * should only be used for programming errors, a typical use case is - * checking for invalid parameters at the beginning of a public function. - * They should not be used if you just mean "if (error) return", they - * should only be used if you mean "if (bug in program) return". - * The program behavior is generally considered undefined after one - * of these checks fails. They are not intended for normal control - * flow, only to give a perhaps-helpful warning before giving up. + * The g_return family of macros (g_return_if_fail(), + * g_return_val_if_fail(), g_return_if_reached(), + * g_return_val_if_reached()) should only be used for programming + * errors, a typical use case is checking for invalid parameters at + * the beginning of a public function. They should not be used if + * you just mean "if (error) return", they should only be used if + * you mean "if (bug in program) return". The program behavior is + * generally considered undefined after one of these checks fails. + * They are not intended for normal control flow, only to give a + * perhaps-helpful warning before giving up. */ @@ -7947,43 +7905,45 @@ * * See your C library manual for more details about access(). * - * Returns: zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error. + * Returns: zero if the pathname refers to an existing file system + * object that has all the tested permissions, or -1 otherwise + * or on error. * Since: 2.8 */ /** * g_array_append_val: - * @a: a #GArray. - * @v: the value to append to the #GArray. + * @a: a #GArray + * @v: the value to append to the #GArray * * 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. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_append_vals: - * @array: a #GArray. - * @data: a pointer to the elements to append to the end of the array. - * @len: the number of elements to append. + * @array: a #GArray + * @data: a pointer to the elements to append to the end of the array + * @len: the number of elements to append * * Adds @len elements onto the end of the array. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_free: - * @array: a #GArray. - * @free_segment: if %TRUE the actual element data is freed as well. + * @array: a #GArray + * @free_segment: if %TRUE the actual element data is freed as well * * Frees the memory allocated for the #GArray. If @free_segment is * %TRUE it frees the memory block holding the elements as well and @@ -7993,92 +7953,93 @@ * 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. * - * Returns: the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free(). + * Returns: the element data if @free_segment is %FALSE, otherwise + * %NULL. The element data should be freed using g_free(). */ /** * g_array_get_element_size: - * @array: A #GArray. + * @array: A #GArray * * Gets the size of the elements in @array. * - * Returns: Size of each element, in bytes. + * Returns: Size of each element, in bytes * Since: 2.22 */ /** * g_array_index: - * @a: a #GArray. - * @t: the type of the elements. - * @i: the index of the element to return. + * @a: a #GArray + * @t: the type of the elements + * @i: the index of the element to return * * 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. *<!-- -->/ - * event = &g_array_index (events, EDayViewEvent, 3); - * </programlisting> - * </example> + * // This gets a pointer to the 4th element in the array of + * // EDayViewEvent structs. + * event = &g_array_index (events, EDayViewEvent, 3); + * ]| * - * Returns: the element of the #GArray at the index given by @i. + * Returns: the element of the #GArray at the index given by @i */ /** * g_array_insert_val: - * @a: a #GArray. - * @i: the index to place the element at. - * @v: the value to insert into the array. + * @a: a #GArray + * @i: the index to place the element at + * @v: the value to insert into the array * * 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. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_insert_vals: - * @array: a #GArray. - * @index_: the index to place the elements at. - * @data: a pointer to the elements to insert. - * @len: the number of elements to insert. + * @array: a #GArray + * @index_: the index to place the elements at + * @data: a pointer to the elements to insert + * @len: the number of elements to insert * * Inserts @len elements into a #GArray at the given index. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_new: - * @zero_terminated: %TRUE if the array should have an extra element at the end which is set to 0. - * @clear_: %TRUE if #GArray elements should be automatically cleared to 0 when they are allocated. - * @element_size: the size of each element in bytes. + * @zero_terminated: %TRUE if the array should have an extra element at + * the end which is set to 0 + * @clear_: %TRUE if #GArray elements should be automatically cleared + * to 0 when they are allocated + * @element_size: the size of each element in bytes * * Creates a new #GArray with a reference count of 1. * - * Returns: the new #GArray. + * Returns: the new #GArray */ /** * g_array_prepend_val: - * @a: a #GArray. - * @v: the value to prepend to the #GArray. + * @a: a #GArray + * @v: the value to prepend to the #GArray * * Adds the value on to the start of the array. The array will grow in * size automatically if necessary. @@ -8087,19 +8048,19 @@ * 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. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_prepend_vals: - * @array: a #GArray. - * @data: a pointer to the elements to prepend to the start of the array. - * @len: the number of elements to prepend. + * @array: a #GArray + * @data: a pointer to the elements to prepend to the start of the array + * @len: the number of elements to prepend * * Adds @len elements onto the start of the array. * @@ -8107,58 +8068,58 @@ * existing elements in the array have to be moved to make space for * the new elements. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_ref: - * @array: A #GArray. + * @array: A #GArray * - * 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. * - * Returns: The passed in #GArray. + * Returns: The passed in #GArray * Since: 2.22 */ /** * g_array_remove_index: - * @array: a #GArray. - * @index_: the index of the element to remove. + * @array: a #GArray + * @index_: the index of the element to remove * * Removes the element at the given index from a #GArray. The following * elements are moved down one place. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_remove_index_fast: - * @array: a @GArray. - * @index_: the index of the element to remove. + * @array: a @GArray + * @index_: the index of the element to remove * * Removes the element at the given index from a #GArray. The last * element in the array is used to fill in the space, so this function * does not preserve the order of the #GArray. But it is faster than * g_array_remove_index(). * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_remove_range: - * @array: a @GArray. - * @index_: the index of the first element to remove. - * @length: the number of elements to remove. + * @array: a @GArray + * @index_: the index of the first element to remove + * @length: the number of elements to remove * * Removes the given number of elements starting at the given index * from a #GArray. The following elements are moved to close the gap. * - * Returns: the #GArray. + * Returns: the #GArray * Since: 2.4 */ @@ -8184,36 +8145,38 @@ /** * g_array_set_size: - * @array: a #GArray. - * @length: the new size of the #GArray. + * @array: a #GArray + * @length: the new size of the #GArray * * Sets the size of the array, expanding it if necessary. If the array * was created with @clear_ set to %TRUE, the new elements are set to 0. * - * Returns: the #GArray. + * Returns: the #GArray */ /** * g_array_sized_new: - * @zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared. - * @clear_: %TRUE if all bits in the array should be cleared to 0 on allocation. - * @element_size: size of each element in the array. - * @reserved_size: number of elements preallocated. + * @zero_terminated: %TRUE if the array should have an extra element at + * the end with all bits cleared + * @clear_: %TRUE if all bits in the array should be cleared to 0 on + * allocation + * @element_size: size of each element in the array + * @reserved_size: number of elements preallocated * * Creates a new #GArray with @reserved_size elements preallocated and * a reference count of 1. This avoids frequent reallocation, if you * are going to add many elements to the array. Note however that the * size of the array is still 0. * - * Returns: the new #GArray. + * Returns: the new #GArray */ /** * g_array_sort: - * @array: a #GArray. - * @compare_func: comparison function. + * @array: a #GArray + * @compare_func: comparison function * * Sorts a #GArray using @compare_func which should be a qsort()-style * comparison function (returns less than zero for first arg is less @@ -8226,9 +8189,9 @@ /** * g_array_sort_with_data: - * @array: a #GArray. - * @compare_func: comparison function. - * @user_data: data to pass to @compare_func. + * @array: a #GArray + * @compare_func: comparison function + * @user_data: data to pass to @compare_func * * Like g_array_sort(), but the comparison function receives an extra * user data argument. @@ -8243,7 +8206,7 @@ /** * g_array_unref: - * @array: A #GArray. + * @array: A #GArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, all memory allocated by the array is @@ -8256,14 +8219,14 @@ /** * g_ascii_digit_value: - * @c: an ASCII character. + * @c: an ASCII character * - * 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. * - * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), + * its numeric value. Otherwise, -1. */ @@ -8276,7 +8239,7 @@ * Converts a #gdouble to a string, using the '.' as * decimal point. * - * This functions generates enough precision that converting + * This function generates enough precision that converting * the string back using g_ascii_strtod() gives the same machine-number * (on machines with IEEE compatible 64bit doubles). It is * guaranteed that the size of the resulting string will never @@ -8290,7 +8253,8 @@ * g_ascii_formatd: * @buffer: A buffer to place the resulting string in * @buf_len: The length of the buffer. - * @format: The printf()-style format to use for the code to use for converting. + * @format: The printf()-style format to use for the + * code to use for converting. * @d: The #gdouble to convert * * Converts a #gdouble to a string, using the '.' as @@ -8314,9 +8278,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII alphanumeric character */ @@ -8331,9 +8295,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII alphabetic character */ @@ -8348,9 +8312,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII control character. */ @@ -8363,9 +8327,8 @@ * 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. * * Returns: %TRUE if @c is an ASCII digit. */ @@ -8380,9 +8343,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII printing character other than space. */ @@ -8397,10 +8360,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII lower case letter */ @@ -8415,9 +8377,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII printing character. */ @@ -8432,9 +8394,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII punctuation character. */ @@ -8449,9 +8411,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII white-space character */ @@ -8466,10 +8428,9 @@ * 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. * * Returns: %TRUE if @c is an ASCII upper case letter */ @@ -8482,9 +8443,8 @@ * 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. * * Returns: %TRUE if @c is an ASCII hexadecimal-digit character. */ @@ -8492,8 +8452,8 @@ /** * g_ascii_strcasecmp: - * @s1: string to compare with @s2. - * @s2: string to compare with @s1. + * @s1: string to compare with @s2 + * @s2: string to compare with @s1 * * Compare two strings, ignoring the case of ASCII characters. * @@ -8509,26 +8469,32 @@ * characters include all ASCII letters. If you compare two CP932 * strings using this function, you will get false matches. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. + * Both @s1 and @s2 must be non-%NULL. + * + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. */ /** * g_ascii_strdown: - * @str: a string. - * @len: length of @str in bytes, or -1 if @str is nul-terminated. + * @str: a string + * @len: length of @str in bytes, or -1 if @str is nul-terminated * * Converts all upper case ASCII letters to lower case ASCII letters. * - * Returns: 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.) + * Returns: 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.) */ /** * g_ascii_strncasecmp: - * @s1: string to compare with @s2. - * @s2: string to compare with @s1. - * @n: number of characters to compare. + * @s1: string to compare with @s2 + * @s2: string to compare with @s1 + * @n: number of characters to compare * * Compare @s1 and @s2, ignoring the case of ASCII characters and any * characters after the first @n in each string. @@ -8541,14 +8507,16 @@ * function only on strings known to be in encodings where bytes * corresponding to ASCII letters always represent themselves. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. */ /** * g_ascii_strtod: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * * Converts a string to a #gdouble value. * @@ -8566,12 +8534,12 @@ * 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. * * Returns: the #gdouble value. @@ -8581,7 +8549,8 @@ /** * g_ascii_strtoll: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * @base: to be used for the conversion, 2..36 or 0 * * Converts a string to a #gint64 value. @@ -8596,9 +8565,9 @@ * 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). * @@ -8610,7 +8579,8 @@ /** * g_ascii_strtoull: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * @base: to be used for the conversion, 2..36 or 0 * * Converts a string to a #guint64 value. @@ -8625,9 +8595,9 @@ * 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). * @@ -8638,18 +8608,21 @@ /** * g_ascii_strup: - * @str: a string. - * @len: length of @str in bytes, or -1 if @str is nul-terminated. + * @str: a string + * @len: length of @str in bytes, or -1 if @str is nul-terminated * * Converts all lower case ASCII letters to upper case ASCII letters. * - * Returns: 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.) + * Returns: 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.) */ /** * g_ascii_tolower: - * @c: any character. + * @c: any character * * Convert a character to ASCII lower case. * @@ -8658,16 +8631,17 @@ * 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. * - * Returns: the result of converting @c to lower case. If @c is not an ASCII upper case letter, @c is returned unchanged. + * Returns: the result of converting @c to lower case. If @c is + * not an ASCII upper case letter, @c is returned unchanged. */ /** * g_ascii_toupper: - * @c: any character. + * @c: any character * * Convert a character to ASCII upper case. * @@ -8676,10 +8650,11 @@ * 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. * - * Returns: the result of converting @c to upper case. If @c is not an ASCII lower case letter, @c is returned unchanged. + * Returns: the result of converting @c to upper case. If @c is not + * an ASCII lower case letter, @c is returned unchanged. */ @@ -8692,7 +8667,8 @@ * a char, so there's no worry about sign extension if characters * are signed. * - * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), + * its numeric value. Otherwise, -1. */ @@ -8705,21 +8681,21 @@ * 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. */ /** * g_assert_cmpfloat: * @n1: an floating point number - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another floating point number * - * Debugging macro to terminate the application with a warning - * message if a floating point number comparison fails. + * 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 (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. * @@ -8730,11 +8706,11 @@ /** * g_assert_cmphex: * @n1: an unsigned integer - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * Debugging macro to compare to unsigned integers. * * This is a variant of g_assert_cmpuint() that displays the numbers * in hexadecimal notation in the message. @@ -8746,14 +8722,14 @@ /** * g_assert_cmpint: * @n1: an integer - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another integer * - * Debugging macro to terminate the application with a warning - * message if an integer comparison fails. + * Debugging macro to compare two integers. * - * The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is - * the same as <literal>g_assert (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. * @@ -8764,19 +8740,21 @@ /** * g_assert_cmpstr: * @s1: a string (may be %NULL) - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * - * Debugging macro to terminate the application with a warning - * message if a string comparison fails. The strings are compared - * using g_strcmp0(). + * Debugging macro to compare two strings. If the comparison fails, + * 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 (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"); * ]| * @@ -8787,14 +8765,14 @@ /** * g_assert_cmpuint: * @n1: an unsigned integer - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * - * Debugging macro to terminate the application with a warning - * message if an unsigned integer comparison fails. + * 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 (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. * @@ -8808,32 +8786,47 @@ * @dom: the expected error domain (a #GQuark) * @c: the expected error code * - * Debugging macro to terminate the application with a warning - * message if a method has not returned the correct #GError. + * 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 (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 */ /** + * g_assert_false: + * @expr: the expression to check + * + * Debugging macro to check an expression is false. + * + * If the assertion fails (i.e. the expression is not false), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + +/** * g_assert_no_error: * @err: a #GError, possibly %NULL * - * Debugging macro to terminate the application with a warning - * message if a method has returned a #GError. + * 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 (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. * @@ -8842,6 +8835,22 @@ /** + * g_assert_nonnull: + * @expr: the expression to check + * + * Debugging macro to check an expression is not %NULL. + * + * If the assertion fails (i.e. the expression is %NULL), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.40 + */ + + +/** * g_assert_not_reached: * * Debugging macro to terminate the application if it is ever @@ -8849,7 +8858,39 @@ * 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. + */ + + +/** + * g_assert_null: + * @expr: the expression to check + * + * Debugging macro to check an expression is %NULL. + * + * If the assertion fails (i.e. the expression is not %NULL), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 + */ + + +/** + * g_assert_true: + * @expr: the expression to check + * + * Debugging macro to check that an expression is true. + * + * If the assertion fails (i.e. the expression is not true), + * an error message is logged and the application is either + * terminated or the testcase marked as failed. + * + * See g_test_set_nonfatal_assertions(). + * + * Since: 2.38 */ @@ -8900,8 +8941,8 @@ * 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. */ @@ -9037,7 +9078,9 @@ * * Increases the reference count of the asynchronous @queue by 1. * - * Deprecated: 2.8: Reference counting is done atomically. so g_async_queue_ref() can be used regardless of the @queue's lock. + * Deprecated: 2.8: Reference counting is done atomically. + * so g_async_queue_ref() can be used regardless of the @queue's + * lock. */ @@ -9060,7 +9103,7 @@ * * 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; * @@ -9107,7 +9150,8 @@ * To easily calculate @end_time, a combination of g_get_current_time() * and g_time_val_add() can be used. * - * Returns: data from the queue or %NULL, when no data is received before @end_time. + * Returns: data from the queue or %NULL, when no data is + * received before @end_time. * Deprecated: use g_async_queue_timeout_pop(). */ @@ -9127,7 +9171,8 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is received before @end_time. + * Returns: data from the queue or %NULL, when no data is + * received before @end_time. * Deprecated: use g_async_queue_timeout_pop_unlocked(). */ @@ -9142,7 +9187,8 @@ * * If no data is received before the timeout, %NULL is returned. * - * Returns: data from the queue or %NULL, when no data is received before the timeout. + * Returns: data from the queue or %NULL, when no data is + * received before the timeout. */ @@ -9158,7 +9204,8 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is received before the timeout. + * Returns: data from the queue or %NULL, when no data is + * received before the timeout. */ @@ -9169,7 +9216,8 @@ * Tries to pop data from the @queue. If no data is available, * %NULL is returned. * - * Returns: data from the queue or %NULL, when no data is available immediately. + * Returns: data from the queue or %NULL, when no data is + * available immediately. */ @@ -9182,7 +9230,8 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is available immediately. + * Returns: data from the queue or %NULL, when no data is + * available immediately. */ @@ -9220,7 +9269,9 @@ * the @queue's lock. If the reference count went to 0, the @queue * will be destroyed and the memory allocated will be freed. * - * Deprecated: 2.8: Reference counting is done atomically. so g_async_queue_unref() can be used regardless of the @queue's lock. + * Deprecated: 2.8: Reference counting is done atomically. + * so g_async_queue_unref() can be used regardless of the @queue's + * lock. */ @@ -9271,7 +9322,7 @@ * 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. * @@ -9294,7 +9345,7 @@ * 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; }`. * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 @@ -9313,7 +9364,7 @@ * 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. * @@ -9329,7 +9380,7 @@ * 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. * @@ -9373,8 +9424,7 @@ * * 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. * @@ -9391,7 +9441,7 @@ * 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. * @@ -9423,7 +9473,7 @@ * 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. * @@ -9440,7 +9490,7 @@ * 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. * @@ -9458,7 +9508,7 @@ * 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. * @@ -9479,7 +9529,7 @@ * 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. * @@ -9511,7 +9561,7 @@ * 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. * @@ -9543,7 +9593,7 @@ * 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. * @@ -9557,22 +9607,29 @@ * @text: zero-terminated string with base64 text to decode * @out_len: (out): The length of the decoded data is written here * - * Decode a sequence of Base-64 encoded text into binary data + * Decode a sequence of Base-64 encoded text into binary data. Note + * that the returned binary data is not necessarily zero-terminated, + * so it should not be used as a character string. * - * Returns: (transfer full) (array length=out_len) (element-type guint8): newly allocated buffer containing the binary data that @text represents. The returned buffer must be freed with g_free(). + * Returns: (transfer full) (array length=out_len) (element-type guint8): + * newly allocated buffer containing the binary data + * that @text represents. The returned buffer must + * be freed with g_free(). * Since: 2.12 */ /** * g_base64_decode_inplace: - * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated string with base64 text to decode + * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated + * string with base64 text to decode * @out_len: (inout): The length of the decoded data is written here * * Decode a sequence of Base-64 encoded text into binary data * by overwriting the input data. * - * Returns: (transfer none): The binary data that @text responds. This pointer is the same as the input @text. + * Returns: (transfer none): The binary data that @text responds. This pointer + * is the same as the input @text. * Since: 2.20 */ @@ -9607,7 +9664,9 @@ * Encode a sequence of binary data into its Base-64 stringified * representation. * - * Returns: (transfer full): a newly allocated, zero-terminated Base-64 encoded string representing @data. The returned string must be freed with g_free(). + * Returns: (transfer full): a newly allocated, zero-terminated Base-64 + * encoded string representing @data. The returned string must + * be freed with g_free(). * Since: 2.12 */ @@ -9655,9 +9714,9 @@ * @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. * * Returns: The number of bytes of output that was written * Since: 2.12 @@ -9672,8 +9731,12 @@ * components. It returns a pointer into the given file name * string. * - * Returns: the name of the file without any leading directory components - * Deprecated: 2.2: Use g_path_get_basename() instead, but notice that g_path_get_basename() allocates new memory for the returned string, unlike this function which returns a pointer into the argument. + * Returns: the name of the file without any leading + * directory components + * Deprecated: 2.2: Use g_path_get_basename() instead, but notice + * that g_path_get_basename() allocates new memory for the + * returned string, unlike this function which returns a pointer + * into the argument. */ @@ -9784,7 +9847,8 @@ * g_bookmark_file_add_application: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @name: (allow-none): the name of the application registering the bookmark or %NULL + * @name: (allow-none): the name of the application registering the bookmark + * or %NULL * @exec: (allow-none): command line to be used to launch the bookmark or %NULL * * Adds the application with @name and @exec to the list of @@ -9860,9 +9924,9 @@ * @bookmark: a #GBookmarkFile * @uri: a valid URI * @name: an application's name - * @exec: (allow-none): location for the command line of the application, or %NULL - * @count: (allow-none): return location for the registration count, or %NULL - * @stamp: (allow-none): return location for the last registration time, or %NULL + * @exec: (allow-none) (out): return location for the command line of the application, or %NULL + * @count: (allow-none) (out): return location for the registration count, or %NULL + * @stamp: (allow-none) (out): return location for the last registration time, or %NULL * @error: return location for a #GError, or %NULL * * Gets the registration informations of @app_name for the bookmark for @@ -9888,7 +9952,7 @@ * g_bookmark_file_get_applications: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @length: (allow-none): return location of the length of the returned list, or %NULL + * @length: (allow-none) (out): return location of the length of the returned list, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the names of the applications that have registered the @@ -9897,7 +9961,8 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.12 */ @@ -9913,7 +9978,8 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified URI cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * URI cannot be found. * Since: 2.12 */ @@ -9922,7 +9988,7 @@ * g_bookmark_file_get_groups: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @length: (allow-none): return location for the length of the returned string, or %NULL + * @length: (allow-none) (out): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * Retrieves the list of group names of the bookmark for @uri. @@ -9933,7 +9999,8 @@ * The returned array is %NULL terminated, so @length may optionally * be %NULL. * - * Returns: a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. + * Use g_strfreev() to free it. * Since: 2.12 */ @@ -9942,8 +10009,8 @@ * g_bookmark_file_get_icon: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @href: (allow-none): return location for the icon's location or %NULL - * @mime_type: (allow-none): return location for the icon's MIME type or %NULL + * @href: (allow-none) (out): return location for the icon's location or %NULL + * @mime_type: (allow-none) (out): return location for the icon's MIME type or %NULL * @error: return location for a #GError or %NULL * * Gets the icon of the bookmark for @uri. @@ -9951,7 +10018,8 @@ * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: %TRUE if the icon for the bookmark for the URI was found. You should free the returned strings. + * Returns: %TRUE if the icon for the bookmark for the URI was found. + * You should free the returned strings. * Since: 2.12 */ @@ -9987,7 +10055,8 @@ * event that the MIME type cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. * - * Returns: a newly allocated string or %NULL if the specified URI cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * URI cannot be found. * Since: 2.12 */ @@ -10032,7 +10101,8 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified URI cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * URI cannot be found. * Since: 2.12 */ @@ -10040,13 +10110,14 @@ /** * g_bookmark_file_get_uris: * @bookmark: a #GBookmarkFile - * @length: (allow-none): return location for the number of returned URIs, or %NULL + * @length: (allow-none) (out): return location for the number of returned URIs, or %NULL * * Returns all URIs of the bookmarks in the bookmark file @bookmark. * The array of returned URIs will be %NULL-terminated, so @length may * optionally be %NULL. * - * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.12 */ @@ -10135,7 +10206,8 @@ * g_bookmark_file_load_from_data_dirs: * @bookmark: a #GBookmarkFile * @file: a relative path to a filename to open and parse - * @full_path: (allow-none): return location for a string containing the full path of the file, or %NULL + * @full_path: (allow-none): return location for a string containing the full path + * of the file, or %NULL * @error: return location for a #GError, or %NULL * * This function looks for a desktop bookmark file named @file in the @@ -10304,7 +10376,8 @@ * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark * for @uri is found, one is created. * - * Returns: %TRUE if the application's meta-data was successfully changed. + * Returns: %TRUE if the application's meta-data was successfully + * changed. * Since: 2.12 */ @@ -10445,12 +10518,13 @@ /** * g_bookmark_file_to_data: * @bookmark: a #GBookmarkFile - * @length: (allow-none): return location for the length of the returned string, or %NULL + * @length: (allow-none) (out): return location for the length of the returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @bookmark as a string. * - * Returns: a newly allocated string holding the contents of the #GBookmarkFile + * Returns: a newly allocated string holding + * the contents of the #GBookmarkFile * Since: 2.12 */ @@ -10477,15 +10551,14 @@ * 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 @@ -10530,8 +10603,7 @@ * 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 @@ -10562,28 +10634,29 @@ /** * g_byte_array_append: - * @array: a #GByteArray. - * @data: the byte data to be added. - * @len: the number of bytes to add. + * @array: a #GByteArray + * @data: the byte data to be added + * @len: the number of bytes to add * - * 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. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * g_byte_array_free: - * @array: a #GByteArray. - * @free_segment: if %TRUE the actual byte data is freed as well. + * @array: a #GByteArray + * @free_segment: if %TRUE the actual byte data is freed as well * * Frees the memory allocated by the #GByteArray. If @free_segment is * %TRUE it frees the actual byte data. If the reference count of * @array is greater than one, the #GByteArray wrapper is preserved but * the size of @array will be set to zero. * - * Returns: the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free(). + * Returns: the element data if @free_segment is %FALSE, otherwise + * %NULL. The element data should be freed using g_free(). */ @@ -10601,7 +10674,8 @@ * together. * * Since: 2.32 - * Returns: (transfer full): a new immutable #GBytes representing same byte data that was in the array + * Returns: (transfer full): a new immutable #GBytes representing same + * byte data that was in the array */ @@ -10610,13 +10684,13 @@ * * Creates a new #GByteArray with a reference count of 1. * - * Returns: the new #GByteArray. + * Returns: (transfer full): the new #GByteArray */ /** * g_byte_array_new_take: - * @data: (array length=len): byte data for the array + * @data: (transfer full) (array length=len): byte data for the array * @len: length of @data * * Create byte array containing the data. The data will be owned by the array @@ -10629,97 +10703,97 @@ /** * g_byte_array_prepend: - * @array: a #GByteArray. - * @data: the byte data to be added. - * @len: the number of bytes to add. + * @array: a #GByteArray + * @data: the byte data to be added + * @len: the number of bytes to add * - * 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. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * g_byte_array_ref: - * @array: A #GByteArray. + * @array: A #GByteArray * - * 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. * - * Returns: The passed in #GByteArray. + * Returns: The passed in #GByteArray * Since: 2.22 */ /** * g_byte_array_remove_index: - * @array: a #GByteArray. - * @index_: the index of the byte to remove. + * @array: a #GByteArray + * @index_: the index of the byte to remove * - * 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. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * g_byte_array_remove_index_fast: - * @array: a #GByteArray. - * @index_: the index of the byte to remove. + * @array: a #GByteArray + * @index_: the index of the byte to remove * * Removes the byte at the given index from a #GByteArray. The last * element in the array is used to fill in the space, so this function * does not preserve the order of the #GByteArray. But it is faster * than g_byte_array_remove_index(). * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * g_byte_array_remove_range: - * @array: a @GByteArray. - * @index_: the index of the first byte to remove. - * @length: the number of bytes to remove. + * @array: a @GByteArray + * @index_: the index of the first byte to remove + * @length: the number of bytes to remove * * Removes the given number of bytes starting at the given index from a * #GByteArray. The following elements are moved to close the gap. * - * Returns: the #GByteArray. + * Returns: the #GByteArray * Since: 2.4 */ /** * g_byte_array_set_size: - * @array: a #GByteArray. - * @length: the new size of the #GByteArray. + * @array: a #GByteArray + * @length: the new size of the #GByteArray * * Sets the size of the #GByteArray, expanding it if necessary. * - * Returns: the #GByteArray. + * Returns: the #GByteArray */ /** * g_byte_array_sized_new: - * @reserved_size: number of bytes preallocated. + * @reserved_size: number of bytes preallocated * * Creates a new #GByteArray with @reserved_size bytes preallocated. * This avoids frequent reallocation, if you are going to add many * bytes to the array. Note however that the size of the array is still * 0. * - * Returns: the new #GByteArray. + * Returns: the new #GByteArray */ /** * g_byte_array_sort: - * @array: a #GByteArray. - * @compare_func: comparison function. + * @array: a #GByteArray + * @compare_func: comparison function * * Sorts a byte array, using @compare_func which should be a * qsort()-style comparison function (returns less than zero for first @@ -10736,9 +10810,9 @@ /** * g_byte_array_sort_with_data: - * @array: a #GByteArray. - * @compare_func: comparison function. - * @user_data: data to pass to @compare_func. + * @array: a #GByteArray + * @compare_func: comparison function + * @user_data: data to pass to @compare_func * * Like g_byte_array_sort(), but the comparison function takes an extra * user data argument. @@ -10747,11 +10821,11 @@ /** * g_byte_array_unref: - * @array: A #GByteArray. + * @array: A #GByteArray * * 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 @@ -10767,7 +10841,8 @@ * * This function can be used to sort GBytes instances in lexographical order. * - * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is greater, and zero if bytes2 is equal to bytes1 + * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is + * greater, and zero if bytes2 is equal to bytes1 * Since: 2.32 */ @@ -10797,7 +10872,12 @@ * * This function will always return the same pointer for a given #GBytes. * - * Returns: (array length=size) (type guint8): a pointer to the byte data + * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes + * may represent an empty string with @data non-%NULL and @size as 0. %NULL will + * not be returned if @size is non-zero. + * + * Returns: (transfer none) (array length=size) (type guint8) (allow-none): a pointer to the + * byte data, or %NULL * Since: 2.32 */ @@ -10831,12 +10911,13 @@ /** * g_bytes_new: - * @data: (array length=size): the data to be used for the bytes + * @data: (transfer none) (array length=size) (element-type guint8) (allow-none): + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. * - * @data is copied. + * @data is copied. If @size is 0, @data may be %NULL. * * Returns: (transfer full): a new #GBytes * Since: 2.32 @@ -10861,13 +10942,15 @@ /** - * g_bytes_new_static: - * @data: (array length=size): the data to be used for the bytes + * g_bytes_new_static: (skip) + * @data: (transfer full) (array length=size) (element-type guint8) (allow-none): + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from static data. * - * @data must be static (ie: never modified or freed). + * @data must be static (ie: never modified or freed). It may be %NULL if @size + * is 0. * * Returns: (transfer full): a new #GBytes * Since: 2.32 @@ -10876,7 +10959,8 @@ /** * g_bytes_new_take: - * @data: (transfer full) (array length=size): the data to be used for the bytes + * @data: (transfer full) (array length=size) (element-type guint8) (allow-none): + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. @@ -10890,6 +10974,8 @@ * For creating #GBytes with memory from other allocators, see * g_bytes_new_with_free_func(). * + * @data may be %NULL if @size is 0. + * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ @@ -10897,7 +10983,7 @@ /** * g_bytes_new_with_free_func: - * @data: (array length=size): the data to be used for the bytes + * @data: (array length=size) (allow-none): the data to be used for the bytes * @size: the size of @data * @free_func: the function to call to release the data * @user_data: data to pass to @free_func @@ -10910,6 +10996,8 @@ * @data must not be modified after this call is made until @free_func has * been called to indicate that the bytes is no longer in use. * + * @data may be %NULL if @size is 0. + * * Returns: (transfer full): a new #GBytes * Since: 2.32 */ @@ -10967,7 +11055,8 @@ * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the * data is copied. * - * Returns: (transfer full): a pointer to the same byte data, which should be freed with g_free() + * Returns: (transfer full): a pointer to the same byte data, which should + * be freed with g_free() * Since: 2.32 */ @@ -10994,7 +11083,8 @@ * g_checksum_get_string() or g_checksum_get_digest(), the copied * checksum will be closed as well. * - * Returns: the copy of the passed #GChecksum. Use g_checksum_free() when finished using it. + * Returns: the copy of the passed #GChecksum. Use g_checksum_free() + * when finished using it. * Since: 2.16 */ @@ -11010,10 +11100,11 @@ /** - * g_checksum_get_digest: + * g_checksum_get_digest: (skip) * @checksum: a #GChecksum * @buffer: output buffer - * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. + * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. + * After the call it contains the length of the digest. * * Gets the digest from @checksum as a raw binary vector and places it * into @buffer. The size of the digest depends on the type of checksum. @@ -11036,7 +11127,9 @@ * * The hexadecimal characters will be lower case. * - * Returns: the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed. + * Returns: the hexadecimal representation of the checksum. The + * returned string is owned by the checksum and should not be modified + * or freed. * Since: 2.16 */ @@ -11059,7 +11152,8 @@ * will be closed and it won't be possible to call g_checksum_update() * on it anymore. * - * Returns: the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. + * Returns: (transfer full): the newly created #GChecksum, or %NULL. + * Use g_checksum_free() to free the memory allocated by it. * Since: 2.16 */ @@ -11080,7 +11174,8 @@ * * Gets the length in bytes of digests of type @checksum_type * - * Returns: the checksum length, or -1 if @checksum_type is not supported. + * Returns: the checksum length, or -1 if @checksum_type is + * not supported. * Since: 2.16 */ @@ -11088,7 +11183,7 @@ /** * g_checksum_update: * @checksum: a #GChecksum - * @data: buffer used to compute the checksum + * @data: (array length=length) (element-type guint8): buffer used to compute the checksum * @length: size of the buffer, or -1 if it is a null-terminated string. * * Feeds @data into an existing #GChecksum. The checksum must still be @@ -11101,7 +11196,9 @@ /** * g_child_watch_add: - * @pid: 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). + * @pid: 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). * @function: function to call * @data: data to pass to @function * @@ -11130,9 +11227,11 @@ /** - * g_child_watch_add_full: - * @priority: the priority of the idle source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - * @pid: process 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). + * g_child_watch_add_full: (rename-to g_child_watch_add) + * @priority: the priority of the idle source. Typically this will be in the + * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * @pid: 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). * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the idle is removed, or %NULL @@ -11161,14 +11260,14 @@ * need greater control. * * Returns: the ID (greater than 0) of the event source. - * Rename to: g_child_watch_add * Since: 2.4 */ /** * g_child_watch_source_new: - * @pid: process 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). + * @pid: 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). * * Creates a new child_watch source. * @@ -11177,8 +11276,7 @@ * 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 @@ -11186,9 +11284,13 @@ * 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(-1)</literal> 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). * * Returns: the newly-created child watch source * Since: 2.4 @@ -11211,7 +11313,7 @@ * * See your C library manual for more details about chmod(). * - * Returns: zero if the operation succeeded, -1 on error. + * Returns: 0 if the operation succeeded, -1 on error * Since: 2.8 */ @@ -11249,6 +11351,23 @@ /** + * g_close: + * @fd: A file descriptor + * @error: a #GError + * + * This wraps the close() call; in case of error, %errno will be + * preserved, but the error will also be stored as a #GError in @error. + * + * Besides using #GError, there is another major reason to prefer this + * function over the call provided by the system; on Unix, it will + * attempt to correctly handle %EINTR, which has platform-specific + * semantics. + * + * Since: 2.36 + */ + + +/** * g_compute_checksum_for_bytes: * @checksum_type: a #GChecksumType * @data: binary blob to compute the digest of @@ -11259,7 +11378,8 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the digest of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. + * Returns: the digest of the binary data as a string in hexadecimal. + * The returned string should be freed with g_free() when done using it. * Since: 2.34 */ @@ -11267,7 +11387,7 @@ /** * g_compute_checksum_for_data: * @checksum_type: a #GChecksumType - * @data: binary blob to compute the digest of + * @data: (array length=length) (element-type guint8): binary blob to compute the digest of * @length: length of @data * * Computes the checksum for a binary @data of @length. This is a @@ -11276,7 +11396,8 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the digest of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. + * Returns: the digest of the binary data as a string in hexadecimal. + * The returned string should be freed with g_free() when done using it. * Since: 2.16 */ @@ -11291,7 +11412,8 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the checksum as a hexadecimal string. The returned string should be freed with g_free() when done using it. + * Returns: the checksum as a hexadecimal string. The returned string + * should be freed with g_free() when done using it. * Since: 2.16 */ @@ -11310,7 +11432,8 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it. + * Returns: the HMAC of the binary data as a string in hexadecimal. + * The returned string should be freed with g_free() when done using it. * Since: 2.30 */ @@ -11327,7 +11450,9 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the HMAC as a hexadecimal string. The returned string should be freed with g_free() when done using it. + * Returns: the HMAC as a hexadecimal string. + * The returned string should be freed with g_free() + * when done using it. * Since: 2.30 */ @@ -11396,6 +11521,8 @@ * @mutex: a #GMutex that is currently locked * * Atomically releases @mutex and waits until @cond is signalled. + * When this function returns, @mutex is locked again and owned by the + * calling thread. * * When using condition variables, it is possible that a spurious wakeup * may occur (ie: g_cond_wait() returns even though g_cond_signal() was @@ -11427,10 +11554,10 @@ * 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) * { @@ -11473,32 +11600,66 @@ /** * g_convert: * @str: the string to convert - * @len: 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>. + * @len: the length of the string, or -1 if the string is + * 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) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. - * @bytes_read: (out): location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @bytes_written: (out): the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @bytes_read: (out): location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @bytes_written: (out): the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * 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.) * - * Returns: If the conversion was successful, a newly allocated nul-terminated string, which must be freed with g_free(). Otherwise %NULL and @error will be set. + * Returns: If the conversion was successful, a newly allocated + * nul-terminated string, which must be freed with + * g_free(). Otherwise %NULL and @error will be set. */ /** * g_convert_with_fallback: * @str: the string to convert - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @len: the length of the string, or -1 if the string is + * 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) * @to_codeset: name of character set into which to convert @str * @from_codeset: character set of @str. - * @fallback: UTF-8 string to use in place of character not present in the target encoding. (The string must be representable in the target encoding). If %NULL, characters not in the target encoding will be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. - * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @fallback: UTF-8 string to use in place of character not + * present in the target encoding. (The string must be + * representable in the target encoding). + * If %NULL, characters not in the target encoding will + * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. + * @bytes_written: the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * Converts a string from one character set to another, possibly * including fallback sequences for characters not representable @@ -11508,40 +11669,58 @@ * 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.) * - * Returns: If the conversion was successful, a newly allocated nul-terminated string, which must be freed with g_free(). Otherwise %NULL and @error will be set. + * Returns: If the conversion was successful, a newly allocated + * nul-terminated string, which must be freed with + * g_free(). Otherwise %NULL and @error will be set. */ /** * g_convert_with_iconv: * @str: the string to convert - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @len: the length of the string, or -1 if the string is + * 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) * @converter: conversion descriptor from g_iconv_open() - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @bytes_written: the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * 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.) * - * Returns: If the conversion was successful, a newly allocated nul-terminated string, which must be freed with g_free(). Otherwise %NULL and @error will be set. + * Returns: If the conversion was successful, a newly allocated + * nul-terminated string, which must be freed with + * g_free(). Otherwise %NULL and @error will be set. */ @@ -11570,14 +11749,17 @@ * * See your C library manual for more details about creat(). * - * Returns: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from creat(). + * Returns: a new file descriptor, or -1 if an error occurred. + * The return value can be used exactly like the return value + * from creat(). * Since: 2.8 */ /** * g_critical: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). * It's more or less application-defined what constitutes @@ -11587,8 +11769,12 @@ * 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 + * manually. */ @@ -11662,7 +11848,9 @@ * This function can be useful to avoid races when multiple * threads are using the same datalist and the same key. * - * Returns: the result of calling @dup_func on the value associated with @key_id in @datalist, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. + * Returns: the result of calling @dup_func on the value + * associated with @key_id in @datalist, or %NULL if not set. + * If @dup_func is %NULL, the value is returned unmodified. * Since: 2.34 */ @@ -11722,9 +11910,8 @@ * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * - * Return: %TRUE if the existing value for @key_id was replaced + * Returns: %TRUE if the existing value for @key_id was replaced * by @newval, %FALSE otherwise. - * * Since: 2.34 */ @@ -11733,7 +11920,8 @@ * g_datalist_id_set_data: * @dl: a datalist. * @q: the #GQuark to identify the data element. - * @d: (allow-none): the data element, or %NULL to remove any previous element corresponding to @q. + * @d: (allow-none): the data element, or %NULL to remove any previous element + * corresponding to @q. * * Sets the data corresponding to the given #GQuark id. Any previous * data with the same key is removed, and its destroy function is @@ -11745,8 +11933,13 @@ * g_datalist_id_set_data_full: * @datalist: a datalist. * @key_id: the #GQuark to identify the data element. - * @data: (allow-none): the data element or %NULL to remove any previous element corresponding to @key_id. - * @destroy_func: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @data is %NULL, then @destroy_func must also be %NULL. + * @data: (allow-none): the data element or %NULL to remove any previous element + * corresponding to @key_id. + * @destroy_func: the function to call when the data element is + * removed. This function will be called with the data + * element and can be used to free any memory allocated + * for it. If @data is %NULL, then @destroy_func must + * also be %NULL. * * Sets the data corresponding to the given #GQuark id, and the * function to be called when the element is removed from the datalist. @@ -11787,7 +11980,8 @@ * g_datalist_set_data: * @dl: a datalist. * @k: the string to identify the data element. - * @d: (allow-none): the data element, or %NULL to remove any previous element corresponding to @k. + * @d: (allow-none): the data element, or %NULL to remove any previous element + * corresponding to @k. * * Sets the data element corresponding to the given string identifier. */ @@ -11797,8 +11991,12 @@ * g_datalist_set_data_full: * @dl: a datalist. * @k: the string to identify the data element. - * @d: (allow-none): the data element, or %NULL to remove any previous element corresponding to @k. - * @f: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @d is %NULL, then @f must also be %NULL. + * @d: (allow-none): the data element, or %NULL to remove any previous element + * corresponding to @k. + * @f: the function to call when the data element is removed. This + * function will be called with the data element and can be used to + * free any memory allocated for it. If @d is %NULL, then @f must + * also be %NULL. * * Sets the data element corresponding to the given string identifier, * and the function to be called when the data element is removed. @@ -11808,7 +12006,11 @@ /** * g_datalist_set_flags: * @datalist: pointer to the location that holds a list - * @flags: the flags to turn on. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3; giving two possible boolean flags). A value for @flags that doesn't fit within the mask is an error. + * @flags: the flags to turn on. The values of the flags are + * restricted by %G_DATALIST_FLAGS_MASK (currently + * 3; giving two possible boolean flags). + * A value for @flags that doesn't fit within the mask is + * an error. * * Turns on flag values for a data list. This function is used * to keep a small number of boolean flags in an object with @@ -11824,7 +12026,11 @@ /** * g_datalist_unset_flags: * @datalist: pointer to the location that holds a list - * @flags: the flags to turn off. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3: giving two possible boolean flags). A value for @flags that doesn't fit within the mask is an error. + * @flags: the flags to turn off. The values of the flags are + * restricted by %G_DATALIST_FLAGS_MASK (currently + * 3: giving two possible boolean flags). + * A value for @flags that doesn't fit within the mask is + * an error. * * Turns off flag values for a data list. See g_datalist_unset_flags() * @@ -11861,7 +12067,8 @@ * * Gets the data element corresponding to a string. * - * Returns: the data element corresponding to the string, or %NULL if it is not found. + * Returns: the data element corresponding to the string, or %NULL if + * it is not found. */ @@ -11872,7 +12079,8 @@ * * Gets the data element corresponding to a #GQuark. * - * Returns: the data element corresponding to the #GQuark, or %NULL if it is not found. + * Returns: the data element corresponding to the #GQuark, or %NULL if + * it is not found. */ @@ -11915,7 +12123,10 @@ * @dataset_location: the location identifying the dataset. * @key_id: the #GQuark id to identify the data element. * @data: the data element. - * @destroy_func: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. + * @destroy_func: the function to call when the data element is + * removed. This function will be called with the data + * element and can be used to free any memory allocated + * for it. * * Sets the data element associated with the given #GQuark id, and also * the function to call when the data element is destroyed. Any @@ -11958,7 +12169,9 @@ * @l: the location identifying the dataset. * @k: the string to identify the data element. * @d: the data element. - * @f: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. + * @f: the function to call when the data element is removed. This + * function will be called with the data element and can be used to + * free any memory allocated for it. * * Sets the data corresponding to the given string identifier, and the * function to call when the data element is destroyed. @@ -12035,7 +12248,8 @@ * qsort()-style comparison function for dates. * Both dates must be valid. * - * Returns: 0 for equal, less than zero if @lhs is less than @rhs, greater than zero if @lhs is greater than @rhs + * Returns: 0 for equal, less than zero if @lhs is less than @rhs, + * greater than zero if @lhs is greater than @rhs */ @@ -12231,11 +12445,11 @@ * @year: year to check * * 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. * * Returns: %TRUE if the year is a leap year */ @@ -12338,10 +12552,10 @@ * @str: string to parse * * 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. @@ -12366,14 +12580,14 @@ /** * g_date_set_time_t: * @date: a #GDate - * @timet: <type>time_t</type> value to set + * @timet: time_t value to set * * Sets the value of a date to the date corresponding to a time * 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)); * ]| * @@ -12414,7 +12628,7 @@ * @date: valid #GDate * * 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() @@ -12474,7 +12688,8 @@ * * Creates a copy of @datetime and adds the specified timespan to the copy. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12485,9 +12700,10 @@ * @days: the number of days * * Creates a copy of @datetime and adds the specified number of days to the - * copy. + * copy. Add negative values to subtract days. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12503,9 +12719,10 @@ * @seconds: the number of seconds to add * * Creates a new #GDateTime adding the specified values to the current date and - * time in @datetime. + * time in @datetime. Add negative values to subtract. * - * Returns: the newly created #GDateTime that should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime that should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12515,9 +12732,11 @@ * @datetime: a #GDateTime * @hours: the number of hours to add * - * Creates a copy of @datetime and adds the specified number of hours + * Creates a copy of @datetime and adds the specified number of hours. + * Add negative values to subtract hours. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12528,8 +12747,10 @@ * @minutes: the number of minutes to add * * Creates a copy of @datetime adding the specified number of minutes. + * Add negative values to subtract minutes. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12540,9 +12761,10 @@ * @months: the number of months * * Creates a copy of @datetime and adds the specified number of months to the - * copy. + * copy. Add negative values to subtract months. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12553,8 +12775,10 @@ * @seconds: the number of seconds to add * * Creates a copy of @datetime and adds the specified number of seconds. + * Add negative values to subtract seconds. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12565,9 +12789,10 @@ * @weeks: the number of weeks * * Creates a copy of @datetime and adds the specified number of weeks to the - * copy. + * copy. Add negative values to subtract weeks. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12578,9 +12803,10 @@ * @years: the number of years * * Creates a copy of @datetime and adds the specified number of years to the - * copy. + * copy. Add negative values to subtract years. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12593,7 +12819,8 @@ * A comparison function for #GDateTimes that is suitable * as a #GCompareFunc. Both #GDateTimes must be non-%NULL. * - * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater than @dt2. + * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater + * than @dt2. * Since: 2.26 */ @@ -12605,9 +12832,10 @@ * * Calculates the difference in time between @end and @begin. The * #GTimeSpan that is returned is effectively @end - @begin (ie: - * positive if the first simparameter is larger). + * positive if the first parameter is larger). * - * Returns: the difference between the two #GDateTime, as a time span expressed in microseconds. + * Returns: the difference between the two #GDateTime, as a time + * span expressed in microseconds. * Since: 2.26 */ @@ -12630,7 +12858,8 @@ /** * g_date_time_format: * @datetime: A #GDateTime - * @format: a valid UTF-8 string, containing the format for the #GDateTime + * @format: a valid UTF-8 string, containing the format for the + * #GDateTime * * Creates a newly allocated string representing the requested @format. * @@ -12647,248 +12876,81 @@ * * 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); - * 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); - * 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 - * 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 - * 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 - * 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 - * 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. - * 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 - * the time - * </simpara></listitem></varlistentry> - * <varlistentry><term> - * <literal>\%X</literal>: - * </term><listitem><simpara> - * 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 hour offset from UTC - * </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> + * - \%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 + * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12); + * single digits are preceded by a blank + * - \%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". + * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for + * the current locale + * - \%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 + * - \%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. + * - \%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. + * - \%x: the preferred date representation for the current locale without + * the time + * - \%X: the preferred time representation for the current locale without + * the date + * - \%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> - * - * Returns: a newly allocated string formatted to the requested format or %NULL in the case that there was an error. The string should be freed with g_free(). + * + * - 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. + * + * Returns: a newly allocated string formatted to the requested format + * or %NULL in the case that there was an error. The string + * should be freed with g_free(). * Since: 2.26 */ @@ -13008,7 +13070,9 @@ * months and "EDT" during the summer months when daylight savings * time is in effect. * - * Returns: (transfer none): the time zone abbreviation. The returned string is owned by the #GDateTime and it should not be modified or freed + * Returns: (transfer none): the time zone abbreviation. The returned + * string is owned by the #GDateTime and it should not be + * modified or freed * Since: 2.26 */ @@ -13026,7 +13090,8 @@ * * If @datetime represents UTC time, then the offset is always zero. * - * Returns: the number of microseconds that should be added to UTC to get the local time + * Returns: the number of microseconds that should be added to UTC to + * get the local time * Since: 2.26 */ @@ -13473,12 +13538,11 @@ /** * g_date_to_struct_tm: - * @date: a #GDate to set the <structname>struct tm</structname> from - * @tm: <structname>struct tm</structname> to fill + * @date: a #GDate to set the struct tm from + * @tm: struct tm to fill * - * 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. */ @@ -13565,12 +13629,13 @@ /** * g_dcgettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @msgid: message to translate * @category: a locale category * * 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. * @@ -13581,17 +13646,26 @@ /** * g_debug: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log a debug message. * + * 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. + * + * Such messages are suppressed by the g_log_default_handler() unless + * the G_MESSAGES_DEBUG environment variable is set appropriately. + * * Since: 2.6 */ /** * g_dgettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @msgid: message to translate * * This function is a wrapper of dgettext() which does not translate @@ -13609,17 +13683,19 @@ * * 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, @@ -13640,7 +13716,8 @@ /** * g_dir_make_tmp: - * @tmpl: (type filename) (allow-none): Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template + * @tmpl: (type filename) (allow-none): Template for directory name, + * as in g_mkdtemp(), basename only, or %NULL for a default template * @error: return location for a #GError * * Creates a subdirectory in the preferred directory for temporary @@ -13655,22 +13732,30 @@ * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not * modified, and might thus be a read-only literal string. * - * Returns: (type filename): The actual name used. This string should be freed with g_free() when not needed any longer and is is in the GLib file name encoding. In case of errors, %NULL is returned and @error will be set. + * Returns: (type filename): The actual name used. This string + * should be freed with g_free() when not needed any longer and is + * is in the GLib file name encoding. In case of errors, %NULL is + * returned and @error will be set. * Since: 2.30 */ /** * g_dir_open: - * @path: the path to the directory you are interested in. On Unix in the on-disk encoding. On Windows in UTF-8 + * @path: the path to the directory you are interested in. On Unix + * in the on-disk encoding. On Windows in UTF-8 * @flags: Currently must be set to 0. Reserved for future use. - * @error: return location for a #GError, or %NULL. If non-%NULL, an error will be set if and only if g_dir_open() fails. + * @error: return location for a #GError, or %NULL. + * If non-%NULL, an error will be set if and only if + * g_dir_open() fails. * * Opens a directory for reading. The names of the files in the * directory can then be retrieved using g_dir_read_name(). Note * that the ordering is not defined. * - * Returns: a newly allocated #GDir on success, %NULL on failure. If non-%NULL, you must free the result with g_dir_close() when you are finished with it. + * Returns: a newly allocated #GDir on success, %NULL on failure. + * If non-%NULL, you must free the result with g_dir_close() + * when you are finished with it. */ @@ -13684,8 +13769,7 @@ * 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. @@ -13693,7 +13777,9 @@ * On Windows, as is true of all GLib functions which operate on * filenames, the returned name is in UTF-8. * - * Returns: The entry's name or %NULL if there are no more entries. The return value is owned by GLib and must not be modified or freed. + * Returns: The entry's name or %NULL if there are no + * more entries. The return value is owned by GLib and + * must not be modified or freed. */ @@ -13713,11 +13799,11 @@ * * 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)`. * * Returns: %TRUE if the two keys match. */ @@ -13732,8 +13818,8 @@ * 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)`. * * Returns: a hash value corresponding to the key. */ @@ -13755,7 +13841,8 @@ /** * g_dngettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @msgid: message to translate * @msgid_plural: plural form of the message * @n: the quantity for which translation is needed @@ -13804,8 +13891,10 @@ /** * g_dpgettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() - * @msgctxtid: a combined message context and message id, separated by a \004 character + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() + * @msgctxtid: a combined message context and message id, separated + * by a \004 character * @msgidoffset: the offset of the message id in @msgctxid * * This function is a variant of g_dgettext() which supports @@ -13829,7 +13918,8 @@ /** * g_dpgettext2: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @context: the message context * @msgid: the message * @@ -13851,27 +13941,29 @@ /** * g_environ_getenv: - * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment list (eg, as returned from g_get_environ()), or %NULL for an empty environment list - * @variable: the environment variable to get, in the GLib file name encoding + * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment + * list (eg, as returned from g_get_environ()), or %NULL + * for an empty environment list + * @variable: the environment variable to get, in the GLib file name + * encoding * * Returns the value of the environment variable @variable in the * provided list @envp. * - * The name and value are in the GLib file name encoding. - * On UNIX, this means the actual bytes which might or might not - * be in some consistent character set and encoding. On Windows, - * it is in UTF-8. On Windows, in case the environment variable's - * value contains references to other environment variables, they - * are expanded. - * - * Returns: the value of the environment variable, or %NULL if the environment variable is not set in @envp. The returned string is owned by @envp, and will be freed if @variable is set or unset again. + * Returns: the value of the environment variable, or %NULL if + * the environment variable is not set in @envp. The returned + * string is owned by @envp, and will be freed if @variable is + * set or unset again. * Since: 2.32 */ /** * g_environ_setenv: - * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list + * @envp: (allow-none) (array zero-terminated=1) (transfer full): an + * environment list that can be freed using g_strfreev() (e.g., as + * returned from g_get_environ()), or %NULL for an empty + * environment list * @variable: the environment variable to set, must not contain '=' * @value: the value for to set the variable to * @overwrite: whether to change the variable if it already exists @@ -13879,31 +13971,32 @@ * Sets the environment variable @variable in the provided list * @envp to @value. * - * Both the variable's name and value should be in the GLib - * file name encoding. On UNIX, this means that they can be - * arbitrary byte strings. On Windows, they should be in UTF-8. - * - * Returns: (array zero-terminated=1) (transfer full): the updated environment list. Free it using g_strfreev(). + * Returns: (array zero-terminated=1) (transfer full): the + * updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_environ_unsetenv: - * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list + * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment + * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), + * or %NULL for an empty environment list * @variable: the environment variable to remove, must not contain '=' * * Removes the environment variable @variable from the provided * environment @envp. * - * Returns: (array zero-terminated=1) (transfer full): the updated environment list. Free it using g_strfreev(). + * Returns: (array zero-terminated=1) (transfer full): the + * updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_error: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log an error message. * @@ -13912,6 +14005,10 @@ * result in a core dump; don't use it for errors you expect. * Using this function indicates a bug in your program, i.e. * an assertion failure. + * + * 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. */ @@ -13996,8 +14093,8 @@ * @err_no: an "errno" value * * 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 @@ -14011,7 +14108,8 @@ /** * g_file_get_contents: * @filename: (type filename): name of a file to read contents from, in the GLib file name encoding - * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free the returned string + * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free + * the returned string * @length: (allow-none): location to store length in bytes of the contents, or %NULL * @error: return location for a #GError, or %NULL * @@ -14032,8 +14130,10 @@ /** * g_file_open_tmp: - * @tmpl: (type filename) (allow-none): Template for file name, as in g_mkstemp(), basename only, or %NULL for a default template - * @name_used: (out) (type filename): location to store actual name used, or %NULL + * @tmpl: (type filename) (allow-none): Template for file name, as in + * g_mkstemp(), basename only, or %NULL for a default template + * @name_used: (out) (type filename): location to store actual name used, + * or %NULL * @error: return location for a #GError * * Opens a file for writing in the preferred directory for temporary @@ -14053,7 +14153,10 @@ * when not needed any longer. The returned name is in the GLib file * name encoding. * - * Returns: A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and @error will be set. + * Returns: A file handle (as from open()) to the file opened for + * reading and writing. The file is opened in binary mode on platforms + * where there is a difference. The file handle should be closed with + * close(). In case of errors, -1 is returned and @error will be set. */ @@ -14066,14 +14169,16 @@ * readlink() function. The returned string is in the encoding used * for filenames. Use g_filename_to_utf8() to convert it to UTF-8. * - * Returns: A newly-allocated string with the contents of the symbolic link, or %NULL if an error occurred. + * Returns: A newly-allocated string with the contents of the symbolic link, + * or %NULL if an error occurred. * Since: 2.4 */ /** * g_file_set_contents: - * @filename: (type filename): name of a file to write @contents to, in the GLib file name encoding + * @filename: (type filename): name of a file to write @contents to, in the GLib file name + * encoding * @contents: (array length=length) (element-type guint8): string to write to the file * @length: length of @contents, or -1 if @contents is a nul-terminated string * @error: return location for a #GError, or %NULL @@ -14083,24 +14188,19 @@ * * 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. - * 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 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. + * + * - 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. @@ -14120,11 +14220,11 @@ * @test: bitfield of #GFileTest flags * * 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 @@ -14139,12 +14239,12 @@ * 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 * } * ]| * @@ -14159,7 +14259,7 @@ * %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. * * Returns: whether a test was %TRUE */ @@ -14186,7 +14286,8 @@ * This function is preferred over g_filename_display_name() if you know the * whole path, as it allows translation. * - * Returns: a newly allocated string containing a rendition of the basename of the filename in valid UTF-8 + * Returns: a newly allocated string containing + * a rendition of the basename of the filename in valid UTF-8 * Since: 2.6 */ @@ -14211,7 +14312,8 @@ * g_filename_display_basename(), since that allows location-based * translation of filenames. * - * Returns: a newly allocated string containing a rendition of the filename in valid UTF-8 + * Returns: a newly allocated string containing + * a rendition of the filename in valid UTF-8 * Since: 2.6 */ @@ -14219,58 +14321,89 @@ /** * g_filename_from_uri: * @uri: a uri describing a filename (escaped, encoded in ASCII). - * @hostname: (allow-none): Location to store hostname for the URI, or %NULL. If there is no hostname in the URI, %NULL will be stored in this location. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @hostname: (out) (allow-none): Location to store hostname for the URI, or %NULL. + * If there is no hostname in the URI, %NULL will be + * stored in this location. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * Converts an escaped ASCII-encoded URI to a local filename in the * encoding used for filenames. * - * Returns: a newly-allocated string holding the resulting filename, or %NULL on an error. + * Returns: (type filename): a newly-allocated string holding + * the resulting filename, or %NULL on an error. */ /** * g_filename_from_utf8: * @utf8string: a UTF-8 encoded string. - * @len: the length of the string, or -1 if the string is nul-terminated. - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @len: the length of the string, or -1 if the string is + * nul-terminated. + * @bytes_read: (out) (allow-none): location to store the number of bytes in + * the input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @bytes_written: (out): the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * 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]. * - * Returns: The converted string, or %NULL on an error. + * Returns: (array length=bytes_written) (element-type guint8) (transfer full): + * The converted string, or %NULL on an error. */ /** * g_filename_to_uri: - * @filename: an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows + * @filename: an absolute filename specified in the GLib file name encoding, + * which is the on-disk file name bytes on Unix, and UTF-8 on + * Windows * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * Converts an absolute filename to an escaped ASCII-encoded URI, with the path * component following Section 3.3. of RFC 2396. * - * Returns: a newly-allocated string holding the resulting URI, or %NULL on an error. + * Returns: a newly-allocated string holding the resulting + * URI, or %NULL on an error. */ /** * g_filename_to_utf8: * @opsysstring: a string in the encoding for filenames - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @len: the length of the string, or -1 if the string is + * 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) + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @bytes_written: the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * 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]. * * Returns: The converted string, or %NULL on an error. */ @@ -14285,18 +14418,18 @@ * with the absolute path name, or %NULL if the program is not found in * the path. If @program is already an absolute path, returns a copy of * @program if @program exists and is executable, and %NULL otherwise. - * + * * 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. * * Returns: a newly-allocated string with the absolute path, or %NULL */ @@ -14311,16 +14444,16 @@ * 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(). * - * Returns: A <type>FILE</type> pointer if the file was successfully opened, or %NULL if an error occurred + * Returns: A FILE* if the file was successfully opened, or %NULL if + * an error occurred * Since: 2.6 */ @@ -14341,7 +14474,8 @@ * See g_format_size_full() for more options about how the size might be * formatted. * - * Returns: a newly-allocated formatted string containing a human readable file size + * Returns: a newly-allocated formatted string containing a human readable + * file size * Since: 2.30 */ @@ -14360,9 +14494,11 @@ * * This string should be freed with g_free() when not needed any longer. * - * Returns: a newly-allocated formatted string containing a human readable file size + * Returns: a newly-allocated formatted string containing a human + * readable file size * Since: 2.16 - * Deprecated: 2.30: This function is broken due to its use of SI suffixes to denote IEC units. Use g_format_size() instead. + * Deprecated: 2.30: This function is broken due to its use of SI + * suffixes to denote IEC units. Use g_format_size() instead. */ @@ -14376,7 +14512,8 @@ * This function is similar to g_format_size() but allows for flags * that modify the output. See #GFormatSizeFlags. * - * Returns: a newly-allocated formatted string containing a human readable file size + * Returns: a newly-allocated formatted string containing a human + * readable file size * Since: 2.30 */ @@ -14384,7 +14521,8 @@ /** * g_fprintf: * @file: the stream to write to. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -14397,7 +14535,7 @@ /** * g_free: - * @mem: the memory to free + * @mem: (allow-none): the memory to free * * Frees the memory pointed to by @mem. * If @mem is %NULL it simply returns. @@ -14407,7 +14545,7 @@ /** * g_freopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be opened + * @mode: a string describing the mode in which the file should be opened * @stream: (allow-none): an existing stream which will be reused, or %NULL * * A wrapper for the POSIX freopen() function. The freopen() function @@ -14415,7 +14553,8 @@ * * See your C library manual for more details about freopen(). * - * Returns: A <literal>FILE</literal> pointer if the file was successfully opened, or %NULL if an error occurred. + * Returns: A FILE* if the file was successfully opened, or %NULL if + * an error occurred. * Since: 2.6 */ @@ -14440,11 +14579,10 @@ * g_get_charset: * @charset: return location for character set name * - * 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 @@ -14467,7 +14605,8 @@ * * Gets the character set for the current locale. * - * Returns: a newly allocated string containing the name of the character set. This string must be freed with g_free(). + * Returns: a newly allocated string containing the name + * of the character set. This string must be freed with g_free(). */ @@ -14480,6 +14619,11 @@ * The encoding of the returned string is system defined. * On Windows, it is always UTF-8. * + * Since GLib 2.40, this function will return the value of the "PWD" + * environment variable if it is set and it happens to be the same as + * the current directory. This can make a difference in the case that + * the current directory is the target of a symbolic link. + * * Returns: the current directory */ @@ -14508,7 +14652,8 @@ * The return value is freshly allocated and it should be freed with * g_strfreev() when it is no longer needed. * - * Returns: (array zero-terminated=1) (transfer full): the list of environment variables + * Returns: (array zero-terminated=1) (transfer full): the list of + * environment variables * Since: 2.28 */ @@ -14523,24 +14668,23 @@ * 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. * * Returns: %TRUE if the filename encoding is UTF-8. @@ -14551,31 +14695,26 @@ /** * g_get_home_dir: * - * Gets the current user's home directory as defined in the - * password database. + * Gets the current user's home directory. * - * Note that in contrast to traditional UNIX tools, this function - * prefers <filename>passwd</filename> entries over the <envar>HOME</envar> - * environment variable. + * As with most UNIX tools, this function will return the value of the + * `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. * - * One of the reasons for this decision is that applications in many - * cases need special handling to deal with the case where - * <envar>HOME</envar> is - * <simplelist> - * <member>Not owned by the user</member> - * <member>Not writeable</member> - * <member>Not even readable</member> - * </simplelist> - * Since applications are in general <emphasis>not</emphasis> written - * to deal with these situations it was considered better to make - * g_get_home_dir() not pay attention to <envar>HOME</envar> and to - * return the real home directory for the user. If applications - * want to pay attention to <envar>HOME</envar>, they can do: - * |[ - * const char *homedir = g_getenv ("HOME"); - * if (!homedir) - * homedir = g_get_home_dir (<!-- -->); - * ]| + * 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 `HOME` environment variable yourself + * or unset it before calling any functions in GLib. * * Returns: the current user's home directory */ @@ -14613,11 +14752,12 @@ * 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. * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed. + * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib + * that must not be modified or freed. * Since: 2.6 */ @@ -14634,10 +14774,12 @@ * 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(). * - * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly allocated array of newly allocated strings with the locale variants. Free with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly + * allocated array of newly allocated strings with the locale variants. Free with + * g_strfreev(). * Since: 2.28 */ @@ -14647,12 +14789,12 @@ * * Queries the system monotonic time, if available. * - * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call + * On POSIX systems with clock_gettime() and `CLOCK_MONOTONIC` 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). * - * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does + * It's important to note that POSIX `CLOCK_MONOTONIC` does * not count time spent while the machine is suspended. * * On Windows, "limitations of the OS kernel" is a rather substantial @@ -14668,25 +14810,40 @@ /** + * g_get_num_processors: + * + * Determine the approximate number of threads that the system will + * schedule simultaneously for this process. This is intended to be + * used as a parameter to g_thread_pool_new() for CPU bound tasks and + * similar cases. + * + * Returns: Number of schedulable threads, always greater than 0 + * Since: 2.36 + */ + + +/** * g_get_prgname: * - * 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]. * - * Returns: the name of the program. The returned string belongs to GLib and must not be modified or freed. + * Returns: the name of the program. The returned string belongs + * to GLib and must not be modified or freed. */ /** * g_get_real_name: * - * 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. * * Returns: the user's real name. @@ -14717,10 +14874,10 @@ * 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. @@ -14729,7 +14886,8 @@ * of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. * This information will not roam and is available to anyone using the computer. * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed. + * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must + * not be modified or freed. * Since: 2.6 */ @@ -14740,9 +14898,9 @@ * 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 @@ -14767,7 +14925,8 @@ * Note that on Windows the returned list can vary depending on where * this function is called. * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed. + * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must + * not be modified or freed. * Since: 2.6 */ @@ -14775,12 +14934,20 @@ /** * g_get_tmp_dir: * - * Gets the directory to use for temporary files. This is found from - * inspecting the environment variables <envar>TMPDIR</envar>, - * <envar>TMP</envar>, and <envar>TEMP</envar> in that order. If none - * of those are defined "/tmp" is returned on UNIX and "C:\" on Windows. + * Gets the directory to use for temporary files. + * + * 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 `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. + * it is always UTF-8. The return value is never %NULL or the empty + * string. * * Returns: the directory to use for temporary files. */ @@ -14792,9 +14959,9 @@ * 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 @@ -14802,7 +14969,8 @@ * C:\Documents and Settings\username\Local Settings\Temporary Internet Files. * See documentation for CSIDL_INTERNET_CACHE. * - * Returns: a string owned by GLib that must not be modified or freed. + * Returns: a string owned by GLib that must not be modified + * or freed. * Since: 2.6 */ @@ -14813,17 +14981,18 @@ * 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 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_data_dir() returns. * - * Returns: a string owned by GLib that must not be modified or freed. + * Returns: a string owned by GLib that must not be modified + * or freed. * Since: 2.6 */ @@ -14834,17 +15003,18 @@ * 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 * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_config_dir() returns. * - * Returns: a string owned by GLib that must not be modified or freed. + * Returns: a string owned by GLib that must not be modified + * or freed. * Since: 2.6 */ @@ -14867,10 +15037,11 @@ * 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(). * @@ -14890,23 +15061,26 @@ * * 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 * will not reflect any change once the special directories are loaded. * - * Returns: the path to the specified special directory, or %NULL if the logical id was not found. The returned string is owned by GLib and should not be modified or freed. + * Returns: the path to the specified special directory, or %NULL + * if the logical id was not found. The returned string is owned by + * GLib and should not be modified or freed. * Since: 2.14 */ /** * g_getenv: - * @variable: the environment variable to get, in the GLib file name encoding + * @variable: the environment variable to get, in the GLib file name + * encoding * * Returns the value of an environment variable. * @@ -14916,7 +15090,10 @@ * On Windows, in case the environment variable's value contains * references to other environment variables, they are expanded. * - * Returns: the value of the environment variable, or %NULL if the environment variable is not found. The returned string may be overwritten by the next call to g_getenv(), g_setenv() or g_unsetenv(). + * Returns: the value of the environment variable, or %NULL if + * the environment variable is not found. The returned string + * may be overwritten by the next call to g_getenv(), g_setenv() + * or g_unsetenv(). */ @@ -14933,6 +15110,7 @@ * corresponding value it is able to be stored more efficiently. See * the discussion in the section description. * + * Returns: %TRUE if the key did not exist yet * Since: 2.32 */ @@ -14981,7 +15159,9 @@ * (keep in mind that an O(n) find/foreach operation issued for all n * values in a hash table ends up needing O(n*n) operations). * - * Returns: (allow-none): The value of the first key/value pair is returned, for which @predicate evaluates to %TRUE. If no pair with the requested property is found, %NULL is returned. + * Returns: (allow-none): The value of the first key/value pair is returned, + * for which @predicate evaluates to %TRUE. If no pair with the + * requested property is found, %NULL is returned. * Since: 2.4 */ @@ -15054,22 +15234,53 @@ * g_hash_table_get_keys: * @hash_table: a #GHashTable * - * Retrieves every key inside @hash_table. The returned data - * is valid until @hash_table is modified. + * Retrieves every key inside @hash_table. The returned data is valid + * until changes to the hash release those keys. * - * Returns: a #GList containing all the keys inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. + * Returns: a #GList containing all the keys inside the hash + * table. The content of the list is owned by the hash table and + * should not be modified or freed. Use g_list_free() when done + * using the list. * Since: 2.14 */ /** + * g_hash_table_get_keys_as_array: + * @hash_table: a #GHashTable + * @length: (out): the length of the returned array + * + * Retrieves every key inside @hash_table, as an array. + * + * The returned array is %NULL-terminated but may contain %NULL as a + * key. Use @length to determine the true length if it's possible that + * %NULL was used as the value for a key. + * + * Note: in the common case of a string-keyed #GHashTable, the return + * value of this function can be conveniently cast to (gchar **). + * + * You should always free the return result with g_free(). In the + * above-mentioned case of a string-keyed hash table, it may be + * appropriate to use g_strfreev() if you call g_hash_table_steal_all() + * first to transfer ownership of the keys. + * + * Returns: (array length=length) (transfer container): a + * %NULL-terminated array containing each key from the table. + * Since: 2.40 + */ + + +/** * g_hash_table_get_values: * @hash_table: a #GHashTable * * Retrieves every value inside @hash_table. The returned data * is valid until @hash_table is modified. * - * Returns: a #GList containing all the values inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list. + * Returns: a #GList containing all the values inside the hash + * table. The content of the list is owned by the hash table and + * should not be modified or freed. Use g_list_free() when done + * using the list. * Since: 2.14 */ @@ -15088,6 +15299,8 @@ * value is freed using that function. If you supplied a * @key_destroy_func when creating the #GHashTable, the passed * key is freed using that function. + * + * Returns: %TRUE if the key did not exist yet */ @@ -15110,14 +15323,14 @@ * 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 * } * ]| * @@ -15250,8 +15463,12 @@ * g_hash_table_new_full: * @hash_func: a function to create a hash value from a key * @key_equal_func: a function to check two keys for equality - * @key_destroy_func: (allow-none): a function to free the memory allocated for the key used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. - * @value_destroy_func: (allow-none): a function to free the memory allocated for the value used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. + * @key_destroy_func: (allow-none): a function to free the memory allocated for the key + * used when removing the entry from the #GHashTable, or %NULL + * if you don't want to supply such a function. + * @value_destroy_func: (allow-none): a function to free the memory allocated for the + * value used when removing the entry from the #GHashTable, or %NULL + * if you don't want to supply such a function. * * Creates a new #GHashTable like g_hash_table_new() with a reference * count of 1 and allows to specify functions to free the memory @@ -15318,6 +15535,8 @@ * the #GHashTable, the old value is freed using that function. * If you supplied a @key_destroy_func when creating the * #GHashTable, the old key is freed using that function. + * + * Returns: %TRUE of the key did not exist yet */ @@ -15384,7 +15603,8 @@ * g_hmac_get_string() or g_hmac_get_digest(), the copied * HMAC will be closed as well. * - * Returns: the copy of the passed #GHmac. Use g_hmac_unref() when finished using it. + * Returns: the copy of the passed #GHmac. Use g_hmac_unref() + * when finished using it. * Since: 2.30 */ @@ -15393,7 +15613,8 @@ * g_hmac_get_digest: * @hmac: a #GHmac * @buffer: output buffer - * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest + * @digest_len: an inout parameter. The caller initializes it to the + * size of @buffer. After the call it contains the length of the digest * * Gets the digest from @checksum as a raw binary array and places it * into @buffer. The size of the digest depends on the type of checksum. @@ -15416,7 +15637,9 @@ * * The hexadecimal characters will be lower case. * - * Returns: the hexadecimal representation of the HMAC. The returned string is owned by the HMAC and should not be modified or freed. + * Returns: the hexadecimal representation of the HMAC. The + * returned string is owned by the HMAC and should not be modified + * or freed. * Since: 2.30 */ @@ -15441,7 +15664,8 @@ * will be closed and it won't be possible to call g_hmac_update() * on it anymore. * - * Returns: the newly created #GHmac, or %NULL. Use g_hmac_unref() to free the memory allocated by it. + * Returns: the newly created #GHmac, or %NULL. + * Use g_hmac_unref() to free the memory allocated by it. * Since: 2.30 */ @@ -15516,7 +15740,7 @@ * Compares the ids of two #GHook elements, returning a negative value * if the second id is greater than the first. * - * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook + * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook */ @@ -15544,8 +15768,10 @@ /** * g_hook_find: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped - * @func: the function to call for each #GHook, which should return %TRUE when the #GHook has been found + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped + * @func: the function to call for each #GHook, which should return + * %TRUE when the #GHook has been found * @data: the data to pass to @func * * Finds a #GHook in a #GHookList using the given function to @@ -15558,44 +15784,52 @@ /** * g_hook_find_data: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped * @data: the data to find * * Finds a #GHook in a #GHookList with the given data. * - * Returns: the #GHook with the given @data or %NULL if no matching #GHook is found + * Returns: the #GHook with the given @data or %NULL if no matching + * #GHook is found */ /** * g_hook_find_func: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped * @func: the function to find * * Finds a #GHook in a #GHookList with the given function. * - * Returns: the #GHook with the given @func or %NULL if no matching #GHook is found + * Returns: the #GHook with the given @func or %NULL if no matching + * #GHook is found */ /** * g_hook_find_func_data: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped * @func: the function to find * @data: the data to find * * Finds a #GHook in a #GHookList with the given function and data. * - * Returns: the #GHook with the given @func and @data or %NULL if no matching #GHook is found + * Returns: the #GHook with the given @func and @data or %NULL if + * no matching #GHook is found */ /** * g_hook_first_valid: * @hook_list: a #GHookList - * @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_be_in_call: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * * Returns the first #GHook in a #GHookList which has not been destroyed. * The reference count for the #GHook is incremented, so you must call @@ -15658,7 +15892,8 @@ /** * g_hook_list_init: * @hook_list: a #GHookList - * @hook_size: the size of each element in the #GHookList, typically <literal>sizeof (GHook)</literal> + * @hook_size: the size of each element in the #GHookList, + * typically `sizeof (GHook)`. * * Initializes a #GHookList. * This must be called before the #GHookList is used. @@ -15668,7 +15903,9 @@ /** * g_hook_list_invoke: * @hook_list: a #GHookList - * @may_recurse: %TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if functions which are already running + * (e.g. in another thread) can be called. If set to %FALSE, + * these are skipped * * Calls all of the #GHook functions in a #GHookList. */ @@ -15677,7 +15914,9 @@ /** * g_hook_list_invoke_check: * @hook_list: a #GHookList - * @may_recurse: %TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if functions which are already running + * (e.g. in another thread) can be called. If set to %FALSE, + * these are skipped * * Calls all of the #GHook functions in a #GHookList. * Any function which returns %FALSE is removed from the #GHookList. @@ -15687,7 +15926,9 @@ /** * g_hook_list_marshal: * @hook_list: a #GHookList - * @may_recurse: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * @marshaller: the function to call for each #GHook * @marshal_data: data to pass to @marshaller * @@ -15698,7 +15939,9 @@ /** * g_hook_list_marshal_check: * @hook_list: a #GHookList - * @may_recurse: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * @marshaller: the function to call for each #GHook * @marshal_data: data to pass to @marshaller * @@ -15711,7 +15954,9 @@ * g_hook_next_valid: * @hook_list: a #GHookList * @hook: the current #GHook - * @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_be_in_call: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * * Returns the next #GHook in a #GHookList which has not been destroyed. * The reference count for the #GHook is incremented, so you must call @@ -15766,7 +16011,8 @@ * segments, and so it is possible for g_hostname_is_non_ascii() and * g_hostname_is_ascii_encoded() to both return %TRUE for a name. * - * Returns: %TRUE if @hostname contains any ASCII-encoded segments. + * Returns: %TRUE if @hostname contains any ASCII-encoded + * segments. * Since: 2.22 */ @@ -15808,7 +16054,8 @@ * string containing no uppercase letters and not ending with a * trailing dot. * - * Returns: an ASCII hostname, which must be freed, or %NULL if @hostname is in some way invalid. + * Returns: an ASCII hostname, which must be freed, or %NULL if + * @hostname is in some way invalid. * Since: 2.22 */ @@ -15825,7 +16072,8 @@ * Of course if @hostname is not an internationalized hostname, then * the canonical presentation form will be entirely ASCII. * - * Returns: a UTF-8 hostname, which must be freed, or %NULL if @hostname is in some way invalid. + * Returns: a UTF-8 hostname, which must be freed, or %NULL if + * @hostname is in some way invalid. * Since: 2.22 */ @@ -15898,7 +16146,8 @@ * GLib provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * - * Returns: a "conversion descriptor", or (GIConv)-1 if opening the converter failed. + * Returns: a "conversion descriptor", or (GIConv)-1 if + * opening the converter failed. */ @@ -15922,8 +16171,9 @@ /** - * g_idle_add_full: - * @priority: the priority of the idle source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * g_idle_add_full: (rename-to g_idle_add) + * @priority: the priority of the idle source. Typically this will be in the + * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the idle is removed, or %NULL @@ -15937,7 +16187,6 @@ * You can do these steps manually if you need greater control. * * Returns: the ID (greater than 0) of the event source. - * Rename to: g_idle_add */ @@ -15967,6 +16216,24 @@ /** + * g_info: + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) + * + * A convenience function/macro to log an informational message. Seldom used. + * + * 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. + * + * Such messages are suppressed by the g_log_default_handler() unless + * the G_MESSAGES_DEBUG environment variable is set appropriately. + * + * Since: 2.40 + */ + + +/** * g_int64_equal: * @v1: a pointer to a #gint64 key * @v2: a pointer to a #gint64 key to compare with @v1 @@ -16008,9 +16275,9 @@ * 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. * * Returns: %TRUE if the two keys match. */ @@ -16024,9 +16291,9 @@ * 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. * * Returns: a hash value corresponding to the key. */ @@ -16074,7 +16341,7 @@ /** - * g_io_add_watch_full: + * g_io_add_watch_full: (rename-to g_io_add_watch) * @channel: a #GIOChannel * @priority: the priority of the #GIOChannel source * @condition: the condition to watch for @@ -16090,7 +16357,6 @@ * You can do these steps manually if you need greater control. * * Returns: the event source id - * Rename to: g_io_add_watch */ @@ -16108,19 +16374,18 @@ /** * g_io_channel_error_from_errno: - * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal> + * @en: an `errno` error number, e.g. `EINVAL` * - * Converts an <literal>errno</literal> error number to a #GIOChannelError. + * Converts an `errno` error number to a #GIOChannelError. * - * Returns: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. + * Returns: a #GIOChannelError error number, e.g. + * %G_IO_CHANNEL_ERROR_INVAL. */ /** * g_io_channel_error_quark: * - * - * * Returns: the quark used as %G_IO_CHANNEL_ERROR */ @@ -16132,7 +16397,9 @@ * * Flushes the write buffer for the GIOChannel. * - * Returns: the status of the operation: One of #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or #G_IO_STATUS_ERROR. + * Returns: the status of the operation: One of + * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or + * #G_IO_STATUS_ERROR. */ @@ -16177,7 +16444,8 @@ * destroyed. The default value of this is %TRUE for channels created * by g_io_channel_new_file (), and %FALSE for all other channels. * - * Returns: Whether the channel will be closed on the final unref of the GIOChannel data structure. + * Returns: Whether the channel will be closed on the final unref of + * the GIOChannel data structure. */ @@ -16189,7 +16457,8 @@ * The internal encoding is always UTF-8. The encoding %NULL * makes the channel safe for binary data. * - * Returns: A string containing the encoding, this string is owned by GLib and must not be freed. + * Returns: A string containing the encoding, this string is + * owned by GLib and must not be freed. */ @@ -16220,7 +16489,8 @@ * where in the file a line break occurs. A value of %NULL * indicates autodetection. * - * Returns: The line termination string. This value is owned by GLib and must not be freed. + * Returns: The line termination string. This value + * is owned by GLib and must not be freed. */ @@ -16239,7 +16509,8 @@ /** * g_io_channel_new_file: * @filename: A string containing the name of a file - * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen() + * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have + * the same meaning as in fopen() * @error: A location to return an error of type %G_FILE_ERROR * * Open a file @filename as a #GIOChannel using mode @mode. This @@ -16255,7 +16526,8 @@ /** * g_io_channel_read: * @channel: a #GIOChannel - * @buf: a buffer to read the data into (which should be at least count bytes long) + * @buf: a buffer to read the data into (which should be at least + * count bytes long) * @count: the number of bytes to read from the #GIOChannel * @bytes_read: returns the number of bytes actually read * @@ -16269,10 +16541,17 @@ /** * g_io_channel_read_chars: * @channel: a #GIOChannel - * @buf: a buffer to read data into - * @count: the size of the buffer. Note that the buffer may not be complelely filled even if there is data in the buffer if the remaining data is not a complete character. - * @bytes_read: (allow-none): The number of bytes read. This may be zero even on success if count < 6 and the channel's encoding is non-%NULL. This indicates that the next UTF-8 character is too wide for the buffer. - * @error: a location to return an error of type #GConvertError or #GIOChannelError. + * @buf: (out caller-allocates) (array length=count) (element-type guint8): + * a buffer to read data into + * @count: (in): the size of the buffer. Note that the buffer may not be + * complelely filled even if there is data in the buffer if the + * remaining data is not a complete character. + * @bytes_read: (allow-none) (out): The number of bytes read. This may be + * zero even on success if count < 6 and the channel's encoding + * is non-%NULL. This indicates that the next UTF-8 character is + * too wide for the buffer. + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError. * * Replacement for g_io_channel_read() with the new API. * @@ -16283,10 +16562,14 @@ /** * g_io_channel_read_line: * @channel: a #GIOChannel - * @str_return: The line read from the #GIOChannel, including the line terminator. This data should be freed with g_free() when no longer needed. This is a nul-terminated string. If a @length of zero is returned, this will be %NULL instead. - * @length: (allow-none): location to store length of the read data, or %NULL - * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL - * @error: A location to return an error of type #GConvertError or #GIOChannelError + * @str_return: (out): The line read from the #GIOChannel, including the + * line terminator. This data should be freed with g_free() + * when no longer needed. This is a nul-terminated string. + * If a @length of zero is returned, this will be %NULL instead. + * @length: (allow-none) (out): location to store length of the read data, or %NULL + * @terminator_pos: (allow-none) (out): location to store position of line terminator, or %NULL + * @error: A location to return an error of type #GConvertError + * or #GIOChannelError * * Reads a line, including the terminating character(s), * from a #GIOChannel into a newly-allocated string. @@ -16300,9 +16583,12 @@ /** * g_io_channel_read_line_string: * @channel: a #GIOChannel - * @buffer: a #GString into which the line will be written. If @buffer already contains data, the old data will be overwritten. + * @buffer: a #GString into which the line will be written. + * If @buffer already contains data, the old data will + * be overwritten. * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL - * @error: a location to store an error of type #GConvertError or #GIOChannelError + * @error: a location to store an error of type #GConvertError + * or #GIOChannelError * * Reads a line from a #GIOChannel, using a #GString as a buffer. * @@ -16313,21 +16599,28 @@ /** * g_io_channel_read_to_end: * @channel: a #GIOChannel - * @str_return: Location to store a pointer to a string holding the remaining data in the #GIOChannel. This data should be freed with g_free() when no longer needed. This data is terminated by an extra nul character, but there may be other nuls in the intervening data. - * @length: location to store length of the data - * @error: location to return an error of type #GConvertError or #GIOChannelError + * @str_return: (out) (array length=length) (element-type guint8): Location to + * store a pointer to a string holding the remaining data in the + * #GIOChannel. This data should be freed with g_free() when no + * longer needed. This data is terminated by an extra nul + * character, but there may be other nuls in the intervening data. + * @length: (out): location to store length of the data + * @error: location to return an error of type #GConvertError + * or #GIOChannelError * * Reads all the remaining data from the file. * - * Returns: %G_IO_STATUS_NORMAL on success. This function never returns %G_IO_STATUS_EOF. + * Returns: %G_IO_STATUS_NORMAL on success. + * This function never returns %G_IO_STATUS_EOF. */ /** * g_io_channel_read_unichar: * @channel: a #GIOChannel - * @thechar: a location to return a character - * @error: a location to return an error of type #GConvertError or #GIOChannelError + * @thechar: (out): a location to return a character + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError * * Reads a Unicode character from @channel. * This function cannot be called on a channel with %NULL encoding. @@ -16349,8 +16642,11 @@ /** * g_io_channel_seek: * @channel: a #GIOChannel - * @offset: an offset, in bytes, which is added to the position specified by @type - * @type: the position in the file, which can be %G_SEEK_CUR (the current position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the file) + * @offset: an offset, in bytes, which is added to the position specified + * by @type + * @type: the position in the file, which can be %G_SEEK_CUR (the current + * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END + * (the end of the file) * * Sets the current position in the #GIOChannel, similar to the standard * library function fseek(). @@ -16364,7 +16660,10 @@ * g_io_channel_seek_position: * @channel: a #GIOChannel * @offset: The offset in bytes from the position specified by @type - * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those cases where a call to g_io_channel_set_encoding () is allowed. See the documentation for g_io_channel_set_encoding () for details. + * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those + * cases where a call to g_io_channel_set_encoding () + * is allowed. See the documentation for + * g_io_channel_set_encoding () for details. * @error: A location to return an error of type #GIOChannelError * * Replacement for g_io_channel_seek() with the new API. @@ -16412,7 +16711,10 @@ /** * g_io_channel_set_close_on_unref: * @channel: a #GIOChannel - * @do_close: Whether to close the channel on the final unref of the GIOChannel data structure. The default value of this is %TRUE for channels created by g_io_channel_new_file (), and %FALSE for all other channels. + * @do_close: Whether to close the channel on the final unref of + * the GIOChannel data structure. The default value of + * this is %TRUE for channels created by g_io_channel_new_file (), + * and %FALSE for all other channels. * * Setting this flag to %TRUE for a channel you have already closed * can cause problems. @@ -16422,7 +16724,7 @@ /** * g_io_channel_set_encoding: * @channel: a #GIOChannel - * @encoding: the encoding type + * @encoding: (allow-none): the encoding type * @error: location to store an error of type #GConvertError * * Sets the encoding for the input/output of the channel. @@ -16433,43 +16735,34 @@ * * 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 - * (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 + * + * - 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). + * + * - 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 * calling one of the API "read" functions. * - * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set. + * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set */ @@ -16488,8 +16781,13 @@ /** * g_io_channel_set_line_term: * @channel: a #GIOChannel - * @line_term: The line termination string. Use %NULL for autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph separator. Autodetection should not be used for anything other than file-based channels. - * @length: The length of the termination string. If -1 is passed, the string is assumed to be nul-terminated. This option allows termination strings with embedded nuls. + * @line_term: (allow-none): The line termination string. Use %NULL for + * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", + * and the Unicode paragraph separator. Autodetection should not be + * used for anything other than file-based channels. + * @length: The length of the termination string. If -1 is passed, the + * string is assumed to be nul-terminated. This option allows + * termination strings with embedded nuls. * * This sets the string that #GIOChannel uses to determine * where in the file a line break occurs. @@ -16638,10 +16936,16 @@ /** * g_io_channel_write_chars: * @channel: a #GIOChannel - * @buf: a buffer to write data from - * @count: the size of the buffer. If -1, the buffer is taken to be a nul-terminated string. - * @bytes_written: The number of bytes written. This can be nonzero even if the return value is not %G_IO_STATUS_NORMAL. If the return value is %G_IO_STATUS_NORMAL and the channel is blocking, this will always be equal to @count if @count >= 0. - * @error: a location to return an error of type #GConvertError or #GIOChannelError + * @buf: (array) (element-type guint8): a buffer to write data from + * @count: the size of the buffer. If -1, the buffer + * is taken to be a nul-terminated string. + * @bytes_written: (out): The number of bytes written. This can be nonzero + * even if the return value is not %G_IO_STATUS_NORMAL. + * If the return value is %G_IO_STATUS_NORMAL and the + * channel is blocking, this will always be equal + * to @count if @count >= 0. + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError * * Replacement for g_io_channel_write() with the new API. * @@ -16658,7 +16962,8 @@ * g_io_channel_write_unichar: * @channel: a #GIOChannel * @thechar: a character - * @error: location to return an error of type #GConvertError or #GIOChannelError + * @error: location to return an error of type #GConvertError + * or #GIOChannelError * * Writes a Unicode character to @channel. * This function cannot be called on a channel with %NULL encoding. @@ -16715,7 +17020,8 @@ * associated with @key cannot be interpreted as a boolean then %FALSE * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: the value associated with the key as a boolean, or %FALSE if the key was not found or could not be parsed. + * Returns: the value associated with the key as a boolean, + * or %FALSE if the key was not found or could not be parsed. * Since: 2.6 */ @@ -16736,7 +17042,10 @@ * with @key cannot be interpreted as booleans then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: (array length=length) (element-type gboolean) (transfer container): the values associated with the key as a list of booleans, or %NULL if the key was not found or could not be parsed. The returned list of booleans should be freed with g_free() when no longer needed. + * Returns: (array length=length) (element-type gboolean) (transfer container): + * the values associated with the key as a list of booleans, or %NULL if the + * key was not found or could not be parsed. The returned list of booleans + * should be freed with g_free() when no longer needed. * Since: 2.6 */ @@ -16773,7 +17082,8 @@ * with @key cannot be interpreted as a double then 0.0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: the value associated with the key as a double, or 0.0 if the key was not found or could not be parsed. + * Returns: the value associated with the key as a double, or + * 0.0 if the key was not found or could not be parsed. * Since: 2.12 */ @@ -16794,7 +17104,10 @@ * with @key cannot be interpreted as doubles then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: (array length=length) (element-type gdouble) (transfer container): the values associated with the key as a list of doubles, or %NULL if the key was not found or could not be parsed. The returned list of doubles should be freed with g_free() when no longer needed. + * Returns: (array length=length) (element-type gdouble) (transfer container): + * the values associated with the key as a list of doubles, or %NULL if the + * key was not found or could not be parsed. The returned list of doubles + * should be freed with g_free() when no longer needed. * Since: 2.12 */ @@ -16808,7 +17121,8 @@ * The array of returned groups will be %NULL-terminated, so * @length may optionally be %NULL. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.6 */ @@ -16824,7 +17138,8 @@ * 64-bit integer. This is similar to g_key_file_get_integer() but can return * 64-bit results without truncation. * - * Returns: the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed. + * Returns: the value associated with the key as a signed 64-bit integer, or + * 0 if the key was not found or could not be parsed. * Since: 2.26 */ @@ -16844,7 +17159,8 @@ * with @key cannot be interpreted as an integer then 0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: the value associated with the key as an integer, or 0 if the key was not found or could not be parsed. + * Returns: the value associated with the key as an integer, or + * 0 if the key was not found or could not be parsed. * Since: 2.6 */ @@ -16865,7 +17181,10 @@ * with @key cannot be interpreted as integers then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: (array length=length) (element-type gint) (transfer container): the values associated with the key as a list of integers, or %NULL if the key was not found or could not be parsed. The returned list of integers should be freed with g_free() when no longer needed. + * Returns: (array length=length) (element-type gint) (transfer container): + * the values associated with the key as a list of integers, or %NULL if + * the key was not found or could not be parsed. The returned list of + * integers should be freed with g_free() when no longer needed. * Since: 2.6 */ @@ -16883,7 +17202,8 @@ * be found, %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.6 */ @@ -16905,7 +17225,8 @@ * with @key cannot be interpreted or no suitable translation can * be found then the untranslated value is returned. * - * Returns: a newly allocated string or %NULL if the specified key cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * key cannot be found. * Since: 2.6 */ @@ -16930,7 +17251,9 @@ * returned array is %NULL-terminated, so @length may optionally * be %NULL. * - * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array or %NULL if the key isn't found. The string array should be freed with g_strfreev(). + * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array + * or %NULL if the key isn't found. The string array should be freed + * with g_strfreev(). * Since: 2.6 */ @@ -16962,7 +17285,8 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified key cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * key cannot be found. * Since: 2.6 */ @@ -16982,7 +17306,9 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a %NULL-terminated string array or %NULL if the specified key cannot be found. The array should be freed with g_strfreev(). + * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full): + * a %NULL-terminated string array or %NULL if the specified + * key cannot be found. The array should be freed with g_strfreev(). * Since: 2.6 */ @@ -16998,7 +17324,8 @@ * 64-bit integer. This is similar to g_key_file_get_integer() but can return * large positive results without truncation. * - * Returns: the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed. + * Returns: the value associated with the key as an unsigned 64-bit integer, + * or 0 if the key was not found or could not be parsed. * Since: 2.26 */ @@ -17018,7 +17345,8 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified key cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * key cannot be found. * Since: 2.6 */ @@ -17030,7 +17358,8 @@ * * Looks whether the key file has the group @group_name. * - * Returns: %TRUE if @group_name is a part of @key_file, %FALSE otherwise. + * Returns: %TRUE if @group_name is a part of @key_file, %FALSE + * otherwise. * Since: 2.6 */ @@ -17045,15 +17374,15 @@ * 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. * - * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise. + * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise * Since: 2.6 */ @@ -17062,7 +17391,7 @@ * g_key_file_load_from_data: * @key_file: an empty #GKeyFile struct * @data: key file loaded in memory - * @length: the length of @data in bytes (or -1 if data is nul-terminated) + * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated) * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * @@ -17078,7 +17407,8 @@ * g_key_file_load_from_data_dirs: * @key_file: an empty #GKeyFile struct * @file: (type filename): a relative path to a filename to open and parse - * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path of the file, or %NULL + * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path + * of the file, or %NULL * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * @@ -17098,7 +17428,8 @@ * @key_file: an empty #GKeyFile struct * @file: (type filename): a relative path to a filename to open and parse * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search - * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path of the file, or %NULL + * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path + * of the file, or %NULL * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * @@ -17199,6 +17530,23 @@ /** + * g_key_file_save_to_file: + * @key_file: a #GKeyFile + * @filename: the name of the file to write to + * @error: a pointer to a %NULL #GError, or %NULL + * + * Writes the contents of @key_file to @filename using + * g_file_set_contents(). + * + * This function can fail for any of the reasons that + * g_file_set_contents() may fail. + * + * Returns: %TRUE if successful, else %FALSE with @error set + * Since: 2.40 + */ + + +/** * g_key_file_set_boolean: * @key_file: a #GKeyFile * @group_name: a group name @@ -17352,7 +17700,7 @@ * @group_name: a group name * @key: a key * @locale: a locale identifier - * @list: (array length=length zero-terminated=1): a %NULL-terminated array of locale string values + * @list: (array zero-terminated=1 length=length): a %NULL-terminated array of locale string values * @length: the length of @list * * Associates a list of string values for @key and @locale under @@ -17385,7 +17733,7 @@ * @key_file: a #GKeyFile * @group_name: a group name * @key: a key - * @list: (array length=length zero-terminated=1) (element-type utf8): an array of string values + * @list: (array zero-terminated=1 length=length) (element-type utf8): an array of string values * @length: number of string values in @list * * Associates a list of string values for @key under @group_name. @@ -17431,7 +17779,8 @@ /** * g_key_file_to_data: * @key_file: a #GKeyFile - * @length: (out) (allow-none): return location for the length of the returned string, or %NULL + * @length: (out) (allow-none): return location for the length of the + * returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @key_file as a string. @@ -17439,7 +17788,8 @@ * Note that this function never reports an error, * so it is safe to pass %NULL as @error. * - * Returns: a newly allocated string holding the contents of the #GKeyFile + * Returns: a newly allocated string holding + * the contents of the #GKeyFile * Since: 2.6 */ @@ -17462,7 +17812,7 @@ * g_list_append(), g_list_prepend(), g_list_insert() and * g_list_insert_sorted() and so is rarely used on its own. * - * Returns: a pointer to the newly-allocated #GList element. + * Returns: a pointer to the newly-allocated #GList element */ @@ -17473,115 +17823,118 @@ * * 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)); * ]| * - * Returns: the new start of the #GList + * Returns: either @list or the new start of the #GList if @list was %NULL */ /** * g_list_concat: - * @list1: a #GList - * @list2: the #GList to add to the end of the first #GList + * @list1: a #GList, this must point to the top of the list + * @list2: the #GList to add to the end of the first #GList, + * this must point to the top of the list * * 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. * - * Returns: the start of the new #GList + * 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); + * ]| + * + * Returns: the start of the new #GList, which equals @list1 if not %NULL */ /** * g_list_copy: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * * 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> * - * Returns: a copy of @list + * Returns: the start of the new list that holds the same data as @list */ /** * g_list_copy_deep: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @func: a copy function used to copy every element in the list - * @user_data: user data passed to the copy function @func, or #NULL + * @user_data: user data passed to the copy function @func, or %NULL * * 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); * ]| * - * Returns: a full copy of @list, use #g_list_free_full to free it + * Returns: the start of the new list that holds a full copy of @list, + * use g_list_free_full() to free it * Since: 2.34 */ /** * g_list_delete_link: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @link_: node to delete from @list * * Removes the node link_ from the list and frees it. * Compare this to g_list_remove_link() which removes the node * without freeing it. * - * Returns: the new head of @list + * Returns: the (possibly changed) start of the #GList */ /** * g_list_find: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @data: the element data to find * - * Finds the element in a #GList which - * contains the given data. + * Finds the element in a #GList which contains the given data. * * Returns: the found #GList element, or %NULL if it is not found */ @@ -17589,9 +17942,10 @@ /** * g_list_find_custom: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @data: user data passed to the function - * @func: the function to call for each element. It should return 0 when the desired element is found + * @func: the function to call for each element. + * It should return 0 when the desired element is found * * Finds an element in a #GList, using a supplied function to * find the desired element. It iterates over the list, calling @@ -17606,17 +17960,18 @@ /** * g_list_first: - * @list: a #GList + * @list: any #GList element * * Gets the first element in a #GList. * - * Returns: the first element in the #GList, or %NULL if the #GList has no elements + * Returns: the first element in the #GList, + * or %NULL if the #GList has no elements */ /** * g_list_foreach: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @func: the function to call with each element's data * @user_data: user data to pass to the function * @@ -17631,11 +17986,8 @@ * 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. */ @@ -17660,8 +18012,8 @@ * @list: a pointer to a #GList * @free_func: the function to be called to free each element's data * - * 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 */ @@ -17669,88 +18021,108 @@ /** * g_list_index: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @data: the data to find * * Gets the position of the element containing * the given data (starting from 0). * - * Returns: the index of the element containing the data, or -1 if the data is not found + * Returns: the index of the element containing the data, + * or -1 if the data is not found */ /** * g_list_insert: - * @list: a pointer to a #GList + * @list: a pointer to a #GList, this must point to the top of the list * @data: the data for the new element - * @position: the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. + * @position: the position to insert the element. If this is + * negative, or is larger than the number of elements in the + * list, the new element is added on to the end of the list. * * Inserts a new element into the list at the given position. * - * Returns: the new start of the #GList + * Returns: the (possibly changed) start of the #GList */ /** * g_list_insert_before: - * @list: a pointer to a #GList - * @sibling: the list element before which the new element is inserted or %NULL to insert at the end of the list + * @list: a pointer to a #GList, this must point to the top of the list + * @sibling: the list element before which the new element + * is inserted or %NULL to insert at the end of the list * @data: the data for the new element * * Inserts a new element into the list before the given position. * - * Returns: the new start of the #GList + * Returns: the (possibly changed) start of the #GList */ /** * g_list_insert_sorted: - * @list: a pointer to a #GList + * @list: a pointer to a #GList, this must point to the top of the + * already sorted list * @data: the data for the new element - * @func: 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. + * @func: 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. * * Inserts a new element into the list, using the given comparison * function to determine its position. * - * Returns: the new start of the #GList + * 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(). + * + * Returns: the (possibly changed) start of the #GList */ /** * g_list_insert_sorted_with_data: - * @list: a pointer to a #GList + * @list: a pointer to a #GList, this must point to the top of the + * already sorted list * @data: the data for the new element - * @func: 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. - * @user_data: user data to pass to comparison function. + * @func: 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. + * @user_data: user data to pass to comparison function * * Inserts a new element into the list, using the given comparison * function to determine its position. * - * Returns: the new start of the #GList + * 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(). + * + * Returns: the (possibly changed) start of the #GList * Since: 2.10 */ /** * g_list_last: - * @list: a #GList + * @list: any #GList element * * Gets the last element in a #GList. * - * Returns: the last element in the #GList, or %NULL if the #GList has no elements + * Returns: the last element in the #GList, + * or %NULL if the #GList has no elements */ /** * g_list_length: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * * 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. * * Returns: the number of elements in the #GList */ @@ -17758,33 +18130,37 @@ /** * g_list_next: - * @list: an element in a #GList. + * @list: an element in a #GList * * A convenience macro to get the next element in a #GList. + * Note that it is considered perfectly acceptable to access + * @list->next directly. * - * Returns: the next element, or %NULL if there are no more elements. + * Returns: the next element, or %NULL if there are no more elements */ /** * g_list_nth: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @n: the position of the element, counting from 0 * * Gets the element at the given position in a #GList. * - * Returns: the element, or %NULL if the position is off the end of the #GList + * Returns: the element, or %NULL if the position is off + * the end of the #GList */ /** * g_list_nth_data: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @n: the position of the element * * Gets the data of the element at the given position. * - * Returns: the element's data, or %NULL if the position is off the end of the #GList + * Returns: the element's data, or %NULL if the position + * is off the end of the #GList */ @@ -17795,71 +18171,79 @@ * * Gets the element @n places before @list. * - * Returns: the element, or %NULL if the position is off the end of the #GList + * Returns: the element, or %NULL if the position is + * off the end of the #GList */ /** * g_list_position: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @llink: an element in the #GList * * Gets the position of the given element * in the #GList (starting from 0). * - * Returns: the position of the element in the #GList, or -1 if the element is not found + * Returns: the position of the element in the #GList, + * or -1 if the element is not found */ /** * g_list_prepend: - * @list: a pointer to a #GList + * @list: a pointer to a #GList, this must point to the top of the list * @data: the data for the new element * - * 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"); * ]| * - * Returns: the new start of the #GList + * 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. + * + * Returns: a pointer to the newly prepended element, which is the new + * start of the #GList */ /** * g_list_previous: - * @list: an element in a #GList. + * @list: an element in a #GList * * A convenience macro to get the previous element in a #GList. + * Note that it is considered perfectly acceptable to access + * @list->previous directly. * - * Returns: the previous element, or %NULL if there are no previous elements. + * Returns: the previous element, or %NULL if there are no previous + * elements */ /** * g_list_remove: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @data: the data of the element to remove * * Removes an element from a #GList. * If two elements contain the same data, only the first is removed. * If none of the elements contain the data, the #GList is unchanged. * - * Returns: the new start of the #GList + * Returns: the (possibly changed) start of the #GList */ /** * g_list_remove_all: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @data: data to remove * * Removes all list nodes with data equal to @data. @@ -17867,26 +18251,35 @@ * g_list_remove() which removes only the first node * matching the given data. * - * Returns: new head of @list + * Returns: the (possibly changed) start of the #GList */ /** * g_list_remove_link: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @llink: an element in the #GList * * 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. * - * Returns: the new start of the #GList, without the 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); + * ]| + * + * Returns: the (possibly changed) start of the #GList */ /** * g_list_reverse: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * * Reverses a #GList. * It simply switches the next and prev pointers of each element. @@ -17897,26 +18290,30 @@ /** * g_list_sort: - * @list: a #GList - * @compare_func: the comparison function used to sort the #GList. This function is passed the data from 2 elements of the #GList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. + * @list: a #GList, this must point to the top of the list + * @compare_func: the comparison function used to sort the #GList. + * This function is passed the data from 2 elements of the #GList + * and should return 0 if they are equal, a negative value if the + * first element comes before the second, or a positive value if + * the first element comes after the second. * * Sorts a #GList using the given comparison function. The algorithm * used is a stable sort. * - * Returns: the start of the sorted #GList + * Returns: the (possibly changed) start of the #GList */ /** * g_list_sort_with_data: - * @list: a #GList + * @list: a #GList, this must point to the top of the list * @compare_func: comparison function * @user_data: user data to pass to comparison function * * Like g_list_sort(), but the comparison function accepts * a user data argument. * - * Returns: the new head of @list + * Returns: the (possibly changed) start of the #GList */ @@ -17932,7 +18329,8 @@ * use cases for environment variables in GLib-using programs you want * the UTF-8 encoding that this function and g_getenv() provide. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated list of strings which must be freed with g_strfreev(). + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated + * list of strings which must be freed with g_strfreev(). * Since: 2.8 */ @@ -17940,41 +18338,68 @@ /** * g_locale_from_utf8: * @utf8string: a UTF-8 encoded string - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @len: the length of the string, or -1 if the string is + * 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) + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @bytes_written: the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * 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. * - * Returns: The converted string, or %NULL on an error. + * Returns: A newly-allocated buffer containing the converted string, + * or %NULL on an error, and error will be set. */ /** * g_locale_to_utf8: - * @opsysstring: a string in the encoding of the current locale. On Windows this means the system codepage. - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul). - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @opsysstring: a string in the encoding of the current locale. On Windows + * this means the system codepage. + * @len: the length of the string, or -1 if the string is + * 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) + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * less than @len if there were partial characters + * at the end of the input. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @bytes_written: the number of bytes stored in the output buffer (not + * including the terminating nul). + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * 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. * - * Returns: The converted string, or %NULL on an error. + * Returns: A newly-allocated buffer containing the converted string, + * or %NULL on an error, and error will be set. */ /** * g_log: * @log_domain: the log domain, usually #G_LOG_DOMAIN - * @log_level: the log level, either from #GLogLevelFlags or a user-defined level + * @log_level: the log level, either from #GLogLevelFlags + * or a user-defined level * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * @@ -17982,6 +18407,10 @@ * * If the log level has been set as fatal, the abort() * function is called to terminate the program. + * + * 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. */ @@ -17996,27 +18425,20 @@ * allows to install an alternate default log handler. * This is used if no log handler has been set for the particular log * domain and log level combination. It outputs the message to stderr - * or stdout and if the log level is fatal it calls abort(). + * or stdout and if the log level is fatal it calls abort(). It automatically + * prints a new-line character after the message, so one does not need to be + * 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 @@ -18027,7 +18449,8 @@ /** * g_log_remove_handler: * @log_domain: the log domain - * @handler_id: the id of the handler, which was returned in g_log_set_handler() + * @handler_id: the id of the handler, which was returned + * in g_log_set_handler() * * Removes the log handler. */ @@ -18035,7 +18458,8 @@ /** * g_log_set_always_fatal: - * @fatal_mask: the mask containing bits set for each level of error which is to be fatal + * @fatal_mask: the mask containing bits set for each level + * of error which is to be fatal * * Sets the message levels which are always fatal, in any log domain. * When a message with any of these levels is logged the program terminates. @@ -18043,8 +18467,8 @@ * %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)). * * Returns: the old fatal mask */ @@ -18079,8 +18503,12 @@ /** * g_log_set_handler: - * @log_domain: (allow-none): the log domain, or %NULL for the default "" application domain - * @log_levels: the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine the log levels with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION bit flags. + * @log_domain: (allow-none): the log domain, or %NULL for the default "" + * application domain + * @log_levels: the log levels to apply the log handler for. + * To handle fatal and recursive messages as well, combine + * the log levels with the #G_LOG_FLAG_FATAL and + * #G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * @@ -18093,31 +18521,24 @@ * 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> + * ]| * * Returns: the id of the new handler */ @@ -18134,13 +18555,18 @@ * * If the log level has been set as fatal, the abort() * function is called to terminate the program. + * + * 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. */ /** * g_lstat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @buf: a pointer to a <structname>stat</structname> struct, which will be filled with the file information + * @buf: a pointer to a stat struct, which will be filled with the file + * information * * A wrapper for the POSIX lstat() function. The lstat() function is * like stat() except that in the case of symbolic links, it returns @@ -18150,7 +18576,8 @@ * * See your C library manual for more details about lstat(). * - * Returns: 0 if the information was successfully retrieved, -1 if an error occurred + * Returns: 0 if the information was successfully retrieved, + * -1 if an error occurred * Since: 2.6 */ @@ -18170,19 +18597,23 @@ * can call g_main_context_prepare(), g_main_context_query(), * g_main_context_check(), g_main_context_dispatch(). * - * Returns: %TRUE if the operation succeeded, and this thread is now the owner of @context. + * Returns: %TRUE if the operation succeeded, and + * this thread is now the owner of @context. */ /** * g_main_context_add_poll: * @context: (allow-none): a #GMainContext (or %NULL for the default context) - * @fd: a #GPollFD structure holding information about a file descriptor to watch. - * @priority: the priority for this file descriptor which should be the same as the priority used for g_source_attach() to ensure that the file descriptor is polled whenever the results may be needed. + * @fd: a #GPollFD structure holding information about a file + * descriptor to watch. + * @priority: the priority for this file descriptor which should be + * the same as the priority used for g_source_attach() to ensure that the + * file descriptor is polled whenever the results may be needed. * * Adds a file descriptor to the set of file descriptors polled for * this context. This will very seldom be used directly. Instead - * a typical event source will use g_source_add_poll() instead. + * a typical event source will use g_source_add_unix_fd() instead. */ @@ -18190,7 +18621,8 @@ * g_main_context_check: * @context: a #GMainContext * @max_priority: the maximum numerical priority of sources to check - * @fds: (array length=n_fds): array of #GPollFD's that was passed to the last call to g_main_context_query() + * @fds: (array length=n_fds): array of #GPollFD's that was passed to + * the last call to g_main_context_query() * @n_fds: return value of g_main_context_query() * * Passes the results of polling back to the main loop. @@ -18274,7 +18706,7 @@ * 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.) @@ -18282,7 +18714,8 @@ * If you need to hold a reference on the context, use * g_main_context_ref_thread_default() instead. * - * Returns: (transfer none): the thread-default #GMainContext, or %NULL if the thread-default context is the global default context. + * Returns: (transfer none): the thread-default #GMainContext, or + * %NULL if the thread-default context is the global default context. * Since: 2.22 */ @@ -18410,12 +18843,14 @@ /** * g_main_context_prepare: * @context: a #GMainContext - * @priority: location to store priority of highest priority source already ready. + * @priority: location to store priority of highest priority + * source already ready. * * Prepares to poll sources within a main loop. The resulting information * for polling is determined by calling g_main_context_query (). * - * Returns: %TRUE if some source is ready to be dispatched prior to polling. + * Returns: %TRUE if some source is ready to be dispatched + * prior to polling. */ @@ -18425,14 +18860,13 @@ * * 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 @@ -18461,12 +18895,15 @@ * @context: a #GMainContext * @max_priority: maximum priority source to check * @timeout_: (out): location to store timeout to be used in polling - * @fds: (out caller-allocates) (array length=n_fds): location to store #GPollFD records that need to be polled. + * @fds: (out caller-allocates) (array length=n_fds): location to + * store #GPollFD records that need to be polled. * @n_fds: length of @fds. * * Determines information necessary to poll this main loop. * - * Returns: the number of records actually stored in @fds, or, if more than @n_fds records need to be stored, the number of records that need to be stored. + * Returns: the number of records actually stored in @fds, + * or, if more than @n_fds records need to be stored, the number + * of records that need to be stored. */ @@ -18490,7 +18927,8 @@ * is the global default context, this will return that #GMainContext * (with a ref added to it) rather than returning %NULL. * - * Returns: (transfer full): the thread-default #GMainContext. Unref with g_main_context_unref() when you are done with it. + * Returns: (transfer full): the thread-default #GMainContext. Unref + * with g_main_context_unref() when you are done with it. * Since: 2.32 */ @@ -18552,7 +18990,8 @@ * that owner releases ownership or until @cond is signaled, then * try again (once) to become the owner. * - * Returns: %TRUE if the operation succeeded, and this thread is now the owner of @context. + * Returns: %TRUE if the operation succeeded, and + * this thread is now the owner of @context. */ @@ -18560,8 +18999,34 @@ * g_main_context_wakeup: * @context: a #GMainContext * - * If @context is currently waiting in a poll(), interrupt - * the poll(), and continue the iteration process. + * If @context is currently blocking in g_main_context_iteration() + * waiting for a source to become ready, cause it to stop blocking + * and return. Otherwise, cause the next invocation of + * g_main_context_iteration() to return without blocking. + * + * This API is useful for low-level control over #GMainContext; for + * example, integrating it with main loop implementations such as + * #GMainLoop. + * + * 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; + * ... + * + * while (g_atomic_int_get (&tasks_remaining) != 0) + * g_main_context_iteration (NULL, TRUE); + * ]| + * + * Then in a thread: + * |[<!-- language="C" --> + * perform_work(); + * + * if (g_atomic_int_dec_and_test (&tasks_remaining)) + * g_main_context_wakeup (NULL); + * ]| */ @@ -18589,7 +19054,7 @@ * This function is useful in a situation like the following: * Imagine an extremely simple "garbage collected" system. * - * |[ + * |[<!-- language="C" --> * static GList *free_list; * * gpointer @@ -18626,7 +19091,7 @@ * 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) * { @@ -18641,7 +19106,7 @@ * free_allocated_memory (void) * { * GList *l; - * + * * int depth = g_main_depth (); * for (l = free_list; l; ); * { @@ -18653,7 +19118,7 @@ * g_free (block); * free_list = g_list_delete_link (free_list, l); * } - * + * * l = next; * } * } @@ -18671,23 +19136,14 @@ * 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 - * 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 - * 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> + * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent + * the user from interacting with elements while the main + * loop is recursing. + * + * 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. * * Returns: The main loop recursion level in the current thread */ @@ -18716,7 +19172,9 @@ /** * g_main_loop_new: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used). - * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_loop_run() will set this to %TRUE anyway. + * @is_running: set to %TRUE to indicate that the loop is running. This + * is not very important since calling g_main_loop_run() will set this to + * %TRUE anyway. * * Creates a new #GMainLoop structure. * @@ -18834,7 +19292,8 @@ * The mapped contents of the file must not be modified after creating this * bytes object, because a #GBytes should be immutable. * - * Returns: (transfer full): A newly allocated #GBytes referencing data from @file + * Returns: (transfer full): A newly allocated #GBytes referencing data + * from @file * Since: 2.34 */ @@ -18889,7 +19348,8 @@ * size 0 (e.g. device files such as /dev/null), @error will be set * to the #GFileError value #G_FILE_ERROR_INVAL. * - * Returns: a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. + * Returns: a newly allocated #GMappedFile which must be unref'd + * with g_mapped_file_unref(), or %NULL if the mapping failed. * Since: 2.8 */ @@ -18912,7 +19372,8 @@ * will not be modified, or if all modifications of the file are done * atomically (e.g. using g_file_set_contents()). * - * Returns: a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. + * Returns: a newly allocated #GMappedFile which must be unref'd + * with g_mapped_file_unref(), or %NULL if the mapping failed. * Since: 2.32 */ @@ -18950,7 +19411,9 @@ * @error: a pointer to a #GError or %NULL * @first_type: the #GMarkupCollectType of the first attribute * @first_attr: the name of the first attribute - * @...: a pointer to the storage location of the first attribute (or %NULL), followed by more types names and pointers, ending with %G_MARKUP_COLLECT_INVALID + * @...: a pointer to the storage location of the first attribute + * (or %NULL), followed by more types names and pointers, ending + * with %G_MARKUP_COLLECT_INVALID * * Collects the attributes of the element from the data passed to the * #GMarkupParser start_element function, dealing with common error @@ -19005,7 +19468,7 @@ * of line endings and attribute values. * * Note also that this function will produce character references in - * the range of &#x1; ... &#x1f; for all control sequences + * the range of  ...  for all control sequences * except for tabstop, newline and carriage return. The character * references in this range are not valid XML 1.0, but they are * valid XML 1.1 and will be accepted by the GMarkup parser. @@ -19099,7 +19562,9 @@ * g_markup_parse_context_new() or to the most recent call * of g_markup_parse_context_push(). * - * Returns: the provided user_data. The returned data belongs to the markup context and will be freed when g_markup_parse_context_free() is called. + * Returns: the provided user_data. The returned data belongs to + * the markup context and will be freed when + * g_markup_parse_context_free() is called. * Since: 2.18 */ @@ -19109,7 +19574,8 @@ * @parser: a #GMarkupParser * @flags: one or more #GMarkupParseFlags * @user_data: user data to pass to #GMarkupParser functions - * @user_data_dnotify: user data destroy notifier called when the parse context is freed + * @user_data_dnotify: user data destroy notifier called when + * the parse context is freed * * Creates a new parse context. A parse context is used to parse * marked-up documents. You can feed any number of documents into @@ -19202,7 +19668,7 @@ * 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; @@ -19244,7 +19710,7 @@ * 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) * { @@ -19269,13 +19735,13 @@ * * 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, ...) @@ -19283,7 +19749,7 @@ * if (strcmp (element_name, "count-these") == 0) * g_print ("Counted %d tags\n", end_counting (context)); * - * /* else, handle other tags... */ + * // else, handle other tags... * } * ]| * @@ -19292,6 +19758,28 @@ /** + * g_markup_parse_context_ref: + * @context: a #GMarkupParseContext + * + * Increases the reference count of @context. + * + * Returns: the same @context + * Since: 2.36 + */ + + +/** + * g_markup_parse_context_unref: + * @context: a #GMarkupParseContext + * + * Decreases the reference count of @context. When its reference count + * drops to 0, it is freed. + * + * Since: 2.36 + */ + + +/** * g_markup_printf_escaped: * @format: printf() style format string * @...: the arguments to insert in the format string @@ -19303,19 +19791,20 @@ * output, without having to worry that the strings * might themselves contain markup. * - * |[ - * const char *store = "Fortnum & Mason"; + * |[<!-- 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>" - * "</purchase>", + * + * output = g_markup_printf_escaped ("<purchase>" + * "<store>%s</store>" + * "<item>%s</item>" + * "</purchase>", * store, item); * ]| * - * Returns: newly allocated result from formatting operation. Free with g_free(). + * Returns: newly allocated result from formatting + * operation. Free with g_free(). * Since: 2.4 */ @@ -19329,7 +19818,8 @@ * all string and character arguments in the fashion * of g_markup_escape_text(). See g_markup_printf_escaped(). * - * Returns: newly allocated result from formatting operation. Free with g_free(). + * Returns: newly allocated result from formatting + * operation. Free with g_free(). * Since: 2.4 */ @@ -19368,7 +19858,7 @@ * @match_info: #GMatchInfo structure * @match_num: number of the sub expression * - * 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. * @@ -19385,7 +19875,8 @@ * The string is fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * - * Returns: (allow-none): The matched substring, or %NULL if an error occurred. You have to free the string yourself + * Returns: (allow-none): The matched substring, or %NULL if an error + * occurred. You have to free the string yourself * Since: 2.14 */ @@ -19411,7 +19902,9 @@ * The strings are fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * - * Returns: (transfer full): a %NULL-terminated array of gchar * pointers. It must be freed using g_strfreev(). If the previous match failed %NULL is returned + * Returns: (transfer full): a %NULL-terminated array of gchar * + * pointers. It must be freed using g_strfreev(). If the previous + * match failed %NULL is returned * Since: 2.14 */ @@ -19424,13 +19917,14 @@ * Retrieves the text matching the capturing parentheses named @name. * * If @name is a valid sub pattern name but it didn't match anything - * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") + * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") * then an empty string is returned. * * The string is fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * - * Returns: (allow-none): The matched substring, or %NULL if an error occurred. You have to free the string yourself + * Returns: (allow-none): The matched substring, or %NULL if an error + * occurred. You have to free the string yourself * Since: 2.14 */ @@ -19439,16 +19933,20 @@ * g_match_info_fetch_named_pos: * @match_info: #GMatchInfo structure * @name: name of the subexpression - * @start_pos: (out) (allow-none): pointer to location where to store the start position, or %NULL - * @end_pos: (out) (allow-none): pointer to location where to store the end position, or %NULL + * @start_pos: (out) (allow-none): pointer to location where to store + * the start position, or %NULL + * @end_pos: (out) (allow-none): pointer to location where to store + * the end position, or %NULL * * Retrieves the position in bytes of the capturing parentheses named @name. * * If @name is a valid sub pattern name but it didn't match anything - * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") + * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") * then @start_pos and @end_pos are set to -1 and %TRUE is returned. * - * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged. + * Returns: %TRUE if the position was fetched, %FALSE otherwise. + * If the position cannot be fetched, @start_pos and @end_pos + * are left unchanged. * Since: 2.14 */ @@ -19457,10 +19955,12 @@ * g_match_info_fetch_pos: * @match_info: #GMatchInfo structure * @match_num: number of the sub expression - * @start_pos: (out) (allow-none): pointer to location where to store the start position, or %NULL - * @end_pos: (out) (allow-none): pointer to location where to store the end position, or %NULL + * @start_pos: (out) (allow-none): pointer to location where to store + * the start position, or %NULL + * @end_pos: (out) (allow-none): pointer to location where to store + * the end position, or %NULL * - * 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. * @@ -19474,7 +19974,9 @@ * substring. Substrings are matched in reverse order of length, so * 0 is the longest match. * - * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged + * Returns: %TRUE if the position was fetched, %FALSE otherwise. If + * the position cannot be fetched, @start_pos and @end_pos are left + * unchanged * Since: 2.14 */ @@ -19566,19 +20068,11 @@ * stops at the partial match. * When both #G_REGEX_MATCH_PARTIAL_SOFT and #G_REGEX_MATCH_PARTIAL_HARD * are set, the latter takes precedence. - * See <ulink>man:pcrepartial</ulink> for more information on partial matching. - * - * Because of the way certain internal optimizations are implemented - * the partial matching algorithm cannot be used with all patterns. - * So repeated single characters such as "a{2,4}" and repeated single - * meta-sequences such as "\d+" are not permitted if the maximum number - * of occurrences is greater than one. Optional items such as "\d?" - * (where the maximum is one) are permitted. Quantifiers with any values - * are permitted after parentheses, so the invalid examples above can be - * coded thus "(a){2,4}" and "(\d)+". If #G_REGEX_MATCH_PARTIAL or - * #G_REGEX_MATCH_PARTIAL_HARD is set - * for a pattern that does not conform to the restrictions, matching - * functions return an error. + * + * There were formerly some restrictions on the pattern for partial matching. + * The restrictions no longer apply. + * + * See pcrepartial(3) for more information on partial matching. * * Returns: %TRUE if the match was partial, %FALSE otherwise * Since: 2.14 @@ -19591,7 +20085,8 @@ * * Returns whether the previous match operation succeeded. * - * Returns: %TRUE if the previous match operation succeeded, %FALSE otherwise + * Returns: %TRUE if the previous match operation succeeded, + * %FALSE otherwise * Since: 2.14 */ @@ -19638,8 +20133,8 @@ /** * g_mem_gc_friendly: * - * 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`. */ @@ -19678,13 +20173,17 @@ * g_mem_set_vtable: * @vtable: table of memory allocation routines. * - * 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. */ @@ -19696,7 +20195,8 @@ * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it * from @mem. If @mem is %NULL it returns %NULL. * - * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem is %NULL. + * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem + * is %NULL. */ @@ -19709,18 +20209,20 @@ * Copies a block of memory @len bytes long, from @src to @dest. * The source and destination areas may overlap. * - * In order to use this function, you must include - * <filename>string.h</filename> yourself, because this macro will - * typically simply resolve to memmove() and GLib does not include - * <filename>string.h</filename> for you. + * Deprecated: 2.40: Just use memmove(). */ /** * g_message: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log a normal message. + * + * 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. */ @@ -19735,7 +20237,8 @@ * * See your C library manual for more details about mkdir(). * - * Returns: 0 if the directory was successfully created, -1 if an error occurred + * Returns: 0 if the directory was successfully created, -1 if an error + * occurred * Since: 2.6 */ @@ -19748,7 +20251,8 @@ * Create a directory if it doesn't already exist. Create intermediate * parent directories as needed, too. * - * Returns: 0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set. + * Returns: 0 if the directory already exists, or was successfully + * created. Returns -1 if an error occurred, with errno set. * Since: 2.8 */ @@ -19769,7 +20273,9 @@ * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * - * Returns: A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned and %errno will be set. + * Returns: A pointer to @tmpl, which has been modified + * to hold the directory name. In case of errors, %NULL is + * returned and %errno will be set. * Since: 2.30 */ @@ -19791,7 +20297,9 @@ * in the GLib file name encoding. Most importantly, on Windows it * should be in UTF-8. * - * Returns: A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned, and %errno will be set. + * Returns: A pointer to @tmpl, which has been modified + * to hold the directory name. In case of errors, %NULL is + * returned, and %errno will be set. * Since: 2.30 */ @@ -19811,14 +20319,19 @@ * didn't exist. The string should be in the GLib file name encoding. * Most importantly, on Windows it should be in UTF-8. * - * Returns: A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set. + * Returns: A file handle (as from open()) to the file + * opened for reading and writing. The file is opened in binary + * mode on platforms where there is a difference. The file handle + * should be closed with close(). In case of errors, -1 is + * returned and %errno will be set. */ /** * g_mkstemp_full: * @tmpl: (type filename): template filename - * @flags: flags to pass to an open() call in addition to O_EXCL and O_CREAT, which are passed automatically + * @flags: flags to pass to an open() call in addition to O_EXCL + * and O_CREAT, which are passed automatically * @mode: permissions to create the temporary file with * * Opens a temporary file. See the mkstemp() documentation @@ -19833,7 +20346,10 @@ * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * - * Returns: A file handle (as from open()) to the file opened for reading and writing. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set. + * Returns: A file handle (as from open()) to the file + * opened for reading and writing. The file handle should be + * closed with close(). In case of errors, -1 is returned + * and %errno will be set. * Since: 2.22 */ @@ -19865,7 +20381,7 @@ * It is not necessary to initialize a mutex that has been * statically allocated. * - * |[ + * |[<!-- language="C" --> * typedef struct { * GMutex m; * ... @@ -19895,10 +20411,10 @@ * 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). */ @@ -19910,11 +20426,10 @@ * 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> * * Returns: %TRUE if @mutex could be locked */ @@ -19940,7 +20455,8 @@ * Gets the position of the first child of a #GNode * which contains the given data. * - * Returns: the index of the child of @node which contains @data, or -1 if the data is not found + * Returns: the index of the child of @node which contains + * @data, or -1 if the data is not found */ @@ -19960,7 +20476,8 @@ /** * g_node_children_foreach: * @node: a #GNode - * @flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @flags: which types of children are to be visited, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @func: the function to call for each visited node * @data: user data to pass to the function * @@ -19983,7 +20500,8 @@ /** * g_node_copy_deep: * @node: a #GNode - * @copy_func: the function which is called to copy the data inside each node, or %NULL to use the original data. + * @copy_func: the function which is called to copy the data inside each node, + * or %NULL to use the original data. * @data: data to pass to @copy_func * * Recursively copies a #GNode and its data. @@ -20018,8 +20536,10 @@ /** * g_node_find: * @root: the root #GNode of the tree to search - * @order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER - * @flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @order: the order in which nodes are visited - %G_IN_ORDER, + * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER + * @flags: which types of children are to be searched, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @data: the data to find * * Finds a #GNode in a tree. @@ -20031,7 +20551,8 @@ /** * g_node_find_child: * @node: a #GNode - * @flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @flags: which types of children are to be searched, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @data: the data to find * * Finds the first child of a #GNode with the given data. @@ -20064,7 +20585,8 @@ /** * g_node_insert: * @parent: the #GNode to place @node under - * @position: the position to place @node at, with respect to its siblings If position is -1, @node is inserted as the last child of @parent + * @position: the position to place @node at, with respect to its siblings + * If position is -1, @node is inserted as the last child of @parent * @node: the #GNode to insert * * Inserts a #GNode beneath the parent at the given position. @@ -20076,7 +20598,8 @@ /** * g_node_insert_after: * @parent: the #GNode to place @node under - * @sibling: the sibling #GNode to place @node after. If sibling is %NULL, the node is inserted as the first child of @parent. + * @sibling: the sibling #GNode to place @node after. + * If sibling is %NULL, the node is inserted as the first child of @parent. * @node: the #GNode to insert * * Inserts a #GNode beneath the parent after the given sibling. @@ -20088,7 +20611,8 @@ /** * g_node_insert_before: * @parent: the #GNode to place @node under - * @sibling: the sibling #GNode to place @node before. If sibling is %NULL, the node is inserted as the last child of @parent. + * @sibling: the sibling #GNode to place @node before. + * If sibling is %NULL, the node is inserted as the last child of @parent. * @node: the #GNode to insert * * Inserts a #GNode beneath the parent before the given sibling. @@ -20158,7 +20682,8 @@ /** * g_node_n_nodes: * @root: a #GNode - * @flags: which types of children are to be counted, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @flags: which types of children are to be counted, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * * Gets the number of nodes in a tree. * @@ -20213,9 +20738,14 @@ /** * g_node_traverse: * @root: the root #GNode of the tree to traverse - * @order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. - * @flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * @max_depth: the maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If depth is 1, only the root is visited. If depth is 2, the root and its children are visited. And so on. + * @order: the order in which nodes are visited - %G_IN_ORDER, + * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. + * @flags: which types of children are to be visited, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @max_depth: the maximum depth of the traversal. Nodes below this + * depth will not be visited. If max_depth is -1 all nodes in + * the tree are visited. If depth is 1, only the root is visited. + * If depth is 2, the root and its children are visited. And so on. * @func: the function to call for each visited #GNode * @data: user data to pass to the function * @@ -20263,16 +20793,19 @@ /** * g_on_error_query: - * @prg_name: 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) + * @prg_name: 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) * * 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, @@ -20294,17 +20827,17 @@ * 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. */ @@ -20312,13 +20845,14 @@ /** * g_on_error_stack_trace: - * @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option. + * @prg_name: the program name, needed by gdb for the "[S]tack trace" + * option * - * 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. */ @@ -20327,7 +20861,9 @@ /** * g_once: * @once: a #GOnce structure - * @func: the #GThreadFunc function associated to @once. This function is called only once, regardless of the number of times it and its associated #GOnce struct are passed to g_once(). + * @func: the #GThreadFunc function associated to @once. This function + * is called only once, regardless of the number of times it and + * its associated #GOnce struct are passed to g_once(). * @arg: data to be passed to @func * * The first call to this routine by a process with a given #GOnce @@ -20343,7 +20879,7 @@ * Calling g_once() recursively on the same #GOnce struct in * @func will lead to a deadlock. * - * |[ + * |[<!-- language="C" --> * gpointer * get_debug_flags (void) * { @@ -20373,20 +20909,21 @@ * 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)) + * 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); + * g_once_init_leave (&initialization_value, setup_value); * } * - * /** use initialization_value here **/ + * // use initialization_value here * ]| * - * Returns: %TRUE if the initialization section should be entered, %FALSE and blocks otherwise + * Returns: %TRUE if the initialization section should be entered, + * %FALSE and blocks otherwise * Since: 2.14 */ @@ -20431,7 +20968,9 @@ * * See your C library manual for more details about open(). * - * Returns: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from open(). + * Returns: a new file descriptor, or -1 if an error occurred. + * The return value can be used exactly like the return value + * from open(). * Since: 2.6 */ @@ -20454,8 +20993,10 @@ /** * g_option_context_add_main_entries: * @context: a #GOptionContext - * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s - * @translation_domain: (allow-none): a translation domain to use for translating the <option>--help</option> output for the options in @entries with gettext(), or %NULL + * @entries: a %NULL-terminated array of #GOptionEntrys + * @translation_domain: (allow-none): a translation domain to use for translating + * the `--help` output for the options in @entries + * with gettext(), or %NULL * * A convenience function which creates a main group if it doesn't * exist, adds the @entries to it and sets the translation domain. @@ -20496,12 +21037,12 @@ * @group: (allow-none): the #GOptionGroup to create help for, or %NULL * * 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)`. * * Returns: A newly allocated string containing the help text * Since: 2.14 @@ -20512,7 +21053,7 @@ * g_option_context_get_help_enabled: * @context: a #GOptionContext * - * Returns whether automatic <option>--help</option> generation + * Returns whether automatic `--help` generation * is turned on for @context. See g_option_context_set_help_enabled(). * * Returns: %TRUE if automatic help generation is turned on. @@ -20538,7 +21079,9 @@ * * Returns a pointer to the main group of @context. * - * Returns: the main group of @context, or %NULL if @context doesn't have a main group. Note that group belongs to @context and should not be modified or freed. + * Returns: the main group of @context, or %NULL if @context doesn't + * have a main group. Note that group belongs to @context and should + * not be modified or freed. * Since: 2.6 */ @@ -20556,7 +21099,9 @@ /** * g_option_context_new: - * @parameter_string: a string which is displayed in the first line of <option>--help</option> output, after the usage summary <literal><replaceable>programname</replaceable> [OPTION...]</literal> + * @parameter_string: (allow-none): a string which is displayed in + * the first line of `--help` output, after the usage summary + * `programname [OPTION...]` * * Creates a new option context. * @@ -20578,7 +21123,8 @@ * function set with g_option_context_set_translate_func(), so * it should normally be passed untranslated. * - * Returns: a newly created #GOptionContext, which must be freed with g_option_context_free() after use. + * Returns: a newly created #GOptionContext, which must be + * freed with g_option_context_free() after use. * Since: 2.6 */ @@ -20602,30 +21148,60 @@ * 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. * - * Returns: %TRUE if the parsing was successful, %FALSE if an error occurred + * Returns: %TRUE if the parsing was successful, + * %FALSE if an error occurred * Since: 2.6 */ /** + * g_option_context_parse_strv: + * @context: a #GOptionContext + * @arguments: (inout) (array null-terminated=1): a pointer to the + * command line arguments (which must be in UTF-8 on Windows) + * @error: a return location for errors + * + * Parses the command line arguments. + * + * This function is similar to g_option_context_parse() except that it + * respects the normal memory rules when dealing with a strv instead of + * 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. + * + * Returns: %TRUE if the parsing was successful, + * %FALSE if an error occurred + * Since: 2.40 + */ + + +/** * g_option_context_set_description: * @context: a #GOptionContext - * @description: (allow-none): a string to be shown in <option>--help</option> output after the list of options, or %NULL + * @description: (allow-none): a string to be shown in `--help` output + * after the list of options, or %NULL * - * 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()). @@ -20637,14 +21213,12 @@ /** * g_option_context_set_help_enabled: * @context: a #GOptionContext - * @help_enabled: %TRUE to enable <option>--help</option>, %FALSE to disable it + * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it * - * 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 */ @@ -20653,7 +21227,8 @@ /** * g_option_context_set_ignore_unknown_options: * @context: a #GOptionContext - * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce an error when unknown options are met + * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce + * an error when unknown options are met * * Sets whether to ignore unknown options or not. If an argument is * ignored, it is left in the @argv array after parsing. By default, @@ -20675,7 +21250,7 @@ * 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 */ @@ -20684,11 +21259,11 @@ /** * g_option_context_set_summary: * @context: a #GOptionContext - * @summary: (allow-none): a string to be shown in <option>--help</option> output before the list of options, or %NULL + * @summary: (allow-none): a string to be shown in `--help` output + * before the list of options, or %NULL * - * 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 @@ -20706,8 +21281,8 @@ * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * * 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()), @@ -20736,7 +21311,7 @@ /** * g_option_group_add_entries: * @group: a #GOptionGroup - * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s + * @entries: a %NULL-terminated array of #GOptionEntrys * * Adds the options specified in @entries to @group. * @@ -20748,8 +21323,8 @@ * g_option_group_free: * @group: a #GOptionGroup * - * 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 */ @@ -20757,15 +21332,22 @@ /** * g_option_group_new: - * @name: the name for the option group, this is used to provide help for the options in this group with <option>--help-</option>@name - * @description: a description for this group to be shown in <option>--help</option>. This string is translated using the translation domain or translation function of the group - * @help_description: a description for the <option>--help-</option>@name option. This string is translated using the translation domain or translation function of the group - * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL + * @name: the name for the option group, this is used to provide + * help for the options in this group with `--help-`@name + * @description: a description for this group to be shown in + * `--help`. This string is translated using the translation + * domain or translation function of the group + * @help_description: a description for the `--help-`@name option. + * This string is translated using the translation domain or translation function + * of the group + * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, + * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL * @destroy: (allow-none): a function that will be called to free @user_data, or %NULL * * Creates a new #GOptionGroup. * - * Returns: a newly created option group. It should be added to a #GOptionContext or freed with g_option_group_free(). + * Returns: a newly created option group. It should be added + * to a #GOptionContext or freed with g_option_group_free(). * Since: 2.6 */ @@ -20810,10 +21392,9 @@ * @data: (allow-none): user data to pass to @func, or %NULL * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL * - * 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(). @@ -20836,21 +21417,23 @@ /** * g_parse_debug_string: - * @string: (allow-none): a list of debug options separated by colons, spaces, or commas, or %NULL. - * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate strings with bit flags. - * @nkeys: the number of #GDebugKey<!-- -->s in the array. + * @string: (allow-none): a list of debug options separated by colons, spaces, or + * commas, or %NULL. + * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate + * strings with bit flags. + * @nkeys: the number of #GDebugKeys in the array. * * Parses a string containing debugging options * 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. * * Returns: the combined set of bit flags. @@ -20868,7 +21451,8 @@ * separators (and on Windows, possibly a drive letter), a single * separator is returned. If @file_name is empty, it gets ".". * - * Returns: a newly allocated string containing the last component of the filename + * Returns: a newly allocated string containing the last + * component of the filename */ @@ -20933,7 +21517,8 @@ /** * g_pattern_match: * @pspec: a #GPatternSpec - * @string_length: the length of @string (in bytes, i.e. strlen(), <emphasis>not</emphasis> g_utf8_strlen()) + * @string_length: the length of @string (in bytes, i.e. strlen(), + * not g_utf8_strlen()) * @string: the UTF-8 encoded string to match * @string_reversed: (allow-none): the reverse of @string or %NULL * @@ -20951,10 +21536,9 @@ * 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. * * Returns: %TRUE if @string matches @pspec */ @@ -21085,9 +21669,11 @@ * 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(). * - * Returns: the number of entries in @fds whose %revents fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted. + * Returns: the number of entries in @fds whose %revents fields + * were filled in, or 0 if the operation timed out, or -1 on error or + * if the call was interrupted. * Since: 2.20 */ @@ -21098,16 +21684,13 @@ * @format: printf()-style format string * @...: arguments to @format * - * 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 */ @@ -21119,7 +21702,9 @@ * @...: the parameters to insert into the format string * * Outputs a formatted message via the print handler. - * The default print handler simply outputs the message to stdout. + * The default print handler simply outputs the message to stdout, without + * appending a trailing new-line character. Typically, @format should end with + * its own new-line character. * * g_print() should not be used from within libraries for debugging * messages, since it may be redirected by applications to special @@ -21135,7 +21720,9 @@ * @...: the parameters to insert into the format string * * Outputs a formatted message via the error message handler. - * The default handler simply outputs the message to stderr. + * The default handler simply outputs the message to stderr, without appending + * a trailing new-line character. Typically, @format should end with its own + * new-line character. * * g_printerr() should not be used from within libraries. * Instead g_log() should be used, or the convenience functions @@ -21145,12 +21732,17 @@ /** * g_printf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard printf() function which supports * positional parameters, as specified in the Single Unix Specification. * + * As with the standard printf(), this does not automatically append a trailing + * new-line character to the message, so typically @format should end with its + * own new-line character. + * * Returns: the number of bytes printed. * Since: 2.2 */ @@ -21228,9 +21820,8 @@ * @format: printf()-style format string * @...: arguments to @format * - * 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 @@ -21239,8 +21830,8 @@ /** * g_ptr_array_add: - * @array: a #GPtrArray. - * @data: the pointer to add. + * @array: a #GPtrArray + * @data: the pointer to add * * Adds a pointer to the end of the pointer array. The array will grow * in size automatically if necessary. @@ -21261,8 +21852,8 @@ /** * g_ptr_array_free: - * @array: a #GPtrArray. - * @free_seg: if %TRUE the actual pointer array is freed as well. + * @array: a #GPtrArray + * @free_seg: if %TRUE the actual pointer array is freed as well * * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE * it frees the memory block holding the elements as well. Pass %FALSE @@ -21271,22 +21862,39 @@ * 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. * - * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. The pointer array should be freed using g_free(). + * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. + * The pointer array should be freed using g_free(). */ /** * g_ptr_array_index: - * @array: a #GPtrArray. - * @index_: the index of the pointer to return. + * @array: a #GPtrArray + * @index_: the index of the pointer to return * * Returns the pointer at the given index of the pointer array. * - * Returns: the pointer at the given index. + * This does not perform bounds checking on the given @index_, + * so you are responsible for checking it against the array length. + * + * Returns: the pointer at the given index + */ + + +/** + * g_ptr_array_insert: + * @array: a #GPtrArray + * @index_: the index to place the new element at, or -1 to append + * @data: the pointer to add. + * + * Inserts an element into the pointer array at the given index. The + * array will grow in size automatically if necessary. + * + * Since: 2.40 */ @@ -21295,38 +21903,40 @@ * * Creates a new #GPtrArray with a reference count of 1. * - * Returns: the new #GPtrArray. + * Returns: the new #GPtrArray */ /** * g_ptr_array_new_full: - * @reserved_size: number of pointers preallocated. - * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL. + * @reserved_size: number of pointers preallocated + * @element_free_func: (allow-none): A function to free elements with + * destroy @array or %NULL * * Creates a new #GPtrArray with @reserved_size pointers preallocated * 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. * - * Returns: A new #GPtrArray. + * Returns: A new #GPtrArray * Since: 2.30 */ /** * g_ptr_array_new_with_free_func: - * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL. + * @element_free_func: (allow-none): A function to free elements with + * destroy @array or %NULL * - * 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. * - * Returns: A new #GPtrArray. + * Returns: A new #GPtrArray * Since: 2.22 */ @@ -21345,8 +21955,8 @@ /** * g_ptr_array_remove: - * @array: a #GPtrArray. - * @data: the pointer to remove. + * @array: a #GPtrArray + * @data: the pointer to remove * * Removes the first occurrence of the given pointer from the pointer * array. The following elements are moved down one place. If @array @@ -21356,76 +21966,79 @@ * It returns %TRUE if the pointer was removed, or %FALSE if the * pointer was not found. * - * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found in the array. + * Returns: %TRUE if the pointer is removed, %FALSE if the pointer + * is not found in the array */ /** * g_ptr_array_remove_fast: - * @array: a #GPtrArray. - * @data: the pointer to remove. + * @array: a #GPtrArray + * @data: the pointer to remove * * 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 * pointer was not found. * - * Returns: %TRUE if the pointer was found in the array. + * Returns: %TRUE if the pointer was found in the array */ /** * g_ptr_array_remove_index: - * @array: a #GPtrArray. - * @index_: the index of the pointer to remove. + * @array: a #GPtrArray + * @index_: the index of the pointer to remove * - * 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. * - * Returns: the pointer which was removed. + * Returns: the pointer which was removed */ /** * g_ptr_array_remove_index_fast: - * @array: a #GPtrArray. - * @index_: the index of the pointer to remove. + * @array: a #GPtrArray + * @index_: the index of the pointer to remove * - * 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. * - * Returns: the pointer which was removed. + * Returns: the pointer which was removed */ /** * g_ptr_array_remove_range: - * @array: a @GPtrArray. - * @index_: the index of the first pointer to remove. - * @length: the number of pointers to remove. + * @array: a @GPtrArray + * @index_: the index of the first pointer to remove + * @length: the number of pointers to remove * * 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. * + * Returns: the @array * Since: 2.4 */ /** * g_ptr_array_set_free_func: - * @array: A #GPtrArray. - * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL. + * @array: A #GPtrArray + * @element_free_func: (allow-none): A function to free elements with + * destroy @array or %NULL * * Sets a function for freeing each element when @array is destroyed * either via g_ptr_array_unref(), when g_ptr_array_free() is called @@ -21437,8 +22050,8 @@ /** * g_ptr_array_set_size: - * @array: a #GPtrArray. - * @length: the new length of the pointer array. + * @array: a #GPtrArray + * @length: the new length of the pointer array * * Sets the size of the array. When making the array larger, * newly-added elements will be set to %NULL. When making it smaller, @@ -21449,30 +22062,30 @@ /** * g_ptr_array_sized_new: - * @reserved_size: number of pointers preallocated. + * @reserved_size: number of pointers preallocated * * Creates a new #GPtrArray with @reserved_size pointers preallocated * 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. * - * Returns: the new #GPtrArray. + * Returns: the new #GPtrArray */ /** * g_ptr_array_sort: - * @array: a #GPtrArray. - * @compare_func: comparison function. + * @array: a #GPtrArray + * @compare_func: comparison function * * Sorts the array, using @compare_func which should be a qsort()-style * 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. */ @@ -21480,16 +22093,16 @@ /** * g_ptr_array_sort_with_data: - * @array: a #GPtrArray. - * @compare_func: comparison function. - * @user_data: data to pass to @compare_func. + * @array: a #GPtrArray + * @compare_func: comparison function + * @user_data: data to pass to @compare_func * * 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. */ @@ -21497,7 +22110,7 @@ /** * g_ptr_array_unref: - * @array: A #GPtrArray. + * @array: A #GPtrArray * * Atomically decrements the reference count of @array by one. If the * reference count drops to 0, the effect is the same as calling @@ -21525,7 +22138,7 @@ /** * g_quark_from_static_string: - * @string: (allow-none): a string. + * @string: (allow-none): a string * * Gets the #GQuark identifying the given (static) string. If the * string does not currently have an associated #GQuark, a new #GQuark @@ -21534,25 +22147,25 @@ * 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). * - * Returns: the #GQuark identifying the string, or 0 if @string is %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ /** * g_quark_from_string: - * @string: (allow-none): a string. + * @string: (allow-none): a string * * Gets the #GQuark identifying the given string. If the string does * not currently have an associated #GQuark, a new #GQuark is created, * using a copy of the string. * - * Returns: the #GQuark identifying the string, or 0 if @string is %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is %NULL */ @@ -21568,7 +22181,7 @@ /** * g_quark_try_string: - * @string: (allow-none): a string. + * @string: (allow-none): a string * * Gets the #GQuark associated with the given string, or 0 if string is * %NULL or it has no associated #GQuark. @@ -21576,7 +22189,8 @@ * 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(). * - * Returns: the #GQuark associated with the string, or 0 if @string is %NULL or there is no #GQuark associated with it. + * Returns: the #GQuark associated with the string, or 0 if @string is + * %NULL or there is no #GQuark associated with it */ @@ -21599,7 +22213,7 @@ * queue consist of pointers to data, the pointers are copied, but the * actual data is not. * - * Returns: A copy of @queue + * Returns: a copy of @queue * Since: 2.4 */ @@ -21607,7 +22221,7 @@ /** * g_queue_delete_link: * @queue: a #GQueue - * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue + * @link_: a #GList link that must be part of @queue * * Removes @link_ from @queue and frees it. * @@ -21624,7 +22238,7 @@ * * Finds the first link in @queue which contains @data. * - * Returns: The first link in @queue which contains @data. + * Returns: the first link in @queue which contains @data * Since: 2.4 */ @@ -21633,7 +22247,8 @@ * g_queue_find_custom: * @queue: a #GQueue * @data: user data passed to @func - * @func: a #GCompareFunc to call for each element. It should return 0 when the desired element is found + * @func: a #GCompareFunc to call for each element. It should return 0 + * when the desired element is found * * Finds an element in a #GQueue, using a supplied function to find the * desired element. It iterates over the queue, calling the given function @@ -21641,7 +22256,7 @@ * takes two gconstpointer arguments, the #GQueue element's data as the * first argument and the given user data as the second argument. * - * Returns: The found link, or %NULL if it wasn't found + * Returns: the found link, or %NULL if it wasn't found * Since: 2.4 */ @@ -21661,17 +22276,14 @@ /** * g_queue_free: - * @queue: a #GQueue. + * @queue: a #GQueue * - * 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. */ @@ -21680,8 +22292,8 @@ * @queue: a pointer to a #GQueue * @free_func: the function to be called to free each 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. + * 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 */ @@ -21693,7 +22305,7 @@ * * Returns the number of items in @queue. * - * Returns: The number of items in @queue. + * Returns: the number of items in @queue * Since: 2.4 */ @@ -21701,11 +22313,12 @@ /** * g_queue_index: * @queue: a #GQueue - * @data: the data to find. + * @data: the data to find * * Returns the position of the first element in @queue which contains @data. * - * Returns: The position of the first element in @queue which contains @data, or -1 if no element in @queue contains @data. + * Returns: the position of the first element in @queue which + * contains @data, or -1 if no element in @queue contains @data * Since: 2.4 */ @@ -21726,7 +22339,7 @@ /** * g_queue_insert_after: * @queue: a #GQueue - * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue + * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue after @sibling @@ -21740,7 +22353,7 @@ /** * g_queue_insert_before: * @queue: a #GQueue - * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue + * @sibling: a #GList link that must be part of @queue * @data: the data to insert * * Inserts @data into @queue before @sibling. @@ -21755,8 +22368,12 @@ * g_queue_insert_sorted: * @queue: a #GQueue * @data: the data to insert - * @func: the #GCompareDataFunc used to compare elements in the queue. It is called with two elements of the @queue and @user_data. It should return 0 if the elements are equal, a negative value if the first element comes before the second, and a positive value if the second element comes before the first. - * @user_data: user data passed to @func. + * @func: the #GCompareDataFunc used to compare elements in the queue. It is + * called with two elements of the @queue and @user_data. It should + * return 0 if the elements are equal, a negative value if the first + * element comes before the second, and a positive value if the second + * element comes before the first. + * @user_data: user data passed to @func * * Inserts @data into @queue using @func to determine the new position. * @@ -21770,18 +22387,19 @@ * * Returns %TRUE if the queue is empty. * - * Returns: %TRUE if the queue is empty. + * Returns: %TRUE if the queue is empty */ /** * g_queue_link_index: * @queue: a #GQueue - * @link_: A #GList link + * @link_: a #GList link * * Returns the position of @link_ in @queue. * - * Returns: The position of @link_, or -1 if the link is not part of @queue + * Returns: the position of @link_, or -1 if the link is + * not part of @queue * Since: 2.4 */ @@ -21791,17 +22409,18 @@ * * Creates a new #GQueue. * - * Returns: a new #GQueue. + * Returns: a newly allocated #GQueue */ /** * g_queue_peek_head: - * @queue: a #GQueue. + * @queue: a #GQueue * * Returns the first element of the queue. * - * Returns: the data of the first element in the queue, or %NULL if the queue is empty. + * Returns: the data of the first element in the queue, or %NULL + * if the queue is empty */ @@ -21809,7 +22428,7 @@ * g_queue_peek_head_link: * @queue: a #GQueue * - * Returns the first link in @queue + * Returns the first link in @queue. * * Returns: the first link in @queue, or %NULL if @queue is empty * Since: 2.4 @@ -21819,11 +22438,12 @@ /** * g_queue_peek_nth: * @queue: a #GQueue - * @n: the position of the element. + * @n: the position of the element * * Returns the @n'th element of @queue. * - * Returns: The data for the @n'th element of @queue, or %NULL if @n is off the end of @queue. + * Returns: the data for the @n'th element of @queue, + * or %NULL if @n is off the end of @queue * Since: 2.4 */ @@ -21835,18 +22455,20 @@ * * Returns the link at the given position * - * Returns: The link at the @n'th position, or %NULL if @n is off the end of the list + * Returns: the link at the @n'th position, or %NULL + * if @n is off the end of the list * Since: 2.4 */ /** * g_queue_peek_tail: - * @queue: a #GQueue. + * @queue: a #GQueue * * Returns the last element of the queue. * - * Returns: the data of the last element in the queue, or %NULL if the queue is empty. + * Returns: the data of the last element in the queue, or %NULL + * if the queue is empty */ @@ -21854,7 +22476,7 @@ * g_queue_peek_tail_link: * @queue: a #GQueue * - * Returns the last link @queue. + * Returns the last link in @queue. * * Returns: the last link in @queue, or %NULL if @queue is empty * Since: 2.4 @@ -21863,32 +22485,34 @@ /** * g_queue_pop_head: - * @queue: a #GQueue. + * @queue: a #GQueue * - * Removes the first element of the queue. + * Removes the first element of the queue and returns its data. * - * Returns: the data of the first element in the queue, or %NULL if the queue is empty. + * Returns: the data of the first element in the queue, or %NULL + * if the queue is empty */ /** * g_queue_pop_head_link: - * @queue: a #GQueue. + * @queue: a #GQueue * - * Removes the first element of the queue. + * Removes and returns the first element of the queue. * - * Returns: the #GList element at the head of the queue, or %NULL if the queue is empty. + * Returns: the #GList element at the head of the queue, or %NULL + * if the queue is empty */ /** * g_queue_pop_nth: * @queue: a #GQueue - * @n: the position of the element. + * @n: the position of the element * - * Removes the @n'th element of @queue. + * Removes the @n'th element of @queue and returns its data. * - * Returns: the element's data, or %NULL if @n is off the end of @queue. + * Returns: the element's data, or %NULL if @n is off the end of @queue * Since: 2.4 */ @@ -21900,28 +22524,30 @@ * * Removes and returns the link at the given position. * - * Returns: The @n'th link, or %NULL if @n is off the end of @queue. + * Returns: the @n'th link, or %NULL if @n is off the end of @queue * Since: 2.4 */ /** * g_queue_pop_tail: - * @queue: a #GQueue. + * @queue: a #GQueue * - * Removes the last element of the queue. + * Removes the last element of the queue and returns its data. * - * Returns: the data of the last element in the queue, or %NULL if the queue is empty. + * Returns: the data of the last element in the queue, or %NULL + * if the queue is empty */ /** * g_queue_pop_tail_link: - * @queue: a #GQueue. + * @queue: a #GQueue * - * Removes the last element of the queue. + * Removes and returns the last element of the queue. * - * Returns: the #GList element at the tail of the queue, or %NULL if the queue is empty. + * Returns: the #GList element at the tail of the queue, or %NULL + * if the queue is empty */ @@ -21936,8 +22562,8 @@ /** * g_queue_push_head_link: - * @queue: a #GQueue. - * @link_: a single #GList element, <emphasis>not</emphasis> a list with more than one element. + * @queue: a #GQueue + * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the head of the queue. */ @@ -21947,9 +22573,11 @@ * g_queue_push_nth: * @queue: a #GQueue * @data: the data for the new element - * @n: the position to insert the new element. If @n is negative or larger than the number of elements in the @queue, the element is added to the end of the queue. + * @n: the position to insert the new element. If @n is negative or + * larger than the number of elements in the @queue, the element is + * added to the end of the queue. * - * Inserts a new element into @queue at the given position + * Inserts a new element into @queue at the given position. * * Since: 2.4 */ @@ -21958,7 +22586,9 @@ /** * g_queue_push_nth_link: * @queue: a #GQueue - * @n: the position to insert the link. If this is negative or larger than the number of elements in @queue, the link is added to the end of @queue. + * @n: the position to insert the link. If this is negative or larger than + * the number of elements in @queue, the link is added to the end of + * @queue. * @link_: the link to add to @queue * * Inserts @link into @queue at the given position. @@ -21969,8 +22599,8 @@ /** * g_queue_push_tail: - * @queue: a #GQueue. - * @data: the data for the new element. + * @queue: a #GQueue + * @data: the data for the new element * * Adds a new element at the tail of the queue. */ @@ -21978,8 +22608,8 @@ /** * g_queue_push_tail_link: - * @queue: a #GQueue. - * @link_: a single #GList element, <emphasis>not</emphasis> a list with more than one element. + * @queue: a #GQueue + * @link_: a single #GList element, not a list with more than one element * * Adds a new element at the tail of the queue. */ @@ -21988,7 +22618,7 @@ /** * g_queue_remove: * @queue: a #GQueue - * @data: data to remove. + * @data: the data to remove * * Removes the first element in @queue that contains @data. * @@ -22000,7 +22630,7 @@ /** * g_queue_remove_all: * @queue: a #GQueue - * @data: data to remove + * @data: the data to remove * * Remove all elements whose data equals @data from @queue. * @@ -22022,7 +22652,10 @@ /** * g_queue_sort: * @queue: a #GQueue - * @compare_func: the #GCompareDataFunc used to sort @queue. This function is passed two elements of the queue and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first. + * @compare_func: the #GCompareDataFunc used to sort @queue. This function + * is passed two elements of the queue and should return 0 if they are + * equal, a negative value if the first comes before the second, and + * a positive value if the second comes before the first. * @user_data: user data passed to @compare_func * * Sorts @queue using @compare_func. @@ -22034,12 +22667,12 @@ /** * g_queue_unlink: * @queue: a #GQueue - * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue + * @link_: a #GList link that must be part of @queue * - * 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 */ @@ -22047,55 +22680,55 @@ /** * g_rand_boolean: - * @rand_: a #GRand. + * @rand_: a #GRand * - * 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. * - * Returns: a random #gboolean. + * Returns: a random #gboolean */ /** * g_rand_copy: - * @rand_: a #GRand. + * @rand_: a #GRand * * Copies a #GRand into a new one with the same exact state as before. * This way you can take a snapshot of the random number generator for * replaying later. * - * Returns: the new #GRand. + * Returns: the new #GRand * Since: 2.4 */ /** * g_rand_double: - * @rand_: a #GRand. + * @rand_: a #GRand * * Returns the next random #gdouble from @rand_ equally distributed over * the range [0..1). * - * Returns: A random number. + * Returns: a random number */ /** * g_rand_double_range: - * @rand_: a #GRand. - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @rand_: a #GRand + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns the next random #gdouble from @rand_ equally distributed over * the range [@begin..@end). * - * Returns: A random number. + * Returns: a random number */ /** * g_rand_free: - * @rand_: a #GRand. + * @rand_: a #GRand * * Frees the memory allocated for the #GRand. */ @@ -22103,25 +22736,25 @@ /** * g_rand_int: - * @rand_: a #GRand. + * @rand_: a #GRand * * Returns the next random #guint32 from @rand_ equally distributed over * the range [0..2^32-1]. * - * Returns: A random number. + * Returns: a random number */ /** * g_rand_int_range: - * @rand_: a #GRand. - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @rand_: a #GRand + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns the next random #gint32 from @rand_ equally distributed over * the range [@begin..@end-1]. * - * Returns: A random number. + * Returns: a random number */ @@ -22129,39 +22762,42 @@ * g_rand_new: * * 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). + * either from `/dev/urandom` (if existing) or from the current time + * (as a fallback). * - * Returns: the new #GRand. + * On Windows, the seed is taken from rand_s(). + * + * Returns: the new #GRand */ /** * g_rand_new_with_seed: - * @seed: a value to initialize the random number generator. + * @seed: a value to initialize the random number generator * * Creates a new random number generator initialized with @seed. * - * Returns: the new #GRand. + * Returns: the new #GRand */ /** * g_rand_new_with_seed_array: - * @seed: an array of seeds to initialize the random number generator. - * @seed_length: an array of seeds to initialize the random number generator. + * @seed: an array of seeds to initialize the random number generator + * @seed_length: an array of seeds to initialize the random number + * generator * * Creates a new random number generator initialized with @seed. * - * Returns: the new #GRand. + * Returns: the new #GRand * Since: 2.4 */ /** * g_rand_set_seed: - * @rand_: a #GRand. - * @seed: a value to reinitialize the random number generator. + * @rand_: a #GRand + * @seed: a value to reinitialize the random number generator * * Sets the seed for the random number generator #GRand to @seed. */ @@ -22169,15 +22805,15 @@ /** * g_rand_set_seed_array: - * @rand_: a #GRand. + * @rand_: a #GRand * @seed: array to initialize with * @seed_length: length of array * - * 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 */ @@ -22186,9 +22822,10 @@ /** * g_random_boolean: * - * Returns a random #gboolean. This corresponds to a unbiased coin toss. + * Returns a random #gboolean. + * This corresponds to a unbiased coin toss. * - * Returns: a random #gboolean. + * Returns: a random #gboolean */ @@ -22197,18 +22834,19 @@ * * Returns a random #gdouble equally distributed over the range [0..1). * - * Returns: A random number. + * Returns: a random number */ /** * g_random_double_range: - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * - * Returns a random #gdouble equally distributed over the range [@begin..@end). + * Returns a random #gdouble equally distributed over the range + * [@begin..@end). * - * Returns: A random number. + * Returns: a random number */ @@ -22218,34 +22856,34 @@ * Return a random #guint32 equally distributed over the range * [0..2^32-1]. * - * Returns: A random number. + * Returns: a random number */ /** * g_random_int_range: - * @begin: lower closed bound of the interval. - * @end: upper open bound of the interval. + * @begin: lower closed bound of the interval + * @end: upper open bound of the interval * * Returns a random #gint32 equally distributed over the range * [@begin..@end-1]. * - * Returns: A random number. + * Returns: a random number */ /** * g_random_set_seed: - * @seed: a value to reinitialize the global random number generator. + * @seed: a value to reinitialize the global random number generator * * 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. */ /** * g_realloc: - * @mem: the memory to reallocate + * @mem: (allow-none): the memory to reallocate * @n_bytes: new size of the memory in bytes * * Reallocates the memory pointed to by @mem, so that it now has space for @@ -22260,7 +22898,7 @@ /** * g_realloc_n: - * @mem: the memory to reallocate + * @mem: (allow-none): the memory to reallocate * @n_blocks: the number of blocks to allocate * @n_block_bytes: the size of each block in bytes * @@ -22302,7 +22940,7 @@ * It is not necessary to initialise a recursive mutex that has been * statically allocated. * - * |[ + * |[<!-- language="C" --> * typedef struct { * GRecMutex m; * ... @@ -22370,7 +23008,8 @@ /** * g_regex_check_replacement: * @replacement: the replacement string - * @has_references: (out) (allow-none): location to store information about references in @replacement or %NULL + * @has_references: (out) (allow-none): location to store information about + * references in @replacement or %NULL * @error: location to store error * * Checks whether @replacement is a valid replacement string @@ -22480,6 +23119,19 @@ /** + * g_regex_get_max_lookbehind: + * @regex: a #GRegex structure + * + * Gets the number of characters in the longest lookbehind assertion in the + * pattern. This information is useful when doing multi-segment matching using + * the partial matching facilities. + * + * Returns: the number of characters in the longest lookbehind assertion. + * Since: 2.38 + */ + + +/** * g_regex_get_pattern: * @regex: a #GRegex structure * @@ -22498,7 +23150,8 @@ * * Retrieves the number of the subexpression named @name. * - * Returns: The number of the subexpression or -1 if @name does not exists + * Returns: The number of the subexpression or -1 if @name + * does not exists * Since: 2.14 */ @@ -22508,7 +23161,8 @@ * @regex: a #GRegex structure from g_regex_new() * @string: the string to scan for matches * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * * Scans for a match in string for the pattern in @regex. * The @match_options are combined with the match options specified @@ -22523,16 +23177,16 @@ * 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); + * g_regex_match (regex, string, 0, &match_info); * while (g_match_info_matches (match_info)) * { * gchar *word = g_match_info_fetch (match_info, 0); @@ -22559,7 +23213,8 @@ * @regex: a #GRegex structure from g_regex_new() * @string: the string to scan for matches * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * * Using the standard algorithm for regular expression matching only * the longest match in the string is retrieved. This function uses @@ -22588,21 +23243,22 @@ * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * * Using the standard algorithm for regular expression matching only * the longest match in the string is retrieved, it is not possible * to obtain all the available matches. For instance matching - * "<a> <b> <c>" against the pattern "<.*>" - * you get "<a> <b> <c>". + * "<a> <b> <c>" against the pattern "<.*>" + * 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 "<.*>" - * you would obtain three matches: "<a> <b> <c>", - * "<a> <b>" and "<a>". + * "<a> <b> <c>" against the pattern "<.*>;" + * you would obtain three matches: "<a> <b> <c>", + * "<a> <b>" and "<a>". * * The number of matched strings is retrieved using * g_match_info_get_match_count(). To obtain the matched strings and @@ -22640,7 +23296,8 @@ * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * * Scans for a match in string for the pattern in @regex. @@ -22665,23 +23322,23 @@ * 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); + * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error); * while (g_match_info_matches (match_info)) * { * gchar *word = g_match_info_fetch (match_info, 0); * g_print ("Found: %s\n", word); * g_free (word); - * g_match_info_next (match_info, &error); + * g_match_info_next (match_info, &error); * } * g_match_info_free (match_info); * g_regex_unref (regex); @@ -22731,7 +23388,8 @@ * Compiles the regular expression to an internal form, and does * the initial setup of the #GRegex structure. * - * Returns: a #GRegex structure. Call g_regex_unref() when you are done with it + * Returns: a #GRegex structure. Call g_regex_unref() when you + * are done with it * Since: 2.14 */ @@ -22759,40 +23417,20 @@ * * 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 '\\'. + * '\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 '\\'. + * * 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(). * @@ -22829,7 +23467,7 @@ * * 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, @@ -22846,7 +23484,7 @@ * return FALSE; * } * - * /* ... */ + * ... * * GRegex *reg; * GHashTable *h; @@ -22863,7 +23501,7 @@ * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); * g_hash_table_destroy (h); * - * /* ... */ + * ... * ]| * * Returns: a newly allocated string containing the replacements @@ -22919,7 +23557,8 @@ * For example splitting "ab c" using as a separator "\s*", you will get * "a", "b" and "c". * - * Returns: (transfer full): a %NULL-terminated gchar ** array. Free it using g_strfreev() + * Returns: (transfer full): a %NULL-terminated gchar ** array. Free + * it using g_strfreev() * Since: 2.14 */ @@ -22931,7 +23570,8 @@ * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match time option flags - * @max_tokens: the maximum number of tokens to split @string into. If this is less than 1, the string is split completely + * @max_tokens: the maximum number of tokens to split @string into. + * If this is less than 1, the string is split completely * @error: return location for a #GError * * Breaks the string on the pattern, and returns an array of the tokens. @@ -22956,7 +23596,8 @@ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern * that begins with any kind of lookbehind assertion, such as "\b". * - * Returns: (transfer full): a %NULL-terminated gchar ** array. Free it using g_strfreev() + * Returns: (transfer full): a %NULL-terminated gchar ** array. Free + * it using g_strfreev() * Since: 2.14 */ @@ -22996,7 +23637,8 @@ * characters. For example splitting "ab c" using as a separator * "\s*", you will get "a", "b" and "c". * - * Returns: (transfer full): a %NULL-terminated array of strings. Free it using g_strfreev() + * Returns: (transfer full): a %NULL-terminated array of strings. Free + * it using g_strfreev() * Since: 2.14 */ @@ -23049,7 +23691,8 @@ * fail. Any errno value set by remove() will be overwritten by that * set by rmdir(). * - * Returns: 0 if the file was successfully removed, -1 if an error occurred + * Returns: 0 if the file was successfully removed, -1 if an error + * occurred * Since: 2.6 */ @@ -23081,7 +23724,8 @@ * See your C library manual for more details about how rmdir() works * on your system. * - * Returns: 0 if the directory was successfully removed, -1 if an error occurred + * Returns: 0 if the directory was successfully removed, -1 if an error + * occurred * Since: 2.6 */ @@ -23113,7 +23757,7 @@ * necessary to initialise a reader-writer lock that has been statically * allocated. * - * |[ + * |[<!-- language="C" --> * typedef struct { * GRWLock l; * ... @@ -23287,7 +23931,8 @@ * Returns %TRUE if the scanner has reached the end of * the file or text buffer. * - * Returns: %TRUE if the scanner has reached the end of the file or text buffer + * Returns: %TRUE if the scanner has reached the end of + * the file or text buffer */ @@ -23364,7 +24009,8 @@ * If the symbol is not bound in the current scope, %NULL is * returned. * - * Returns: the value of @symbol in the current scope, or %NULL if @symbol is not bound in the current scope + * Returns: the value of @symbol in the current scope, or %NULL + * if @symbol is not bound in the current scope */ @@ -23448,7 +24094,8 @@ * Looks up a symbol in a scope and return its value. If the * symbol is not bound in the scope, %NULL is returned. * - * Returns: the value of @symbol in the given scope, or %NULL if @symbol is not bound in the given scope. + * Returns: the value of @symbol in the given scope, or %NULL + * if @symbol is not bound in the given scope. */ @@ -23498,11 +24145,20 @@ * g_scanner_unexp_token: * @scanner: a #GScanner * @expected_token: the expected token - * @identifier_spec: a string describing how the scanner's user refers to identifiers (%NULL defaults to "identifier"). This is used if @expected_token is %G_TOKEN_IDENTIFIER or %G_TOKEN_IDENTIFIER_NULL. - * @symbol_spec: a string describing how the scanner's user refers to symbols (%NULL defaults to "symbol"). This is used if @expected_token is %G_TOKEN_SYMBOL or any token value greater than %G_TOKEN_LAST. - * @symbol_name: the name of the symbol, if the scanner's current token is a symbol. - * @message: a message string to output at the end of the warning/error, or %NULL. - * @is_error: if %TRUE it is output as an error. If %FALSE it is output as a warning. + * @identifier_spec: a string describing how the scanner's user + * refers to identifiers (%NULL defaults to "identifier"). + * This is used if @expected_token is %G_TOKEN_IDENTIFIER or + * %G_TOKEN_IDENTIFIER_NULL. + * @symbol_spec: a string describing how the scanner's user refers + * to symbols (%NULL defaults to "symbol"). This is used if + * @expected_token is %G_TOKEN_SYMBOL or any token value greater + * than %G_TOKEN_LAST. + * @symbol_name: the name of the symbol, if the scanner's current + * token is a symbol. + * @message: a message string to output at the end of the + * warning/error, or %NULL. + * @is_error: if %TRUE it is output as an error. If %FALSE it is + * output as a warning. * * Outputs a message through the scanner's msg_handler, * resulting from an unexpected token in the input stream. @@ -23568,8 +24224,8 @@ * @seq: a #GSequence * * 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 */ @@ -23611,7 +24267,7 @@ /** * g_sequence_get_iter_at_pos: * @seq: a #GSequence - * @pos: a position in @seq, or -1 for the end. + * @pos: a position in @seq, or -1 for the end * * Returns the iterator at position @pos. If @pos is negative or larger * than the number of items in @seq, the end iterator is returned. @@ -23701,7 +24357,8 @@ * * The @a and @b iterators must point into the same sequence. * - * Returns: A negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b. + * Returns: a negative number if @a comes before @b, 0 if they are + * equal, and a positive number if @a comes after @b * Since: 2.14 */ @@ -23723,7 +24380,7 @@ * * Returns the #GSequence that @iter points into. * - * Returns: the #GSequence that @iter points into. + * Returns: the #GSequence that @iter points into * Since: 2.14 */ @@ -23745,7 +24402,7 @@ * * Returns whether @iter is the end iterator * - * Returns: Whether @iter is the end iterator. + * Returns: Whether @iter is the end iterator * Since: 2.14 */ @@ -23753,14 +24410,15 @@ /** * g_sequence_iter_move: * @iter: a #GSequenceIter - * @delta: A positive or negative number indicating how many positions away from @iter the returned #GSequenceIter will be. + * @delta: A positive or negative number indicating how many positions away + * from @iter the returned #GSequenceIter will be * * Returns the #GSequenceIter which is @delta positions away from @iter. * If @iter is closer than -@delta positions to the beginning of the sequence, * the begin iterator is returned. If @iter is closer than @delta positions * to the end of the sequence, the end iterator is returned. * - * Returns: a #GSequenceIter which is @delta positions away from @iter. + * Returns: a #GSequenceIter which is @delta positions away from @iter * Since: 2.14 */ @@ -23769,10 +24427,10 @@ * g_sequence_iter_next: * @iter: a #GSequenceIter * - * 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. * - * Returns: a #GSequenceIter pointing to the next position after @iter. + * Returns: a #GSequenceIter pointing to the next position after @iter * Since: 2.14 */ @@ -23781,10 +24439,11 @@ * g_sequence_iter_prev: * @iter: a #GSequenceIter * - * 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. * - * Returns: a #GSequenceIter pointing to the previous position before @iter. + * Returns: a #GSequenceIter pointing to the previous position + * before @iter * Since: 2.14 */ @@ -23794,7 +24453,7 @@ * @seq: a #GSequence * @data: data to lookup * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. + * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position of the first item found * equal to @data according to @cmp_func and @cmp_data. If more than one @@ -23807,15 +24466,15 @@ * 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> * - * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. + * Returns: 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 * Since: 2.28 */ @@ -23835,15 +24494,15 @@ * 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> * - * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. + * Returns: 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 * Since: 2.28 */ @@ -23851,7 +24510,8 @@ /** * g_sequence_move: * @src: a #GSequenceIter pointing to the item to move - * @dest: a #GSequenceIter pointing to the position to which the item is moved. + * @dest: a #GSequenceIter pointing to the position to which + * the item is moved * * Moves the item pointed to by @src to the position indicated by @dest. * After calling this function @dest will point to the position immediately @@ -23913,12 +24573,13 @@ * * 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. * - * Returns: A #GSequenceIter pointing somewhere in the (@begin, @end) range. + * Returns: a #GSequenceIter pointing somewhere in the + * (@begin, @end) range * Since: 2.14 */ @@ -23956,7 +24617,7 @@ * @seq: a #GSequence * @data: data for the new item * @cmp_func: the function used to compare items in the sequence - * @cmp_data: user data passed to @cmp_func. + * @cmp_data: user data passed to @cmp_func * * Returns an iterator pointing to the position where @data would * be inserted according to @cmp_func and @cmp_data. @@ -23969,15 +24630,14 @@ * 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> * - * Returns: an #GSequenceIter pointing to the position where @data would have been inserted according to @cmp_func and @cmp_data. + * Returns: an #GSequenceIter pointing to the position where @data + * would have been inserted according to @cmp_func and @cmp_data * Since: 2.14 */ @@ -24000,15 +24660,15 @@ * 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> * - * Returns: a #GSequenceIter pointing to the position in @seq where @data would have been inserted according to @iter_cmp and @cmp_data. + * Returns: a #GSequenceIter pointing to the position in @seq + * where @data would have been inserted according to @iter_cmp + * and @cmp_data * Since: 2.14 */ @@ -24166,9 +24826,10 @@ * g_set_prgname: * @prgname: the name of the program. * - * 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. */ @@ -24218,20 +24879,18 @@ * 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> * * Returns: %FALSE if the environment variable couldn't be set. * Since: 2.4 @@ -24311,12 +24970,12 @@ * * 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. * * Returns: a pointer to the allocated memory block @@ -24330,8 +24989,7 @@ * * 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. * * Returns: a pointer to the allocated block @@ -24360,11 +25018,11 @@ * 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. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -24380,12 +25038,11 @@ * 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 */ @@ -24401,10 +25058,8 @@ * 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 */ @@ -24422,9 +25077,8 @@ * 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 */ @@ -24443,9 +25097,8 @@ * @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 */ @@ -24458,11 +25111,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. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -24477,11 +25129,11 @@ * 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 @@ -24506,27 +25158,23 @@ * * 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)); * ]| @@ -24554,12 +25202,10 @@ * * 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> * * Returns: a copy of @list */ @@ -24581,12 +25227,12 @@ * 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); * ]| * @@ -24604,11 +25250,11 @@ * 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. * * Returns: the new head of @list */ @@ -24622,7 +25268,8 @@ * Finds the element in a #GSList which * contains the given data. * - * Returns: the found #GSList element, or %NULL if it is not found + * Returns: the found #GSList element, + * or %NULL if it is not found */ @@ -24630,7 +25277,8 @@ * g_slist_find_custom: * @list: a #GSList * @data: user data passed to the function - * @func: the function to call for each element. It should return 0 when the desired element is found + * @func: the function to call for each element. + * It should return 0 when the desired element is found * * Finds an element in a #GSList, using a supplied function to * find the desired element. It iterates over the list, calling @@ -24660,11 +25308,9 @@ * 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> */ @@ -24706,7 +25352,8 @@ * Gets the position of the element containing * the given data (starting from 0). * - * Returns: the index of the element containing the data, or -1 if the data is not found + * Returns: the index of the element containing the data, + * or -1 if the data is not found */ @@ -24714,7 +25361,10 @@ * g_slist_insert: * @list: a #GSList * @data: the data for the new element - * @position: the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. + * @position: the position to insert the element. + * If this is negative, or is larger than the number + * of elements in the list, the new element is added on + * to the end of the list. * * Inserts a new element into the list at the given position. * @@ -24738,7 +25388,9 @@ * g_slist_insert_sorted: * @list: a #GSList * @data: the data for the new element - * @func: 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. + * @func: 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. * * Inserts a new element into the list, using the given * comparison function to determine its position. @@ -24751,7 +25403,9 @@ * g_slist_insert_sorted_with_data: * @list: a #GSList * @data: the data for the new element - * @func: 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. + * @func: 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. * @user_data: data to pass to comparison function * * Inserts a new element into the list, using the given @@ -24768,11 +25422,10 @@ * * Gets the last element in a #GSList. * - * <note><para> * This function iterates over the whole list. - * </para></note> * - * Returns: the last element in the #GSList, or %NULL if the #GSList has no elements + * Returns: the last element in the #GSList, + * or %NULL if the #GSList has no elements */ @@ -24782,10 +25435,8 @@ * * Gets the number of elements in a #GSList. * - * <note><para> * This function iterates over the whole list to * count its elements. - * </para></note> * * Returns: the number of elements in the #GSList */ @@ -24808,7 +25459,8 @@ * * Gets the element at the given position in a #GSList. * - * Returns: the element, or %NULL if the position is off the end of the #GSList + * Returns: the element, or %NULL if the position is off + * the end of the #GSList */ @@ -24819,7 +25471,8 @@ * * Gets the data of the element at the given position. * - * Returns: the element's data, or %NULL if the position is off the end of the #GSList + * Returns: the element's data, or %NULL if the position + * is off the end of the #GSList */ @@ -24831,7 +25484,8 @@ * Gets the position of the given element * in the #GSList (starting from 0). * - * Returns: the position of the element in the #GSList, or -1 if the element is not found + * Returns: the position of the element in the #GSList, + * or -1 if the element is not found */ @@ -24842,13 +25496,11 @@ * * 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"); @@ -24895,11 +25547,11 @@ * 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. * * Returns: the new start of the #GSList, without the element */ @@ -24918,7 +25570,11 @@ /** * g_slist_sort: * @list: a #GSList - * @compare_func: the comparison function used to sort the #GSList. This function is passed the data from 2 elements of the #GSList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. + * @compare_func: the comparison function used to sort the #GSList. + * This function is passed the data from 2 elements of the #GSList + * and should return 0 if they are equal, a negative value if the + * first element comes before the second, or a positive value if + * the first element comes after the second. * * Sorts a #GSList using the given comparison function. * @@ -24941,8 +25597,10 @@ /** * g_snprintf: * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the terminating nul character). - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @n: the maximum number of bytes to produce (including the + * terminating nul character). + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed @@ -24963,7 +25621,8 @@ * The format string may contain positional parameters, as specified in * the Single Unix Specification. * - * Returns: the number of bytes which would be produced if the buffer was large enough. + * Returns: the number of bytes which would be produced if the buffer + * was large enough. */ @@ -24994,13 +25653,40 @@ /** * g_source_add_poll: * @source: a #GSource - * @fd: a #GPollFD structure holding information about a file descriptor to watch. + * @fd: a #GPollFD structure holding information about a file + * descriptor to watch. * * Adds a file descriptor to the set of file descriptors polled for * this source. This is usually combined with g_source_new() to add an * 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. + * + * 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. + */ + + +/** + * g_source_add_unix_fd: + * @source: a #GSource + * @fd: the fd to monitor + * @events: an event mask + * + * Monitors @fd for the IO events in @events. + * + * The tag returned by this function can be used to remove or modify the + * monitoring of the fd using g_source_remove_unix_fd() or + * g_source_modify_unix_fd(). + * + * It is not necessary to remove the fd before destroying the source; it + * will be cleaned up automatically. + * + * As the name suggests, this function is not available on Windows. + * + * Returns: an opaque tag + * Since: 2.36 */ @@ -25012,7 +25698,8 @@ * Adds a #GSource to a @context so that it will be executed within * that context. Remove it by calling g_source_destroy(). * - * Returns: the ID (greater than 0) for the source within the #GMainContext. + * Returns: the ID (greater than 0) for the source within the + * #GMainContext. */ @@ -25022,7 +25709,8 @@ * * 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. */ @@ -25050,7 +25738,9 @@ * g_main_current_source(). But calling this function on a source * whose #GMainContext has been destroyed is an error. * - * Returns: (transfer none) (allow-none): the #GMainContext with which the source is associated, or %NULL if the context has not yet been added to a source. + * Returns: (transfer none) (allow-none): the #GMainContext with which the + * source is associated, or %NULL if the context has not + * yet been added to a source. */ @@ -25103,6 +25793,20 @@ /** + * g_source_get_ready_time: + * @source: a #GSource + * + * Gets the "ready time" of @source, as set by + * g_source_set_ready_time(). + * + * Any time before the current monotonic time (including 0) is an + * indication that the source will fire immediately. + * + * Returns: the monotonic ready time, -1 for "never" + */ + + +/** * g_source_get_time: * @source: a #GSource * @@ -25129,34 +25833,34 @@ * 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; * } - * + * * static void * some_widget_do_stuff_later (SomeWidget *self) * { * self->idle_id = g_idle_add (idle_callback, self); * } - * + * * static void * some_widget_finalize (GObject *object) * { * SomeWidget *self = SOME_WIDGET (object); - * + * * if (self->idle_id) * g_source_remove (self->idle_id); - * + * * G_OBJECT_CLASS (parent_class)->finalize (object); * } * ]| @@ -25167,19 +25871,19 @@ * 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) * { * 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 (); - * + * * return FALSE; * } * ]| @@ -25190,14 +25894,34 @@ /** + * g_source_modify_unix_fd: + * @source: a #GSource + * @tag: the tag from g_source_add_unix_fd() + * @new_events: the new event mask to watch + * + * Updates the event mask to watch for the fd identified by @tag. + * + * @tag is the tag returned from g_source_add_unix_fd(). + * + * If you want to remove a fd, don't set its event mask to zero. + * Instead, call g_source_remove_unix_fd(). + * + * As the name suggests, this function is not available on Windows. + * + * Since: 2.36 + */ + + +/** * g_source_new: - * @source_funcs: structure containing functions that implement the sources behavior. + * @source_funcs: structure containing functions that implement + * the sources behavior. * @struct_size: size of the #GSource structure to create. * * 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 @@ -25208,6 +25932,24 @@ /** + * g_source_query_unix_fd: + * @source: a #GSource + * @tag: the tag from g_source_add_unix_fd() + * + * Queries the events reported for the fd corresponding to @tag on + * @source during the last poll. + * + * The return value of this function is only defined when the function + * is called from the check or dispatch functions for @source. + * + * As the name suggests, this function is not available on Windows. + * + * Returns: the conditions reported on the fd + * Since: 2.36 + */ + + +/** * g_source_ref: * @source: a #GSource * @@ -25222,16 +25964,19 @@ * @tag: the ID of the source to remove. * * Removes the source with the given id from the default main context. - * The id of - * a #GSource is given by g_source_get_id(), or will be returned by the - * functions g_source_attach(), g_idle_add(), g_idle_add_full(), - * g_timeout_add(), g_timeout_add_full(), g_child_watch_add(), - * g_child_watch_add_full(), g_io_add_watch(), and g_io_add_watch_full(). + * + * The id of a #GSource is given by g_source_get_id(), or will be + * returned by the functions g_source_attach(), g_idle_add(), + * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), + * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and + * g_io_add_watch_full(). * * See also g_source_destroy(). You must use g_source_destroy() for sources * added to a non-default main context. * - * Returns: %TRUE if the source was found and removed. + * It is a programmer error to attempt to remove a non-existent source. + * + * Returns: For historical reasons, this function always returns %TRUE */ @@ -25263,7 +26008,8 @@ /** * g_source_remove_child_source: * @source: a #GSource - * @child_source: a #GSource previously passed to g_source_add_child_source(). + * @child_source: a #GSource previously passed to + * g_source_add_child_source(). * * Detaches @child_source from @source and destroys it. * @@ -25282,6 +26028,23 @@ /** + * g_source_remove_unix_fd: + * @source: a #GSource + * @tag: the tag from g_source_add_unix_fd() + * + * Reverses the effect of a previous call to g_source_add_unix_fd(). + * + * 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. + * + * As the name suggests, this function is not available on Windows. + * + * Since: 2.36 + */ + + +/** * g_source_set_callback: * @source: the source * @func: a callback function @@ -25304,7 +26067,8 @@ * g_source_set_callback_indirect: * @source: the source * @callback_data: pointer to callback data "object" - * @callback_funcs: functions for reference counting @callback_data and getting the callback and data + * @callback_funcs: functions for reference counting @callback_data + * and getting the callback and data * * Sets the callback function storing the data as a refcounted callback * "object". This is used internally. Note that calling @@ -25387,6 +26151,33 @@ /** + * g_source_set_ready_time: + * @source: a #GSource + * @ready_time: the monotonic time at which the source will be ready, + * 0 for "immediately", -1 for "never" + * + * Sets a #GSource to be dispatched when the given monotonic time is + * reached (or passed). If the monotonic time is in the past (as it + * always will be if @ready_time is 0) then the source will be + * dispatched immediately. + * + * If @ready_time is -1 then the source is never woken up on the basis + * of the passage of time. + * + * Dispatching the source does not reset the ready time. You should do + * so yourself, from the source dispatch function. + * + * Note that if you have a pair of sources where the ready time of one + * suggests that it will be delivered first but the priority for the + * 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. + * + * Since: 2.36 + */ + + +/** * g_source_unref: * @source: a #GSource * @@ -25407,7 +26198,8 @@ * The built-in array of primes ranges from 11 to 13845163 such that * each prime is approximately 1.5-2 times the previous prime. * - * Returns: the smallest prime number from a built-in array of primes which is larger than @num + * Returns: the smallest prime number from a built-in array of primes + * which is larger than @num */ @@ -25428,17 +26220,14 @@ * 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. * * Returns: %TRUE on success, %FALSE if error is set */ @@ -25460,18 +26249,18 @@ * * 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 @@ -25496,21 +26285,19 @@ * 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 @@ -25518,9 +26305,8 @@ * 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 @@ -25529,22 +26315,21 @@ * 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 @@ -25553,42 +26338,40 @@ * 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. @@ -25602,11 +26385,11 @@ * 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. @@ -25614,12 +26397,10 @@ * 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> * * Returns: %TRUE on success, %FALSE if an error was set */ @@ -25635,25 +26416,23 @@ * * 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. @@ -25665,12 +26444,12 @@ * * 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. * - * Returns: %TRUE if child exited successfully, %FALSE otherwise (and @error will be set) + * Returns: %TRUE if child exited successfully, %FALSE otherwise (and + * @error will be set) * Since: 2.34 */ @@ -25701,7 +26480,7 @@ * * The same concerns on Windows apply as for g_spawn_command_line_sync(). * - * Returns: %TRUE on success, %FALSE if error is set. + * Returns: %TRUE on success, %FALSE if error is set */ @@ -25760,7 +26539,7 @@ * passing %NULL for @standard_output and @standard_error. * * If @exit_status is non-%NULL, the platform-specific exit status of - * the child is stored there; see the doucumentation of + * the child is stored there; see the documentation of * g_spawn_check_exit_status() for how to use and interpret this. * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in * @flags. @@ -25772,14 +26551,17 @@ * function for full details on the other parameters and details on * how these functions work on Windows. * - * Returns: %TRUE on success, %FALSE if an error was set. + * Returns: %TRUE on success, %FALSE if an error was set */ /** * g_sprintf: - * @string: A pointer to a memory buffer to contain the resulting string. It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @string: A pointer to a memory buffer to contain the resulting string. It + * is up to the caller to ensure that the allocated buffer is large + * enough to hold the formatted result + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard sprintf() function which supports @@ -25798,31 +26580,32 @@ /** * g_stat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @buf: a pointer to a <structname>stat</structname> struct, which will be filled with the file information + * @buf: a pointer to a stat struct, which will be filled with the file + * information * * 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(). * - * Returns: 0 if the information was successfully retrieved, -1 if an error occurred + * Returns: 0 if the information was successfully retrieved, + * -1 if an error occurred * Since: 2.6 */ @@ -25889,11 +26672,11 @@ * * 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. @@ -25903,16 +26686,91 @@ /** + * g_str_is_ascii: + * @str: a string + * + * Determines if a string is pure ASCII. A string is pure ASCII if it + * contains no bytes with the high bit set. + * + * Returns: %TRUE if @str is ASCII + * Since: 2.40 + */ + + +/** + * g_str_match_string: + * @search_term: the search term from the user + * @potential_hit: the text that may be a hit + * @accept_alternates: %TRUE to accept ASCII alternates + * + * Checks if a search conducted for @search_term should match + * @potential_hit. + * + * This function calls g_str_tokenize_and_fold() on both + * @search_term and @potential_hit. ASCII alternates are never taken + * for @search_term but will be taken for @potential_hit according to + * the value of @accept_alternates. + * + * A hit occurs when each folded token in @search_term is a prefix of a + * folded token from @potential_hit. + * + * Depending on how you're performing the search, it will typically be + * faster to call g_str_tokenize_and_fold() on each string in + * your corpus and build an index on the returned folded tokens, then + * call g_str_tokenize_and_fold() on the search term and + * perform lookups into that index. + * + * As some examples, searching for "fred" would match the potential hit + * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match + * "Frédéric" but not "Frederic" (due to the one-directional nature of + * accent matching). Searching "fo" would match "Foo" and "Bar Foo + * Baz", but not "SFO" (because no word as "fo" as a prefix). + * + * Returns: %TRUE if @potential_hit is a hit + * Since: 2.40 + */ + + +/** + * g_str_tokenize_and_fold: + * @string: a string + * @translit_locale: (allow-none): the language code (like 'de' or + * 'en_GB') from which @string originates + * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a + * return location for ASCII alternates + * + * Tokenises @string and performs folding on each token. + * + * A token is a non-empty sequence of alphanumeric characters in the + * source string, separated by non-alphanumeric characters. An + * "alphanumeric" character for this purpose is one that matches + * g_unichar_isalnum() or g_unichar_ismark(). + * + * Each token is then (Unicode) normalised and case-folded. If + * @ascii_alternates is non-%NULL and some of the returned tokens + * contain non-ASCII characters, ASCII alternatives will be generated. + * + * The number of ASCII alternatives that are generated and the method + * for doing so is unspecified, but @translit_locale (if specified) may + * improve the transliteration if the language of the source string is + * known. + * + * Returns: (transfer full) (array zero-terminated=1): the folded tokens + * Since: 2.40 + */ + + +/** * g_strcanon: * @string: a nul-terminated array of bytes * @valid_chars: bytes permitted in @string * @substitutor: replacement character for disallowed bytes * - * 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", '?')) * ]| * @@ -25922,14 +26780,16 @@ /** * g_strcasecmp: - * @s1: a string. - * @s2: a string to compare with @s1. + * @s1: a string + * @s2: a string to compare with @s1 * * A case-insensitive string comparison, corresponding to the standard * strcasecmp() function on platforms which support it. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. - * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this function is deprecated and how to replace it. + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. + * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this + * function is deprecated and how to replace it. */ @@ -25940,12 +26800,14 @@ * 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(). * - * Returns: @string. + * Returns: @string */ @@ -25957,8 +26819,10 @@ * 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(). * @@ -25975,7 +26839,7 @@ * gracefully by sorting it before non-%NULL strings. * Comparing two %NULL pointers returns 0. * - * Returns: -1, 0 or 1, if @str1 is <, == or > than @str2. + * Returns: an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. * Since: 2.16 */ @@ -25988,7 +26852,8 @@ * * This function does the reverse conversion of g_strescape(). * - * Returns: a newly-allocated copy of @source with all escaped character compressed + * Returns: a newly-allocated copy of @source with all escaped + * character compressed */ @@ -25997,17 +26862,16 @@ * @string1: the first string to add, which must not be %NULL * @...: a %NULL-terminated list of strings to append to the string * - * 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> - * * Returns: a newly-allocated string containing all the string arguments */ @@ -26015,7 +26879,8 @@ /** * g_strdelimit: * @string: the string to convert - * @delimiters: (allow-none): a string containing the current delimiters, or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS + * @delimiters: (allow-none): a string containing the current delimiters, + * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. @@ -26023,7 +26888,7 @@ * 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", '?')) * ]| * @@ -26038,7 +26903,9 @@ * Converts a string to lower case. * * Returns: the string - * Deprecated: 2.2: This function is totally broken for the reasons discussed in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() instead. + * Deprecated: 2.2: This function is totally broken for the reasons discussed + * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() + * instead. */ @@ -26056,7 +26923,8 @@ /** * g_strdup_printf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link> + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @...: the parameters to insert into the format string * * Similar to the standard C sprintf() function but safer, since it @@ -26070,7 +26938,8 @@ /** * g_strdup_vprintf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link> + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @args: the list of parameters to insert into the format string * * Similar to the standard C vsprintf() function but safer, since it @@ -26100,14 +26969,16 @@ /** * g_strerror: - * @errnum: the system error number. See the standard C %errno documentation + * @errnum: the system error number. See the standard C %errno + * documentation * * Returns a string corresponding to the given error code, e.g. * "no such process". You should use this function in preference to * strerror(), because it returns a string in UTF-8 encoding, and since * not all platforms support the strerror() function. * - * Returns: a UTF-8 string describing the error code. If the error code is unknown, it returns "unknown error (<code>)". + * Returns: a UTF-8 string describing the error code. If the error code + * is unknown, it returns "unknown error (<code>)". */ @@ -26125,7 +26996,8 @@ * * g_strcompress() does the reverse conversion. * - * Returns: a newly-allocated copy of @source with certain characters escaped. See above. + * Returns: a newly-allocated copy of @source with certain + * characters escaped. See above. */ @@ -26208,7 +27080,8 @@ * g_string_append_uri_escaped: * @string: a #GString * @unescaped: a string - * @reserved_chars_allowed: a string of reserved characters allowed to be used, or %NULL + * @reserved_chars_allowed: a string of reserved characters allowed + * to be used, or %NULL * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters * * Appends @unescaped to @string, escaped any characters that @@ -26240,7 +27113,9 @@ * * Converts all uppercase ASCII letters to lowercase ASCII letters. * - * Returns: passed-in @string pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match g_ascii_tolower(). + * Returns: passed-in @string pointer, with all the + * uppercase characters converted to lowercase in place, + * with semantics that exactly match g_ascii_tolower(). */ @@ -26250,13 +27125,16 @@ * * Converts all lowercase ASCII letters to uppercase ASCII letters. * - * Returns: passed-in @string pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match g_ascii_toupper(). + * Returns: passed-in @string pointer, with all the + * lowercase characters converted to uppercase in place, + * with semantics that exactly match g_ascii_toupper(). */ /** * g_string_assign: - * @string: the destination #GString. Its current contents are destroyed. + * @string: the destination #GString. Its current contents + * are destroyed. * @rval: the string to copy into @string * * Copies the bytes from a string into a #GString, @@ -26307,7 +27185,8 @@ * by g_string_chunk_insert_const() when looking for * duplicates. * - * Returns: a pointer to the copy of @string within the #GStringChunk + * Returns: a pointer to the copy of @string within + * the #GStringChunk */ @@ -26330,7 +27209,8 @@ * pointer to a string added with g_string_chunk_insert(), even * if they do match. * - * Returns: a pointer to the new or existing copy of @string within the #GStringChunk + * Returns: a pointer to the new or existing copy of @string + * within the #GStringChunk */ @@ -26338,7 +27218,8 @@ * g_string_chunk_insert_len: * @chunk: a #GStringChunk * @string: bytes to insert - * @len: number of bytes of @string to insert, or -1 to insert a nul-terminated string + * @len: number of bytes of @string to insert, or -1 to insert a + * nul-terminated string * * Adds a copy of the first @len bytes of @string to the #GStringChunk. * The copy is nul-terminated. @@ -26357,7 +27238,10 @@ /** * g_string_chunk_new: - * @size: the default size of the blocks of memory which are allocated to store the strings. If a particular string is larger than this default size, a larger block of memory will be allocated for it. + * @size: the default size of the blocks of memory which are + * allocated to store the strings. If a particular string + * is larger than this default size, a larger block of + * memory will be allocated for it. * * Creates a new #GStringChunk. * @@ -26372,7 +27256,9 @@ * Converts a #GString to lowercase. * * Returns: the #GString - * Deprecated: 2.2: This function uses the locale-specific tolower() function, which is almost never the right thing. Use g_string_ascii_down() or g_utf8_strdown() instead. + * Deprecated: 2.2: This function uses the locale-specific + * tolower() function, which is almost never the right thing. + * Use g_string_ascii_down() or g_utf8_strdown() instead. */ @@ -26384,7 +27270,8 @@ * Compares two strings for equality, returning %TRUE if they are equal. * For use with #GHashTable. * - * Returns: %TRUE if they strings are the same length and contain the same bytes + * Returns: %TRUE if the strings are the same length and contain the + * same bytes */ @@ -26392,7 +27279,8 @@ * g_string_erase: * @string: a #GString * @pos: the position of the content to remove - * @len: the number of bytes to remove, or -1 to remove all following bytes + * @len: the number of bytes to remove, or -1 to remove all + * following bytes * * Removes @len bytes from a #GString, starting at position @pos. * The rest of the #GString is shifted down to fill the gap. @@ -26411,7 +27299,8 @@ * it's %FALSE, the caller gains ownership of the buffer and must * free it after use with g_free(). * - * Returns: the character data of @string (i.e. %NULL if @free_segment is %TRUE) + * Returns: the character data of @string + * (i.e. %NULL if @free_segment is %TRUE) */ @@ -26471,7 +27360,8 @@ /** * g_string_insert_len: * @string: a #GString - * @pos: position in @string where insertion should happen, or -1 for at the end + * @pos: position in @string where insertion should + * happen, or -1 for at the end * @val: bytes to insert * @len: number of bytes of @val to insert * @@ -26491,7 +27381,8 @@ /** * g_string_insert_unichar: * @string: a #GString - * @pos: the position at which to insert character, or -1 to append at the end of the string + * @pos: the position at which to insert character, or -1 + * to append at the end of the string * @wc: a Unicode character * * Converts a Unicode character into UTF-8, and insert it @@ -26641,7 +27532,8 @@ /** * g_string_sized_new: - * @dfl_size: the default size of the space allocated to hold the string + * @dfl_size: the default size of the space allocated to + * hold the string * * Creates a new #GString, with enough space for @dfl_size * bytes. This is useful if you are going to add a lot of @@ -26700,7 +27592,9 @@ * Converts a #GString to uppercase. * * Returns: @string - * Deprecated: 2.2: This function uses the locale-specific toupper() function, which is almost never the right thing. Use g_string_ascii_up() or g_utf8_strup() instead. + * Deprecated: 2.2: This function uses the locale-specific + * toupper() function, which is almost never the right thing. + * Use g_string_ascii_up() or g_utf8_strup() instead. */ @@ -26725,34 +27619,40 @@ * * An auxiliary function for gettext() support (see Q_()). * - * Returns: @msgval, unless @msgval is identical to @msgid and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned. + * Returns: @msgval, unless @msgval is identical to @msgid + * and contains a '|' character, in which case a pointer to + * the substring of msgid after the first '|' character is returned. * Since: 2.4 */ /** * g_strjoin: - * @separator: (allow-none): a string to insert between each of the strings, or %NULL + * @separator: (allow-none): a string to insert between each of the + * strings, or %NULL * @...: a %NULL-terminated list of strings to join * * Joins a number of strings together to form one long string, with the * optional @separator inserted between each of them. The returned string * should be freed with g_free(). * - * Returns: a newly-allocated string containing all of the strings joined together, with @separator between them + * Returns: a newly-allocated string containing all of the strings joined + * together, with @separator between them */ /** * g_strjoinv: - * @separator: (allow-none): a string to insert between each of the strings, or %NULL + * @separator: (allow-none): a string to insert between each of the + * strings, or %NULL * @str_array: a %NULL-terminated array of strings to join * * Joins a number of strings together to form one long string, with the * optional @separator inserted between each of them. The returned string * should be freed with g_free(). * - * Returns: a newly-allocated string containing all of the strings joined together, with @separator between them + * Returns: a newly-allocated string containing all of the strings joined + * together, with @separator between them */ @@ -26760,24 +27660,26 @@ * g_strlcat: * @dest: destination buffer, already containing one nul-terminated string * @src: source buffer - * @dest_size: length of @dest buffer in bytes (not length of existing string inside @dest) + * @dest_size: length of @dest buffer in bytes (not length of existing string + * inside @dest) * * Portability wrapper that calls strlcat() on systems which have it, * 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. * - * Returns: size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size, truncation occurred. + * Returns: size of attempted result, which is MIN (dest_size, strlen + * (original dest)) + strlen (src), so if retval >= dest_size, + * truncation occurred. */ @@ -26790,17 +27692,17 @@ * 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. * * Returns: length of @src */ @@ -26808,17 +27710,31 @@ /** * g_strncasecmp: - * @s1: a string. - * @s2: a string to compare with @s1. - * @n: the maximum number of characters to compare. + * @s1: a string + * @s2: a string to compare with @s1 + * @n: the maximum number of characters to compare * * 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. + * strncasecmp() function on platforms which support it. It is similar + * to g_strcasecmp() except it only compares the first @n characters of + * the strings. + * + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. + * 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. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. - * 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. There are therefore two replacement functions: g_ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8. + * 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. */ @@ -26828,17 +27744,16 @@ * @n: the maximum number of bytes to copy from @str * * 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. * - * Returns: a newly-allocated buffer containing the first @n bytes of @str, nul-terminated + * Returns: a newly-allocated buffer containing the first @n bytes + * of @str, nul-terminated */ @@ -26859,8 +27774,7 @@ * @string: the string to reverse * * 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 @@ -26878,7 +27792,8 @@ * Searches the string @haystack for the last occurrence * of the string @needle. * - * Returns: a pointer to the found occurrence, or %NULL if not found. + * Returns: a pointer to the found occurrence, or + * %NULL if not found. */ @@ -26892,28 +27807,33 @@ * of the string @needle, limiting the length of the search * to @haystack_len. * - * Returns: a pointer to the found occurrence, or %NULL if not found. + * Returns: a pointer to the found occurrence, or + * %NULL if not found. */ /** * g_strsignal: - * @signum: the signal number. See the <literal>signal</literal> documentation + * @signum: the signal number. See the `signal` documentation * * Returns a string describing the given signal, e.g. "Segmentation fault". * You should use this function in preference to strsignal(), because it * returns a string in UTF-8 encoding, and since not all platforms support * the strsignal() function. * - * Returns: a UTF-8 string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)". + * Returns: a UTF-8 string describing the signal. If the signal is unknown, + * it returns "unknown signal (<signum>)". */ /** * g_strsplit: * @string: a string to split - * @delimiter: a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless @max_tokens is reached. - * @max_tokens: the maximum number of pieces to split @string into. If this is less than 1, the string is split completely. + * @delimiter: a string which specifies the places at which to split + * the string. The delimiter is not included in any of the resulting + * strings, unless @max_tokens is reached. + * @max_tokens: the maximum number of pieces to split @string into. + * If this is less than 1, the string is split completely. * * Splits a string into a maximum of @max_tokens pieces, using the given * @delimiter. If @max_tokens is reached, the remainder of @string is @@ -26926,15 +27846,18 @@ * to represent empty elements, you'll need to check for the empty string * before calling g_strsplit(). * - * Returns: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: a newly-allocated %NULL-terminated array of strings. Use + * g_strfreev() to free it. */ /** * g_strsplit_set: * @string: The string to be tokenized - * @delimiters: A nul-terminated string containing bytes that are used to split the string. - * @max_tokens: The maximum number of tokens to split @string into. If this is less than 1, the string is split completely + * @delimiters: A nul-terminated string containing bytes that are used + * to split the string. + * @max_tokens: The maximum number of tokens to split @string into. + * If this is less than 1, the string is split completely * * Splits @string into a number of tokens not containing any of the characters * in @delimiter. A token is the (possibly empty) longest string that does not @@ -26958,7 +27881,8 @@ * Note that this function works on bytes not characters, so it can't be used * to delimit UTF-8 strings for anything but ASCII characters. * - * Returns: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: a newly-allocated %NULL-terminated array of strings. Use + * g_strfreev() to free it. * Since: 2.4 */ @@ -26966,14 +27890,17 @@ /** * g_strstr_len: * @haystack: a string - * @haystack_len: the maximum length of @haystack. Note that -1 is a valid length, if @haystack is nul-terminated, meaning it will search through the whole string. + * @haystack_len: the maximum length of @haystack. Note that -1 is + * a valid length, if @haystack is nul-terminated, meaning it will + * search through the whole string. * @needle: the string to search for * * Searches the string @haystack for the first occurrence * of the string @needle, limiting the length of the search * to @haystack_len. * - * Returns: a pointer to the found occurrence, or %NULL if not found. + * Returns: a pointer to the found occurrence, or + * %NULL if not found. */ @@ -26991,7 +27918,8 @@ /** * g_strtod: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * * Converts a string to a #gdouble value. * It calls the standard strtod() function to handle the conversion, but @@ -27011,12 +27939,14 @@ /** * g_strup: - * @string: the string to convert. + * @string: the string to convert * * Converts a string to upper case. * * Returns: the string - * 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. */ @@ -27064,6 +27994,10 @@ * slash-separated portions of @testpath. The @test_data argument * 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 `-p` command-line option or g_test_trap_subprocess(). + * * Since: 2.16 */ @@ -27092,6 +28026,10 @@ * created on the fly and added to the root fixture, based on the * 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 `-p` command-line option or g_test_trap_subprocess(). + * * Since: 2.16 */ @@ -27102,6 +28040,9 @@ * Asserts that all messages previously indicated via * g_test_expect_message() have been seen and suppressed. * + * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly + * expected via g_test_expect_message() then they will be ignored. + * * Since: 2.34 */ @@ -27140,6 +28081,40 @@ /** + * g_test_build_filename: + * @file_type: the type of file (built vs. distributed) + * @first_path: the first segment of the pathname + * @...: %NULL-terminated additional path segments + * + * Creates the pathname to a data file that is required for a test. + * + * This function is conceptually similar to g_build_filename() except + * that the first argument has been replaced with a #GTestFileType + * argument. + * + * The data file should either have been distributed with the module + * containing the test (%G_TEST_DIST) or built as part of the build + * 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 glib.mk + * included in GLib. Please ensure that your copy is up to date before + * using this function. + * + * In case neither variable is set, this function will fall back to + * using the dirname portion of argv[0], possibly removing ".libs". + * This allows for casual running of tests directly from the commandline + * in the srcdir == builddir case and should also support running of + * installed tests, assuming the data files have been installed in the + * same relative path as the test binary. + * + * Returns: the path of the file, to be freed using g_free() + * Since: 2.38 + */ + + +/** * g_test_create_case: * @test_name: the name for the test case * @data_size: the size of the fixture data structure @@ -27181,9 +28156,9 @@ /** * g_test_expect_message: - * @log_domain: the log domain of the message + * @log_domain: (allow-none): the log domain of the message * @log_level: the log level of the message - * @pattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Indicates that a message with the given @log_domain and @log_level, * with text matching @pattern, is expected to be logged. When this @@ -27199,20 +28174,22 @@ * * 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_CRITICIAL, - * "assertion.*acquired_context.*failed"); + * G_LOG_LEVEL_CRITICAL, + * "assertion*acquired_context*failed"); * g_main_context_push_thread_default (bad_context); * g_test_assert_expected_messages (); * ]| * * Note that you cannot use this to test g_error() messages, since * g_error() intentionally never returns even if the program doesn't - * abort; use g_test_trap_fork() in this case. + * abort; use g_test_trap_subprocess() in this case. + * + * If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly + * expected via g_test_expect_message() then they will be ignored. * * Since: 2.34 */ @@ -27240,6 +28217,64 @@ /** + * g_test_failed: + * + * Returns whether a test has already failed. This will + * be the case when g_test_fail(), g_test_incomplete() + * or g_test_skip() have been called, but also if an + * assertion has failed. + * + * This can be useful to return early from a test if + * continuing after a failed assertion might be harmful. + * + * The return value of this function is only meaningful + * if it is called from inside a test function. + * + * Returns: %TRUE if the test has failed + * Since: 2.38 + */ + + +/** + * g_test_get_dir: + * @file_type: the type of file (built vs. distributed) + * + * Gets the pathname of the directory containing test files of the type + * specified by @file_type. + * + * This is approximately the same as calling g_test_build_filename("."), + * but you don't need to free the return value. + * + * Returns: the path of the directory, owned by GLib + * Since: 2.38 + */ + + +/** + * g_test_get_filename: + * @file_type: the type of file (built vs. distributed) + * @first_path: the first segment of the pathname + * @...: %NULL-terminated additional path segments + * + * Gets the pathname to a data file that is required for a test. + * + * This is the same as g_test_build_filename() with two differences. + * The first difference is that must only use this function from within + * a testcase function. The second difference is that you need not free + * the return value -- it will be automatically freed when the testcase + * finishes running. + * + * It is safe to use this function from a thread inside of a testcase + * but you must ensure that all such uses occur before the main testcase + * function returns (ie: it is best to ensure that all threads have been + * joined). + * + * Returns: the path, automatically freed at the end of the testcase + * Since: 2.38 + */ + + +/** * g_test_get_root: * * Get the toplevel test suite for the test path API. @@ -27250,94 +28285,79 @@ /** + * g_test_incomplete: + * @msg: (allow-none): explanation + * + * Indicates that a test failed because of some incomplete + * functionality. This function can be called multiple times + * from the same test. + * + * Calling this function will not stop the test from running, you + * need to return from the test function yourself. So you can + * produce additional diagnostic messages or even continue running + * the test. + * + * If not called from inside a test, this function does nothing. + * + * Since: 2.38 + */ + + +/** * g_test_init: - * @argc: Address of the @argc parameter of the main() function. Changed if any arguments were handled. - * @argv: Address of the @argv parameter of main(). Any parameters understood by g_test_init() stripped before return. - * @...: Reserved for future extension. Currently, you must pass %NULL. + * @argc: Address of the @argc parameter of the main() function. + * Changed if any arguments were handled. + * @argv: Address of the @argv parameter of main(). + * Any parameters understood by g_test_init() stripped before return. + * @...: %NULL-terminated list of special options. Currently the only + * defined option is `"no_g_set_prgname"`, which + * will cause g_test_init() to not call g_set_prgname(). * * 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>. - * </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 - * under g_test_trap_fork() 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> + * + * - `-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"). + * - `-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 + * + * `no-undefined`: Avoid tests for undefined behaviour + * + * - `--debug-log`: Debug test logging output. * * Since: 2.16 */ /** + * g_test_initialized: + * + * Returns %TRUE if g_test_init() has been called. + * + * Returns: %TRUE if g_test_init() has been called. + * Since: 2.36 + */ + + +/** * g_test_log_buffer_free: * * Internal function for gtester to free test log messages, no ABI guarantees provided. @@ -27580,13 +28600,37 @@ * * 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. - * - * Returns: 0 on success + * 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 `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 + * run in that order (since g_test_run() would run the first "/foo" + * suite, then the "/bar" suite, then the second "/foo" suite). As of + * 2.36, this bug is fixed, and adding the tests in that order would + * result in a running order of "/foo/simple", "/foo/using-bar", + * "/bar/simple". If this new ordering is sub-optimal (because it puts + * more-complicated tests before simpler ones, making it harder to + * figure out exactly what has failed), you can fix it by changing the + * test paths to group tests by suite in a way that will result in the + * desired running order. Eg, "/simple/foo", "/simple/bar", + * "/complex/foo-using-bar". + * + * However, you should never make the actual result of a test depend + * 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. + * + * Returns: 0 on success, 1 on failure (assuming it returns at all), + * 0 or 77 if all tests were skipped with g_test_skip() * Since: 2.16 */ @@ -27597,8 +28641,10 @@ * * 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(). + * 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. * @@ -27608,6 +28654,44 @@ /** + * g_test_set_nonfatal_assertions: + * + * Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), + * g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), + * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), + * g_assert_error(), g_test_assert_expected_messages() and the various + * g_test_trap_assert_*() macros to not abort to program, but instead + * call g_test_fail() and continue. (This also changes the behavior of + * g_test_fail() so that it will not cause the test program to abort + * after completing the failed test.) + * + * Note that the g_assert_not_reached() and g_assert() are not + * affected by this. + * + * This function can only be called after g_test_init(). + * + * Since: 2.38 + */ + + +/** + * g_test_skip: + * @msg: (allow-none): explanation + * + * Indicates that a test was skipped. + * + * Calling this function will not stop the test from running, you + * need to return from the test function yourself. So you can + * produce additional diagnostic messages or even continue running + * the test. + * + * If not called from inside a test, this function does nothing. + * + * Since: 2.38 + */ + + +/** * g_test_slow: * * Returns %TRUE if tests are run in slow mode. @@ -27619,6 +28703,18 @@ /** + * g_test_subprocess: + * + * Returns %TRUE (after g_test_init() has been called) if the test + * program is running under g_test_trap_subprocess(). + * + * Returns: %TRUE if the test program is running under + * g_test_trap_subprocess(). + * Since: 2.38 + */ + + +/** * g_test_suite_add: * @suite: a #GTestSuite * @test_case: a #GTestCase @@ -27683,13 +28779,13 @@ /** * g_test_trap_assert_failed: * - * Assert that the last forked test failed. - * See g_test_trap_fork(). + * Assert that the last test subprocess failed. + * See g_test_trap_subprocess(). * * This is sometimes used to test situations that are formally considered to * be undefined behaviour, like inputs that fail a g_return_if_fail() * check. In these situations you should skip the entire test, including the - * call to g_test_trap_fork(), unless g_test_undefined() returns %TRUE + * call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE * to indicate that undefined behaviour may be tested. * * Since: 2.16 @@ -27699,8 +28795,8 @@ /** * g_test_trap_assert_passed: * - * Assert that the last forked test passed. - * See g_test_trap_fork(). + * Assert that the last test subprocess passed. + * See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27708,16 +28804,17 @@ /** * g_test_trap_assert_stderr: - * @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * - * Assert that the stderr output of the last forked test - * matches @serrpattern. See g_test_trap_fork(). + * Assert that the stderr output of the last test subprocess + * matches @serrpattern. See g_test_trap_subprocess(). * - * This is sometimes used to test situations that are formally considered to - * be undefined behaviour, like inputs that fail a g_return_if_fail() - * check. In these situations you should skip the entire test, including the - * call to g_test_trap_fork(), unless g_test_undefined() returns %TRUE - * to indicate that undefined behaviour may be tested. + * This is sometimes used to test situations that are formally + * considered to be undefined behaviour, like code that hits a + * g_assert() or g_error(). In these situations you should skip the + * entire test, including the call to g_test_trap_subprocess(), unless + * g_test_undefined() returns %TRUE to indicate that undefined + * behaviour may be tested. * * Since: 2.16 */ @@ -27725,10 +28822,10 @@ /** * g_test_trap_assert_stderr_unmatched: - * @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * - * Assert that the stderr output of the last forked test - * does not match @serrpattern. See g_test_trap_fork(). + * Assert that the stderr output of the last test subprocess + * does not match @serrpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27736,10 +28833,10 @@ /** * g_test_trap_assert_stdout: - * @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * - * Assert that the stdout output of the last forked test matches - * @soutpattern. See g_test_trap_fork(). + * Assert that the stdout output of the last test subprocess matches + * @soutpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27747,10 +28844,10 @@ /** * g_test_trap_assert_stdout_unmatched: - * @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * - * Assert that the stdout output of the last forked test - * does not match @soutpattern. See g_test_trap_fork(). + * Assert that the stdout output of the last test subprocess + * does not match @soutpattern. See g_test_trap_subprocess(). * * Since: 2.16 */ @@ -27762,8 +28859,10 @@ * @test_trap_flags: Flags to modify forking behaviour. * * Fork the current test program to execute a test case that might - * not return or that might abort. The forked test case is aborted - * and considered failing if its run time exceeds @usec_timeout. + * not return or that might abort. + * + * If @usec_timeout is non-0, the forked test case is aborted and + * considered failing if its run time exceeds it. * * The forking behavior can be configured with the #GTestTrapFlags flags. * @@ -27772,7 +28871,7 @@ * The forking parent process then asserts successful child program * termination and validates child program outputs. * - * |[ + * |[<!-- language="C" --> * static void * test_fork_patterns (void) * { @@ -27780,27 +28879,28 @@ * { * 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_passed (); * g_test_trap_assert_stdout ("*somagic17*"); * g_test_trap_assert_stderr ("*semagic43*"); * } * ]| * - * This function is implemented only on Unix platforms. - * * Returns: %TRUE for the forked child and %FALSE for the executing parent process. * Since: 2.16 + * Deprecated: This function is implemented only on Unix platforms, + * and is not always reliable due to problems inherent in + * fork-without-exec. Use g_test_trap_subprocess() instead. */ /** * g_test_trap_has_passed: * - * Check the result of the last g_test_trap_fork() call. + * Check the result of the last g_test_trap_subprocess() call. * - * Returns: %TRUE if the last forked child terminated successfully. + * Returns: %TRUE if the last test subprocess terminated successfully. * Since: 2.16 */ @@ -27808,20 +28908,91 @@ /** * g_test_trap_reached_timeout: * - * Check the result of the last g_test_trap_fork() call. + * Check the result of the last g_test_trap_subprocess() call. * - * Returns: %TRUE if the last forked child got killed due to a fork timeout. + * Returns: %TRUE if the last test subprocess got killed due to a timeout. * Since: 2.16 */ /** + * g_test_trap_subprocess: + * @test_path: (allow-none): Test to run in a subprocess + * @usec_timeout: Timeout for the subprocess test in micro seconds. + * @test_flags: Flags to modify subprocess behaviour. + * + * Respawns the test program to run only @test_path in a subprocess. + * This can be used for a test case that might not return, or that + * might abort. + * + * 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 + * "`/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. + * + * The subprocess behavior can be configured with the + * #GTestSubprocessFlags flags. + * + * You can use methods such as g_test_trap_assert_passed(), + * g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to + * check the results of the subprocess. (But note that + * 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 `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 + * `my_object_new(1000000)` will abort with an error + * message. + * + * |[<!-- language="C" --> + * static void + * test_create_large_object_subprocess (void) + * { + * if (g_test_subprocess ()) + * { + * my_object_new (1000000); + * return; + * } + * + * // 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*"); + * } + * + * int + * main (int argc, char **argv) + * { + * g_test_init (&argc, &argv, NULL); + * + * g_test_add_func ("/myobject/create_large_object", + * test_create_large_object); + * return g_test_run (); + * } + * ]| + * + * Since: 2.38 + */ + + +/** * g_test_undefined: * * Returns %TRUE if tests may provoke assertions and other formally-undefined - * behaviour under g_test_trap_fork(), to verify that appropriate warnings - * are given. It can be useful to turn this off if running tests under - * valgrind. + * behaviour, to verify that appropriate warnings are given. It might, in some + * cases, be useful to turn this off if running tests under valgrind. * * Returns: %TRUE if tests may provoke programming errors */ @@ -27847,15 +29018,13 @@ * 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 - * this function from a thread created with another threading library - * or or from within a #GThreadPool. - * </para></note> + * 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 + * this function from a thread created with another threading library + * or or from within a #GThreadPool. */ @@ -27886,7 +29055,7 @@ /** * g_thread_new: - * @name: a name for the new thread + * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @@ -27897,6 +29066,7 @@ * with g_thread_join(). * * The @name can be useful for discriminating threads in a debugger. + * It is not used for other purposes and does not have to be unique. * Some systems restrict the length of @name to 16 bytes. * * If the thread can not be created the program aborts. See @@ -27943,7 +29113,9 @@ * If this function returns 0, threads waiting in the thread * pool for new work are not stopped. * - * Returns: the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread + * Returns: the maximum @interval (milliseconds) to wait + * for new tasks in the thread pool before stopping the + * thread * Since: 2.10 */ @@ -27989,8 +29161,10 @@ /** * g_thread_pool_new: * @func: a function to execute in the threads of the new thread pool - * @user_data: user data that is handed over to @func every time it is called - * @max_threads: the maximal number of threads to execute concurrently in the new thread pool, -1 means no limit + * @user_data: user data that is handed over to @func every time it + * is called + * @max_threads: the maximal number of threads to execute concurrently + * in the new thread pool, -1 means no limit * @exclusive: should this thread pool be exclusive? * @error: return location for error, or %NULL * @@ -28048,7 +29222,8 @@ /** * g_thread_pool_set_max_idle_time: - * @interval: the maximum @interval (in milliseconds) a thread can be idle + * @interval: the maximum @interval (in milliseconds) + * a thread can be idle * * This function will set the maximum @interval that a thread * waiting in the pool for new tasks can be idle for before @@ -28067,7 +29242,8 @@ /** * g_thread_pool_set_max_threads: * @pool: a #GThreadPool - * @max_threads: a new maximal number of threads for @pool, or -1 for unlimited + * @max_threads: a new maximal number of threads for @pool, + * or -1 for unlimited * @error: return location for error, or %NULL * * Sets the maximal allowed number of threads for @pool. @@ -28110,7 +29286,12 @@ /** * g_thread_pool_set_sort_function: * @pool: a #GThreadPool - * @func: the #GCompareDataFunc used to sort the list of tasks. This function is passed two tasks. It should return 0 if the order in which they are handled does not matter, a negative value if the first task should be processed before the second or a positive value if the second task should be processed first. + * @func: the #GCompareDataFunc used to sort the list of tasks. + * This function is passed two tasks. It should return + * 0 if the order in which they are handled does not matter, + * a negative value if the first task should be processed before + * the second or a positive value if the second task should be + * processed first. * @user_data: user data passed to @func * * Sets the function used to sort the list of tasks. This allows the @@ -28189,7 +29370,7 @@ /** * g_thread_try_new: - * @name: a name for the new thread + * @name: (allow-none): an (optional) name for the new thread * @func: a function to execute in the new thread * @data: an argument to supply to the new thread * @error: return location for error, or %NULL @@ -28274,11 +29455,11 @@ * "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. @@ -28375,7 +29556,8 @@ * arrive at local time for @tz (ie: negative numbers for time zones * west of GMT, positive numbers for east). * - * Returns: the number of seconds that should be added to UTC to get the local time in @tz + * Returns: the number of seconds that should be added to UTC to get the + * local time in @tz * Since: 2.26 */ @@ -28400,32 +29582,63 @@ * 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). - * - * 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>. - * - * The <varname>TZ</varname> environment variable typically corresponds - * to the name of a file in the zoneinfo database, but there are many - * other possibilities. Note that those other possibilities are not - * currently implemented, but are planned. + * 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 `"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 `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. + * + * In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also + * accepts POSIX format. The Windows format uses US rules for all time + * zones; daylight savings time is 60 minutes behind the standard time + * with date and time of change taken from Pacific Standard Time. + * 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 timezone. - * - * 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. + * `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 + * [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. @@ -28442,9 +29655,8 @@ * 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. @@ -28493,7 +29705,8 @@ /** * g_timeout_add: - * @interval: the time between calls to the function, in milliseconds (1/1000ths of a second) + * @interval: the time between calls to the function, in milliseconds + * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * @@ -28526,9 +29739,11 @@ /** - * g_timeout_add_full: - * @priority: the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. - * @interval: the time between calls to the function, in milliseconds (1/1000ths of a second) + * g_timeout_add_full: (rename-to g_timeout_add) + * @priority: the priority of the timeout source. Typically this will be in + * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * @interval: the time between calls to the function, in milliseconds + * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the timeout is removed, or %NULL @@ -28554,7 +29769,6 @@ * See g_get_monotonic_time(). * * Returns: the ID (greater than 0) of the event source. - * Rename to: g_timeout_add */ @@ -28587,8 +29801,9 @@ /** - * g_timeout_add_seconds_full: - * @priority: the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) + * @priority: the priority of the timeout source. Typically this will be in + * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @interval: the time between calls to the function, in seconds * @function: function to call * @data: data to pass to @function @@ -28629,7 +29844,6 @@ * time. See g_get_monotonic_time(). * * Returns: the ID (greater than 0) of the event source. - * Rename to: g_timeout_add_seconds * Since: 2.14 */ @@ -28695,7 +29909,9 @@ /** * g_timer_elapsed: * @timer: a #GTimer. - * @microseconds: return location for the fractional part of seconds elapsed, in microseconds (that is, the total number of microseconds elapsed, modulo 1000000), or %NULL + * @microseconds: return location for the fractional part of seconds + * elapsed, in microseconds (that is, the total number + * of microseconds elapsed, modulo 1000000), or %NULL * * If @timer has been started but not stopped, obtains the time since * the timer was started. If @timer has been stopped, obtains the @@ -28704,7 +29920,8 @@ * including any fractional part. The @microseconds out parameter is * essentially useless. * - * Returns: seconds elapsed as a floating point value, including any fractional part. + * Returns: seconds elapsed as a floating point value, including any + * fractional part. */ @@ -28793,12 +30010,12 @@ /** * g_tree_destroy: - * @tree: a #GTree. + * @tree: a #GTree * * 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. */ @@ -28806,9 +30023,10 @@ /** * g_tree_foreach: - * @tree: a #GTree. - * @func: the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. - * @user_data: user data to pass to the function. + * @tree: a #GTree + * @func: the function to call for each node visited. + * If this function returns %TRUE, the traversal is stopped. + * @user_data: user data to pass to the function * * Calls the given function for each of the key/value pairs in the #GTree. * The function is passed the key and value of each pair, and the given @@ -28823,7 +30041,7 @@ /** * g_tree_height: - * @tree: a #GTree. + * @tree: a #GTree * * Gets the height of a #GTree. * @@ -28831,21 +30049,23 @@ * If the #GTree contains only one root node the height is 1. * If the root node has children the height is 2, etc. * - * Returns: the height of the #GTree. + * Returns: the height of @tree */ /** * g_tree_insert: - * @tree: a #GTree. - * @key: the key to insert. - * @value: the value corresponding to the key. + * @tree: a #GTree + * @key: the key to insert + * @value: the value corresponding to the key * - * 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. @@ -28854,96 +30074,106 @@ /** * g_tree_lookup: - * @tree: a #GTree. - * @key: the key to look up. + * @tree: a #GTree + * @key: the key to look up * * 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). * - * Returns: the value corresponding to the key, or %NULL if the key was not found. + * Returns: the value corresponding to the key, or %NULL + * if the key was not found */ /** * g_tree_lookup_extended: - * @tree: a #GTree. - * @lookup_key: the key to look up. - * @orig_key: returns the original key. - * @value: returns the value associated with the key. + * @tree: a #GTree + * @lookup_key: the key to look up + * @orig_key: returns the original key + * @value: returns the value associated with the key * * 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(). * - * Returns: %TRUE if the key was found in the #GTree. + * Returns: %TRUE if the key was found in the #GTree */ /** * g_tree_new: - * @key_compare_func: the function used to order the nodes in the #GTree. It should return values similar to the standard strcmp() function - 0 if the two arguments are equal, a negative value if the first argument comes before the second, or a positive value if the first argument comes after the second. + * @key_compare_func: the function used to order the nodes in the #GTree. + * It should return values similar to the standard strcmp() function - + * 0 if the two arguments are equal, a negative value if the first argument + * comes before the second, or a positive value if the first argument comes + * after the second. * * Creates a new #GTree. * - * Returns: a new #GTree. + * Returns: a newly allocated #GTree */ /** * g_tree_new_full: - * @key_compare_func: qsort()-style comparison function. - * @key_compare_data: data to pass to comparison function. - * @key_destroy_func: 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. - * @value_destroy_func: 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. + * @key_compare_func: qsort()-style comparison function + * @key_compare_data: data to pass to comparison function + * @key_destroy_func: 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 + * @value_destroy_func: 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 * * Creates a new #GTree like g_tree_new() and allows to specify functions * to free the memory allocated for the key and value that get called when * removing the entry from the #GTree. * - * Returns: a new #GTree. + * Returns: a newly allocated #GTree */ /** * g_tree_new_with_data: - * @key_compare_func: qsort()-style comparison function. - * @key_compare_data: data to pass to comparison function. + * @key_compare_func: qsort()-style comparison function + * @key_compare_data: data to pass to comparison function * * Creates a new #GTree with a comparison function that accepts user data. * See g_tree_new() for more details. * - * Returns: a new #GTree. + * Returns: a newly allocated #GTree */ /** * g_tree_nnodes: - * @tree: a #GTree. + * @tree: a #GTree * * Gets the number of nodes in a #GTree. * - * Returns: the number of nodes in the #GTree. + * Returns: the number of nodes in @tree */ /** * g_tree_ref: - * @tree: a #GTree. + * @tree: a #GTree * - * 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. * - * Returns: the passed in #GTree. + * Returns: the passed in #GTree * Since: 2.22 */ /** * g_tree_remove: - * @tree: a #GTree. - * @key: the key to remove. + * @tree: a #GTree + * @key: the key to remove * * Removes a key/value pair from a #GTree. * @@ -28952,15 +30182,16 @@ * make sure that any dynamically allocated values are freed yourself. * If the key does not exist in the #GTree, the function does nothing. * - * Returns: %TRUE if the key was found (prior to 2.8, this function returned nothing) + * Returns: %TRUE if the key was found (prior to 2.8, this function + * returned nothing) */ /** * g_tree_replace: - * @tree: a #GTree. - * @key: the key to insert. - * @value: the value corresponding to the key. + * @tree: a #GTree + * @key: the key to insert + * @value: the value corresponding to the key * * 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 @@ -28990,45 +30221,52 @@ * @search_func returns 1, searching will proceed among the key/value * pairs that have a larger key. * - * Returns: the value corresponding to the found key, or %NULL if the key was not found. + * Returns: the value corresponding to the found key, or %NULL + * if the key was not found */ /** * g_tree_steal: - * @tree: a #GTree. - * @key: the key to remove. + * @tree: a #GTree + * @key: the key to remove * * Removes a key and its associated value from a #GTree without calling * the key and value destroy functions. * * If the key does not exist in the #GTree, the function does nothing. * - * Returns: %TRUE if the key was found (prior to 2.8, this function returned nothing) + * Returns: %TRUE if the key was found (prior to 2.8, this function + * returned nothing) */ /** * g_tree_traverse: - * @tree: a #GTree. - * @traverse_func: the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. - * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, %G_PRE_ORDER and %G_POST_ORDER. - * @user_data: user data to pass to the function. + * @tree: a #GTree + * @traverse_func: the function to call for each node visited. If this + * function returns %TRUE, the traversal is stopped. + * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, + * %G_PRE_ORDER and %G_POST_ORDER + * @user_data: user data to pass to the function * * 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]. */ /** * g_tree_unref: - * @tree: a #GTree. + * @tree: a #GTree * - * 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. * @@ -29115,30 +30353,48 @@ /** * g_ucs4_to_utf16: * @str: a UCS-4 encoded string - * @len: the maximum length (number of characters) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of bytes read, or %NULL. If an error occurs then the index of the invalid input is stored here. - * @items_written: (allow-none): location to store number of <type>gunichar2</type> written, or %NULL. The value stored here does not include the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of characters) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of bytes read, + * or %NULL. If an error occurs then the index of the invalid input + * is stored here. + * @items_written: (allow-none): location to store number of #gunichar2 + * written, or %NULL. The value stored here does not include the + * trailing 0. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UCS-4 to UTF-16. A 0 character will be * added to the result after the converted text. * - * Returns: 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. + * Returns: 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. */ /** * g_ucs4_to_utf8: * @str: a UCS-4 encoded string - * @len: the maximum length (number of characters) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of characters read, or %NULL. - * @items_written: (allow-none): location to store number of bytes written or %NULL. The value here stored does not include the trailing 0 byte. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of characters) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of characters + * read, or %NULL. + * @items_written: (allow-none): location to store number of bytes + * written or %NULL. The value here stored does not include the + * trailing 0 byte. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from a 32-bit fixed width representation as UCS-4. * to UTF-8. The result will be terminated with a 0 byte. * - * Returns: 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. + * Returns: 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. */ @@ -29187,7 +30443,8 @@ * * 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. * * Returns: %TRUE if the characters could be composed @@ -29221,7 +30478,8 @@ * 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. * * Returns: %TRUE if the character could be decomposed @@ -29236,7 +30494,8 @@ * Determines the numeric value of a character as a decimal * digit. * - * Returns: If @c is a decimal digit (according to g_unichar_isdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a decimal digit (according to + * g_unichar_isdigit()), its numeric value. Otherwise, -1. */ @@ -29263,7 +30522,8 @@ * 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. * * Returns: the length of the full decomposition. @@ -29276,10 +30536,10 @@ * @ch: a Unicode character * @mirrored_ch: location to store the mirrored character * - * 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 @@ -29496,9 +30756,9 @@ * 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 @@ -29541,7 +30801,9 @@ /** * g_unichar_to_utf8: * @c: a Unicode character code - * @outbuf: output buffer, must have at least 6 bytes of space. If %NULL, the length will be computed and returned and nothing will be written to @outbuf. + * @outbuf: output buffer, must have at least 6 bytes of space. + * If %NULL, the length will be computed and returned + * and nothing will be written to @outbuf. * * Converts a single character to UTF-8. * @@ -29555,7 +30817,9 @@ * * Converts a character to lower case. * - * Returns: the result of converting @c to lower case. If @c is not an upperlower or titlecase character, or has no lowercase equivalent @c is returned unchanged. + * Returns: the result of converting @c to lower case. + * If @c is not an upperlower or titlecase character, + * or has no lowercase equivalent @c is returned unchanged. */ @@ -29565,7 +30829,9 @@ * * Converts a character to the titlecase. * - * Returns: the result of converting @c to titlecase. If @c is not an uppercase or lowercase character, @c is returned unchanged. + * Returns: the result of converting @c to titlecase. + * If @c is not an uppercase or lowercase character, + * @c is returned unchanged. */ @@ -29575,7 +30841,9 @@ * * Converts a character to uppercase. * - * Returns: the result of converting @c to uppercase. If @c is not an lowercase or titlecase character, or has no upper case equivalent @c is returned unchanged. + * Returns: the result of converting @c to uppercase. + * If @c is not an lowercase or titlecase character, + * or has no upper case equivalent @c is returned unchanged. */ @@ -29608,7 +30876,8 @@ * Determines the numeric value of a character as a hexidecimal * digit. * - * Returns: If @c is a hex digit (according to g_unichar_isxdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a hex digit (according to + * g_unichar_isxdigit()), its numeric value. Otherwise, -1. */ @@ -29619,8 +30888,10 @@ * * Computes the canonical decomposition of a Unicode character. * - * Returns: a newly allocated string of Unicode characters. @result_len is set to the resulting length of the string. - * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose() instead. + * Returns: a newly allocated string of Unicode characters. + * @result_len is set to the resulting length of the string. + * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose() + * instead. */ @@ -29646,10 +30917,13 @@ * 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. * - * Returns: the Unicode script for @iso15924, or of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. + * Returns: the Unicode script for @iso15924, or + * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and + * %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. * Since: 2.30 */ @@ -29664,30 +30938,93 @@ * 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. * - * Returns: the ISO 15924 code for @script, encoded as an integer, of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. + * Returns: the ISO 15924 code for @script, encoded as an integer, + * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or + * ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. * Since: 2.30 */ /** + * g_unix_fd_add: + * @fd: a file descriptor + * @condition: IO conditions to watch for on @fd + * @function: a #GPollFDFunc + * @user_data: data to pass to @function + * + * Sets a function to be called when the IO condition, as specified by + * @condition becomes true for @fd. + * + * @function will be called when the specified IO condition becomes + * %TRUE. The function is expected to clear whatever event caused the + * IO condition to become true and return %TRUE in order to be notified + * when it happens again. If @function returns %FALSE then the watch + * will be cancelled. + * + * The return value of this function can be passed to g_source_remove() + * to cancel the watch at any time that it exists. + * + * The source will never close the fd -- you must do it yourself. + * + * Returns: the ID (greater than 0) of the event source + * Since: 2.36 + */ + + +/** + * g_unix_fd_add_full: + * @priority: the priority of the source + * @fd: a file descriptor + * @condition: IO conditions to watch for on @fd + * @function: a #GUnixFDSourceFunc + * @user_data: data to pass to @function + * @notify: function to call when the idle is removed, or %NULL + * + * Sets a function to be called when the IO condition, as specified by + * @condition becomes true for @fd. + * + * This is the same as g_unix_fd_add(), except that it allows you to + * specify a non-default priority and a provide a #GDestroyNotify for + * @user_data. + * + * Returns: the ID (greater than 0) of the event source + * Since: 2.36 + */ + + +/** + * g_unix_fd_source_new: + * @fd: a file descriptor + * @condition: IO conditions to watch for on @fd + * + * Creates a #GSource to watch for a particular IO condition on a file + * descriptor. + * + * The source will never close the fd -- you must do it yourself. + * + * Returns: the newly created #GSource + * Since: 2.36 + */ + + +/** * g_unix_open_pipe: * @fds: Array of two integers - * @flags: Bitfield of file descriptor flags, see "man 2 fcntl" + * @flags: Bitfield of file descriptor flags, as for fcntl() * @error: a #GError * * 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. * * Returns: %TRUE on success, %FALSE if not (and errno will be set). * Since: 2.30 @@ -29701,8 +31038,8 @@ * @error: a #GError * * 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. * * Returns: %TRUE if successful * Since: 2.30 @@ -29725,8 +31062,9 @@ /** - * g_unix_signal_add_full: - * @priority: the priority of the signal source. Typically this will be in the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * g_unix_signal_add_full: (rename-to g_unix_signal_add) + * @priority: the priority of the signal source. Typically this will be in + * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @signum: Signal number * @handler: Callback * @user_data: Data for @handler @@ -29746,13 +31084,15 @@ * @signum: A signal number * * Create a #GSource that will be dispatched upon delivery of the UNIX - * signal @signum. Currently only <literal>SIGHUP</literal>, - * <literal>SIGINT</literal>, and <literal>SIGTERM</literal> can - * be monitored. 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(). + * signal @signum. In GLib versions before 2.36, only `SIGHUP`, `SIGINT`, + * `SIGTERM` can be monitored. In GLib 2.36, `SIGUSR1` and `SIGUSR2` + * were added. * - * For example, an effective use of this function is to handle <literal>SIGTERM</literal> + * 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 `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 @@ -29785,7 +31125,8 @@ * that on Windows, it is in general not possible to delete files that * are open to some process, or mapped into memory. * - * Returns: 0 if the name was successfully deleted, -1 if an error occurred + * Returns: 0 if the name was successfully deleted, -1 if an error + * occurred * Since: 2.6 */ @@ -29799,20 +31140,18 @@ * 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 */ @@ -29821,7 +31160,8 @@ /** * g_uri_escape_string: * @unescaped: the unescaped input string. - * @reserved_chars_allowed: a string of reserved characters that are allowed to be used, or %NULL. + * @reserved_chars_allowed: (allow-none): a string of reserved characters that + * are allowed to be used, or %NULL. * @allow_utf8: %TRUE if the result can include UTF-8 characters. * * Escapes a string for use in a URI. @@ -29833,7 +31173,8 @@ * specification, since those are allowed unescaped in some portions of * a URI. * - * Returns: an escaped version of @unescaped. The returned string should be freed when no longer needed. + * Returns: an escaped version of @unescaped. The returned string should be + * freed when no longer needed. * Since: 2.16 */ @@ -29846,7 +31187,9 @@ * mime type defined in RFC 2483 into individual URIs, * discarding any comments. The URIs are not validated. * - * Returns: (transfer full): a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev(). + * Returns: (transfer full): a newly allocated %NULL-terminated list + * of strings holding the individual URIs. The array should be freed + * with g_strfreev(). * Since: 2.6 */ @@ -29856,12 +31199,13 @@ * @uri: a valid URI. * * 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. * - * Returns: The "Scheme" component of the URI, or %NULL on error. The returned string should be freed when no longer needed. + * Returns: The "Scheme" component of the URI, or %NULL on error. + * The returned string should be freed when no longer needed. * Since: 2.16 */ @@ -29880,7 +31224,10 @@ * slash being expanded in an escaped path element, which might confuse pathname * handling. * - * Returns: an unescaped version of @escaped_string or %NULL on error. The returned string should be freed when no longer needed. As a special case if %NULL is given for @escaped_string, this function will return %NULL. + * Returns: an unescaped version of @escaped_string or %NULL on error. + * The returned string should be freed when no longer needed. As a + * special case if %NULL is given for @escaped_string, this function + * will return %NULL. * Since: 2.16 */ @@ -29888,7 +31235,8 @@ /** * g_uri_unescape_string: * @escaped_string: an escaped string to be unescaped. - * @illegal_characters: an optional string of illegal characters not to be allowed. + * @illegal_characters: (allow-none): a string of illegal characters not to be + * allowed, or %NULL. * * Unescapes a whole escaped string. * @@ -29898,7 +31246,8 @@ * slash being expanded in an escaped path element, which might confuse pathname * handling. * - * Returns: an unescaped version of @escaped_string. The returned string should be freed when no longer needed. + * Returns: an unescaped version of @escaped_string. The returned string + * should be freed when no longer needed. * Since: 2.16 */ @@ -29919,25 +31268,42 @@ /** * g_utf16_to_ucs4: * @str: a UTF-16 encoded string - * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): 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. - * @items_written: (allow-none): location to store number of characters written, or %NULL. The value stored here does not include the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of #gunichar2) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): 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. + * @items_written: (allow-none): location to store number of characters + * written, or %NULL. The value stored here does not include the trailing + * 0 character. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UCS-4. The result will be * nul-terminated. * - * Returns: 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. + * Returns: 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. */ /** * g_utf16_to_utf8: * @str: a UTF-16 encoded string - * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): 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. - * @items_written: (allow-none): location to store number of bytes written, or %NULL. The value stored here does not include the trailing 0 byte. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of #gunichar2) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): 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. + * @items_written: (allow-none): location to store number of bytes written, + * or %NULL. The value stored here does not include the trailing 0 byte. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UTF-8. The result will be * terminated with a 0 byte. @@ -29953,7 +31319,9 @@ * be correctly interpreted as UTF-16, i.e. it doesn't contain * things unpaired surrogates. * - * Returns: 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. + * Returns: 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. */ @@ -29974,7 +31342,8 @@ * takes case sensitivity into account. GLib does not currently * provide such a function. * - * Returns: a newly allocated string, that is a case independent form of @str. + * Returns: a newly allocated string, that is a + * case independent form of @str. */ @@ -29984,13 +31353,14 @@ * @str2: a UTF-8 encoded string * * 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 * the original strings. * - * Returns: < 0 if @str1 compares before @str2, 0 if they compare equal, > 0 if @str1 compares after @str2. + * Returns: < 0 if @str1 compares before @str2, + * 0 if they compare equal, > 0 if @str1 compares after @str2. */ @@ -30007,10 +31377,10 @@ * 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]. * - * Returns: a newly allocated string. This string should be freed with g_free() when you are done with it. + * Returns: a newly allocated string. This string should + * be freed with g_free() when you are done with it. */ @@ -30029,10 +31399,10 @@ * 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]. * - * Returns: a newly allocated string. This string should be freed with g_free() when you are done with it. + * Returns: a newly allocated string. This string should + * be freed with g_free() when you are done with it. * Since: 2.8 */ @@ -30040,7 +31410,8 @@ /** * g_utf8_find_next_char: * @p: a pointer to a position within a UTF-8 encoded string - * @end: a pointer to the byte following the end of the string, or %NULL to indicate that the string is nul-terminated. + * @end: a pointer to the byte following the end of the string, + * or %NULL to indicate that the string is nul-terminated * * Finds the start of the next UTF-8 character in the string after @p. * @@ -30074,8 +31445,9 @@ * @p: a pointer to Unicode character encoded as UTF-8 * * 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. * @@ -30086,14 +31458,19 @@ /** * g_utf8_get_char_validated: * @p: a pointer to Unicode character encoded as UTF-8 - * @max_len: the maximum number of bytes to read, or -1, for no maximum or if @p is nul-terminated + * @max_len: the maximum number of bytes to read, or -1, for no maximum or + * if @p is nul-terminated * * Convert a sequence of bytes encoded as UTF-8 to a Unicode character. * This function checks for incomplete characters, for invalid characters * such as characters that are out of the range of Unicode, and for * overlong encodings of valid characters. * - * Returns: the resulting character. If @p points to a partial sequence at the end of a string that could begin a valid character (or if @max_len is zero), returns (gunichar)-2; otherwise, if @p does not point to a valid UTF-8 encoded Unicode character, returns (gunichar)-1. + * Returns: the resulting character. If @p points to a partial + * sequence at the end of a string that could begin a valid + * character (or if @max_len is zero), returns (gunichar)-2; + * otherwise, if @p does not point to a valid UTF-8 encoded + * Unicode character, returns (gunichar)-1. */ @@ -30129,7 +31506,9 @@ * a legacy encoding or pass it to a system with * less capable Unicode handling. * - * Returns: a newly allocated string, that is the normalized form of @str, or %NULL if @str is not valid UTF-8. + * Returns: a newly allocated string, that is the + * normalized form of @str, or %NULL if @str is not + * valid UTF-8. */ @@ -30146,14 +31525,11 @@ * 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> * * Returns: the resulting pointer */ @@ -30185,7 +31561,7 @@ * it starts with an appropriate byte. If @p might be the first * character of the string, you must use g_utf8_find_prev_char() instead. * - * Returns: a pointer to the found character. + * Returns: a pointer to the found character */ @@ -30199,7 +31575,9 @@ * in a UTF-8 encoded string, while limiting the search to @len bytes. * If @len is -1, allow unbounded search. * - * Returns: %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. + * Returns: %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. */ @@ -30213,14 +31591,19 @@ * on the current locale, and may result in the number of * characters in the string changing. * - * Returns: a newly allocated string, with all characters converted to lowercase. + * Returns: a newly allocated string, with all characters + * converted to lowercase. */ /** * g_utf8_strlen: * @p: pointer to the start of a UTF-8 encoded string - * @max: the maximum number of bytes to examine. If @max is less than 0, then the string is assumed to be nul-terminated. If @max is 0, @p will not be examined and may be %NULL. If @max is greater than 0, up to @max bytes are examined + * @max: the maximum number of bytes to examine. If @max + * is less than 0, then the string is assumed to be + * nul-terminated. If @max is 0, @p will not be examined and + * may be %NULL. If @max is greater than 0, up to @max + * bytes are examined * * Computes the length of the string in characters, not including * the terminating nul character. If the @max'th byte falls in the @@ -30236,11 +31619,10 @@ * @src: UTF-8 encoded string * @n: character count * - * 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.) * * Returns: @dest */ @@ -30256,14 +31638,17 @@ * in a UTF-8 encoded string, while limiting the search to @len bytes. * If @len is -1, allow unbounded search. * - * Returns: %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. + * Returns: %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. */ /** * g_utf8_strreverse: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, then the string is nul-terminated. + * @len: the maximum length of @str to use, in bytes. If @len < 0, + * then the string is nul-terminated. * * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. * (Use g_utf8_validate() on all text before trying to use UTF-8 @@ -30279,7 +31664,7 @@ * newly-allocated memory, which should be freed with g_free() when * no longer needed. * - * Returns: a newly-allocated string which is the reverse of @str. + * Returns: a newly-allocated string which is the reverse of @str * Since: 2.2 */ @@ -30295,7 +31680,8 @@ * characters in the string increasing. (For instance, the * German ess-zet will be changed to SS.) * - * Returns: a newly allocated string, with all characters converted to uppercase. + * Returns: a newly allocated string, with all characters + * converted to uppercase. */ @@ -30306,10 +31692,10 @@ * @end_pos: another character offset within @str * * 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. * - * Returns: a newly allocated copy of the requested substring. Free with g_free() when no longer needed. + * Returns: a newly allocated copy of the requested + * substring. Free with g_free() when no longer needed. * Since: 2.30 */ @@ -30317,24 +31703,37 @@ /** * g_utf8_to_ucs4: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): 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. - * @items_written: (allow-none): location to store number of characters written or %NULL. The value here stored does not include the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length of @str to use, in bytes. If @len < 0, + * then the string is nul-terminated. + * @items_read: (allow-none): 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. + * @items_written: (allow-none): location to store number of characters + * written or %NULL. The value here stored does not include the + * trailing 0 character. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4. A trailing 0 character will be added to the * string after the converted text. * - * Returns: 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. + * Returns: 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. */ /** * g_utf8_to_ucs4_fast: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, then the string is nul-terminated. - * @items_written: (allow-none): location to store the number of characters in the result, or %NULL. + * @len: the maximum length of @str to use, in bytes. If @len < 0, + * then the string is nul-terminated. + * @items_written: (allow-none): location to store the number of + * characters in the result, or %NULL. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4, assuming valid UTF-8 input. @@ -30342,22 +31741,33 @@ * but does no error checking on the input. A trailing 0 character * will be added to the string after the converted text. * - * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free(). + * Returns: a pointer to a newly allocated UCS-4 string. + * This value must be freed with g_free(). */ /** * g_utf8_to_utf16: * @str: a UTF-8 encoded string - * @len: the maximum length (number of bytes) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): 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. - * @items_written: (allow-none): location to store number of <type>gunichar2</type> written, or %NULL. The value stored here does not include the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of bytes) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): 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. + * @items_written: (allow-none): location to store number of #gunichar2 + * written, or %NULL. The value stored here does not include the + * trailing 0. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to UTF-16. A 0 character will be * added to the result after the converted text. * - * Returns: 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. + * Returns: 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. */ @@ -30376,12 +31786,12 @@ * 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. * * Returns %TRUE if all of @str was valid. Many GLib and GTK+ - * routines <emphasis>require</emphasis> valid UTF-8 as input; - * so data read from a file or the network should be checked - * with g_utf8_validate() before doing anything else with it. + * routines require valid UTF-8 as input; so data read from a file + * or the network should be checked with g_utf8_validate() before + * doing anything else with it. * * Returns: %TRUE if the text was valid UTF-8 */ @@ -30404,7 +31814,7 @@ /** - * g_variant_builder_add: (skp) + * g_variant_builder_add: (skip) * @builder: a #GVariantBuilder * @format_string: a #GVariant varargs format string * @...: arguments, as per @format_string @@ -30414,27 +31824,31 @@ * 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: * - * <programlisting> + * |[<!-- language="C" --> * GVariant * * make_pointless_dictionary (void) * { - * GVariantBuilder *builder; + * GVariantBuilder builder; * int i; * - * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY); + * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); * for (i = 0; i < 16; i++) * { * gchar buf[3]; * * sprintf (buf, "%d", i); - * g_variant_builder_add (builder, "{is}", i, buf); + * g_variant_builder_add (&builder, "{is}", i, buf); * } * - * return g_variant_builder_end (builder); + * return g_variant_builder_end (&builder); * } - * </programlisting> + * ]| * * Since: 2.24 */ @@ -30452,22 +31866,26 @@ * 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: * - * <programlisting> + * |[<!-- language="C" --> * GVariant * * make_pointless_dictionary (void) * { - * GVariantBuilder *builder; + * GVariantBuilder builder; * int i; * - * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY); - * g_variant_builder_add_parsed (builder, "{'width', <%i>}", 600); - * g_variant_builder_add_parsed (builder, "{'title', <%s>}", "foo"); - * g_variant_builder_add_parsed (builder, "{'transparency', <0.5>}"); - * return g_variant_builder_end (builder); + * g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + * g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); + * g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); + * g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); + * return g_variant_builder_end (&builder); * } - * </programlisting> + * ]| * * Since: 2.26 */ @@ -30742,22 +32160,243 @@ * If you only require an equality comparison, g_variant_equal() is more * general. * - * Returns: negative value if a < b; zero if a = b; positive value if a > b. + * Returns: negative value if a < b; + * zero if a = b; + * positive value if a > b. * Since: 2.26 */ /** + * g_variant_dict_clear: + * @dict: a #GVariantDict + * + * 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 + */ + + +/** + * g_variant_dict_contains: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * + * Checks if @key exists in @dict. + * + * Returns: %TRUE if @key is in @dict + * Since: 2.40 + */ + + +/** + * g_variant_dict_end: + * @dict: a #GVariantDict + * + * 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). + * + * Returns: (transfer none): a new, floating, #GVariant + * Since: 2.40 + */ + + +/** + * g_variant_dict_init: (skip) + * @dict: a #GVariantDict + * @from_asv: (allow-none): the initial value for @dict + * + * 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 + */ + + +/** + * g_variant_dict_insert: + * @dict: a #GVariantDict + * @key: the key to insert a value for + * @format_string: a #GVariant varargs format string + * @...: arguments, as per @format_string + * + * 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 + */ + + +/** + * g_variant_dict_insert_value: + * @dict: a #GVariantDict + * @key: the key to insert a value for + * @value: the value to insert + * + * Inserts (or replaces) a key in a #GVariantDict. + * + * @value is consumed if it is floating. + * + * Since: 2.40 + */ + + +/** + * g_variant_dict_lookup: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * @format_string: a GVariant format string + * @...: the arguments to unpack the value into + * + * 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]. + * + * Returns: %TRUE if a value was unpacked + * Since: 2.40 + */ + + +/** + * g_variant_dict_lookup_value: + * @dict: a #GVariantDict + * @key: the key to lookup in the dictionary + * @expected_type: (allow-none): a #GVariantType, or %NULL + * + * 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. + * + * Returns: (transfer full): the value of the dictionary key, or %NULL + * Since: 2.40 + */ + + +/** + * g_variant_dict_new: + * @from_asv: (allow-none): the #GVariant with which to initialise the + * dictionary + * + * 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. + * + * Returns: (transfer full): a #GVariantDict + * Since: 2.40 + */ + + +/** + * g_variant_dict_ref: + * @dict: a heap-allocated #GVariantDict + * + * Increases the reference count on @dict. + * + * Don't call this on stack-allocated #GVariantDict instances or bad + * things will happen. + * + * Returns: (transfer full): a new reference to @dict + * Since: 2.40 + */ + + +/** + * g_variant_dict_remove: + * @dict: a #GVariantDict + * @key: the key to remove + * + * Removes a key and its associated value from a #GVariantDict. + * + * Returns: %TRUE if the key was found and removed + * Since: 2.40 + */ + + +/** + * g_variant_dict_unref: + * @dict: (transfer full): a heap-allocated #GVariantDict + * + * 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 + */ + + +/** * g_variant_dup_bytestring: * @value: an array-of-bytes #GVariant instance - * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store the length (not including the nul terminator) + * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store + * the length (not including the nul terminator) * * Similar to g_variant_get_bytestring() except that instead of * returning a constant string, the string is duplicated. * * The return value must be freed using g_free(). * - * Returns: (transfer full) (array length=length zero-terminated=1) (element-type guint8): a newly allocated string + * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): + * a newly allocated string * Since: 2.26 */ @@ -30870,15 +32509,15 @@ * 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 */ @@ -30932,7 +32571,8 @@ * * The return value remains valid as long as @value exists. * - * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): the constant string + * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): + * the constant string * Since: 2.26 */ @@ -30973,7 +32613,7 @@ * @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 */ @@ -31038,6 +32678,20 @@ /** + * g_variant_get_data_as_bytes: + * @value: a #GVariant + * + * Returns a pointer to the serialised form of a #GVariant instance. + * The semantics of this function are exactly the same as + * g_variant_get_data(), except that the returned #GBytes holds + * a reference to the variant data. + * + * Returns: (transfer full): A new #GBytes representing the variant data + * Since: 2.36 + */ + + +/** * g_variant_get_double: * @value: a double #GVariant instance * @@ -31065,37 +32719,27 @@ * * @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. * - * Returns: (array length=n_elements) (transfer none): a pointer to the fixed array + * Returns: (array length=n_elements) (transfer none): a pointer to + * the fixed array * Since: 2.24 */ @@ -31243,7 +32887,8 @@ /** * g_variant_get_string: * @value: a string #GVariant instance - * @length: (allow-none) (default 0) (out): a pointer to a #gsize, to store the length + * @length: (allow-none) (default 0) (out): a pointer to a #gsize, + * to store the length * * Returns the string value of a #GVariant instance with a string * type. This includes the types %G_VARIANT_TYPE_STRING, @@ -31359,7 +33004,8 @@ * g_variant_get_va: (skip) * @value: a #GVariant * @format_string: a string that is prefixed with a format string - * @endptr: (allow-none) (default NULL): location to store the end pointer, or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on #GVariant @@ -31385,7 +33031,7 @@ * @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 */ @@ -31597,13 +33243,9 @@ * 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) * { @@ -31617,12 +33259,11 @@ * 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(). * @@ -31636,11 +33277,13 @@ * 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]. * - * Returns: %TRUE if a value was unpacked, or %FALSE if there was no value + * Returns: %TRUE if a value was unpacked, or %FALSE if there was no + * value * Since: 2.24 */ @@ -31694,13 +33337,9 @@ * 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) * { @@ -31714,21 +33353,21 @@ * 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]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value * Since: 2.24 @@ -31745,10 +33384,9 @@ * 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) * { @@ -31766,8 +33404,7 @@ * g_variant_unref (child); * } * } - * </programlisting> - * </example> + * ]| * * Returns: (allow-none) (transfer full): a #GVariant, or %NULL * Since: 2.24 @@ -31791,7 +33428,10 @@ * @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. * * Returns: %TRUE if a value was unpacked * Since: 2.28 @@ -31806,26 +33446,26 @@ * * 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. + * * Returns: (transfer full): the value of the dictionary key, or %NULL * Since: 2.28 */ @@ -31861,16 +33501,31 @@ * * 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); + * ]| + * * Returns: a new floating #GVariant instance * Since: 2.24 */ @@ -31879,7 +33534,8 @@ /** * g_variant_new_array: * @child_type: (allow-none): the element type of the new array - * @children: (allow-none) (array length=n_children): an array of #GVariant pointers, the children + * @children: (allow-none) (array length=n_children): an array of + * #GVariant pointers, the children * @n_children: the length of @children * * Creates a new #GVariant array from @children. @@ -31927,7 +33583,8 @@ /** * g_variant_new_bytestring: - * @string: (array zero-terminated=1) (element-type guint8): a normal nul-terminated string in no particular encoding + * @string: (array zero-terminated=1) (element-type guint8): a normal + * nul-terminated string in no particular encoding * * Creates an array-of-bytes #GVariant with the contents of @string. * This function is just like g_variant_new_string() except that the @@ -31996,11 +33653,11 @@ * @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. @@ -32011,6 +33668,23 @@ /** + * g_variant_new_from_bytes: + * @type: a #GVariantType + * @bytes: a #GBytes + * @trusted: if the contents of @bytes are trusted + * + * Constructs a new serialised-mode #GVariant instance. This is the + * inner interface for creation of new serialised values that gets + * called from various functions in gvariant.c. + * + * A reference is taken on @bytes. + * + * Returns: (transfer none): a new #GVariant with a floating reference + * Since: 2.36 + */ + + +/** * g_variant_new_from_data: * @type: a definite #GVariantType * @data: (array length=size) (element-type guint8): the serialised data @@ -32162,15 +33836,21 @@ * 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 @@ -32201,6 +33881,10 @@ * #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. @@ -32213,6 +33897,23 @@ /** + * g_variant_new_printf: (skip) + * @format_string: a printf-style format string + * @...: arguments for @format_string + * + * Creates a string-type GVariant using printf formatting. + * + * This is similar to calling g_strdup_printf() and then + * g_variant_new_string() but it saves a temporary variable and an + * unnecessary copy. + * + * Returns: (transfer none): a floating reference to a new string + * #GVariant instance + * Since: 2.38 + */ + + +/** * g_variant_new_signature: * @signature: a normal C nul-terminated string * @@ -32254,6 +33955,27 @@ /** + * g_variant_new_take_string: (skip) + * @string: a normal utf8 nul-terminated string + * + * Creates a string #GVariant with the contents of @string. + * + * @string must be valid utf8. + * + * This function consumes @string. g_free() will be called on @string + * when it is no longer required. + * + * You must not modify or access @string in any other way after passing + * it to this function. It is even possible that @string is immediately + * freed. + * + * Returns: (transfer none): a floating reference to a new string + * #GVariant instance + * Since: 2.38 + */ + + +/** * g_variant_new_tuple: * @children: (array length=n_children): the items to make the tuple out of * @n_children: the length of @children @@ -32308,7 +34030,8 @@ /** * g_variant_new_va: (skip) * @format_string: a string that is prefixed with a format string - * @endptr: (allow-none) (default NULL): location to store the end pointer, or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on @@ -32327,6 +34050,10 @@ * @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. @@ -32376,7 +34103,7 @@ * * 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 @@ -32408,13 +34135,61 @@ /** + * g_variant_parse_error_print_context: + * @error: a #GError from the #GVariantParseError domain + * @source_str: the string that was given to the parser + * + * Pretty-prints a message showing the context of a #GVariant parse + * error within the string for which parsing was attempted. + * + * The resulting string is suitable for output to the console or other + * monospace media where newlines are treated in the usual way. + * + * The message will typically look something like one of the following: + * + * |[ + * unterminated string constant: + * (1, 2, 3, 'abc + * ^^^^ + * ]| + * + * or + * + * |[ + * unable to find a common type: + * [1, 2, 3, 'str'] + * ^ ^^^^^ + * ]| + * + * The format of the message may change in a future version. + * + * @error must have come from a failed attempt to g_variant_parse() and + * @source_str must be exactly the same string that caused the error. + * If @source_str was not nul-terminated when you passed it to + * g_variant_parse() then you must add nul termination before using this + * function. + * + * Returns: (transfer full): the printed message + * Since: 2.40 + */ + + +/** + * g_variant_parser_get_error_quark: + * + * Deprecated: Use g_variant_parse_error_quark() instead. + */ + + +/** * g_variant_print: * @value: a #GVariant - * @type_annotate: %TRUE if type information should be included in the output + * @type_annotate: %TRUE if type information should be included in + * the output * * 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. @@ -32428,7 +34203,8 @@ * g_variant_print_string: (skip) * @value: a #GVariant * @string: (allow-none) (default NULL): a #GString, or %NULL - * @type_annotate: %TRUE if type information should be included in the output + * @type_annotate: %TRUE if type information should be included in + * the output * * Behaves as g_variant_print(), but operates on a #GString. * @@ -32456,7 +34232,7 @@ * @value: a #GVariant * * #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 @@ -32553,7 +34329,9 @@ * Makes a copy of a #GVariantType. It is appropriate to call * g_variant_type_free() on the return value. @type may not be %NULL. * - * Returns: (transfer full): a new #GVariantType Since 2.24 + * Returns: (transfer full): a new #GVariantType + * + * Since 2.24 */ @@ -32565,7 +34343,9 @@ * @type. The returned string is nul-terminated. It is appropriate to * call g_free() on the return value. * - * Returns: (transfer full): the corresponding type string Since 2.24 + * Returns: (transfer full): the corresponding type string + * + * Since 2.24 */ @@ -32577,7 +34357,9 @@ * * This function may only be used with array or maybe types. * - * Returns: (transfer none): the element type of @type Since 2.24 + * Returns: (transfer none): the element type of @type + * + * Since 2.24 */ @@ -32597,7 +34379,9 @@ * allow use with #GHashTable without function pointer casting. For * both arguments, a valid #GVariantType must be provided. * - * Returns: %TRUE if @type1 and @type2 are exactly equal Since 2.24 + * Returns: %TRUE if @type1 and @type2 are exactly equal + * + * Since 2.24 */ @@ -32620,7 +34404,9 @@ * This call, together with g_variant_type_next() provides an iterator * interface over tuple and dictionary entry types. * - * Returns: (transfer none): the first item type of @type, or %NULL Since 2.24 + * Returns: (transfer none): the first item type of @type, or %NULL + * + * Since 2.24 */ @@ -32646,7 +34432,9 @@ * @type. This function must be used to determine the valid extent of * the memory region returned by g_variant_type_peek_string(). * - * Returns: the length of the corresponding type string Since 2.24 + * Returns: the length of the corresponding type string + * + * Since 2.24 */ @@ -32660,7 +34448,9 @@ * #GHashTable without function pointer casting. A valid * #GVariantType must be provided. * - * Returns: the hash value Since 2.24 + * Returns: the hash value + * + * Since 2.24 */ @@ -32675,7 +34465,9 @@ * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for * example. * - * Returns: %TRUE if @type is an array type Since 2.24 + * Returns: %TRUE if @type is an array type + * + * Since 2.24 */ @@ -32693,7 +34485,9 @@ * This function returns %FALSE for all indefinite types except * %G_VARIANT_TYPE_BASIC. * - * Returns: %TRUE if @type is a basic type Since 2.24 + * Returns: %TRUE if @type is a basic type + * + * Since 2.24 */ @@ -32710,7 +34504,9 @@ * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for * example. * - * Returns: %TRUE if @type is a container type Since 2.24 + * Returns: %TRUE if @type is a container type + * + * Since 2.24 */ @@ -32729,7 +34525,9 @@ * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in * %FALSE being returned. * - * Returns: %TRUE if @type is definite Since 2.24 + * Returns: %TRUE if @type is definite + * + * Since 2.24 */ @@ -32744,7 +34542,9 @@ * definite subtype is a dictionary entry type -- * %G_VARIANT_TYPE_DICT_ENTRY, for example. * - * Returns: %TRUE if @type is a dictionary entry type Since 2.24 + * Returns: %TRUE if @type is a dictionary entry type + * + * Since 2.24 */ @@ -32759,7 +34559,9 @@ * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for * example. * - * Returns: %TRUE if @type is a maybe type Since 2.24 + * Returns: %TRUE if @type is a maybe type + * + * Since 2.24 */ @@ -32774,7 +34576,9 @@ * types are considered to be subtypes of themselves. Aside from that, * only indefinite types can have subtypes. * - * Returns: %TRUE if @type is a subtype of @supertype Since 2.24 + * Returns: %TRUE if @type is a subtype of @supertype + * + * Since 2.24 */ @@ -32790,7 +34594,9 @@ * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for * example. * - * Returns: %TRUE if @type is a tuple type Since 2.24 + * Returns: %TRUE if @type is a tuple type + * + * Since 2.24 */ @@ -32800,7 +34606,9 @@ * * Determines if the given @type is the variant type. * - * Returns: %TRUE if @type is the variant type Since 2.24 + * Returns: %TRUE if @type is the variant type + * + * Since 2.24 */ @@ -32814,7 +34622,9 @@ * than the additional restriction, this call is equivalent to * g_variant_type_first(). * - * Returns: (transfer none): the key type of the dictionary entry Since 2.24 + * Returns: (transfer none): the key type of the dictionary entry + * + * Since 2.24 */ @@ -32832,7 +34642,9 @@ * In the case of a dictionary entry type, this function will always * return 2. * - * Returns: the number of items in @type Since 2.24 + * Returns: the number of items in @type + * + * Since 2.24 */ @@ -32861,7 +34673,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new array #GVariantType Since 2.24 + * Returns: (transfer full): a new array #GVariantType + * + * Since 2.24 */ @@ -32875,7 +34689,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new dictionary entry #GVariantType Since 2.24 + * Returns: (transfer full): a new dictionary entry #GVariantType + * + * Since 2.24 */ @@ -32888,7 +34704,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new maybe #GVariantType Since 2.24 + * Returns: (transfer full): a new maybe #GVariantType + * + * Since 2.24 */ @@ -32904,7 +34722,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new tuple #GVariantType Since 2.24 + * Returns: (transfer full): a new tuple #GVariantType + * + * Since 2.24 */ @@ -32924,7 +34744,9 @@ * * For tuples, %NULL is returned when @type is the last item in a tuple. * - * Returns: (transfer none): the next #GVariantType after @type, or %NULL Since 2.24 + * Returns: (transfer none): the next #GVariantType after @type, or %NULL + * + * Since 2.24 */ @@ -32938,7 +34760,9 @@ * * To get a nul-terminated string, see g_variant_type_dup_string(). * - * Returns: the corresponding type string (not nul-terminated) Since 2.24 + * Returns: the corresponding type string (not nul-terminated) + * + * Since 2.24 */ @@ -32950,7 +34774,9 @@ * equivalent to calling g_variant_type_string_scan() and confirming * that the following character is a nul terminator. * - * Returns: %TRUE if @type_string is exactly one valid type string Since 2.24 + * Returns: %TRUE if @type_string is exactly one valid type string + * + * Since 2.24 */ @@ -32987,7 +34813,9 @@ * * This function may only be used with a dictionary entry type. * - * Returns: (transfer none): the value type of the dictionary entry Since 2.24 + * Returns: (transfer none): the value type of the dictionary entry + * + * Since 2.24 */ @@ -33005,7 +34833,8 @@ /** * g_vasprintf: * @string: the return location for the newly-allocated string. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the GNU vasprintf() function which supports @@ -33022,7 +34851,8 @@ /** * g_vfprintf: * @file: the stream to write to. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -33035,7 +34865,8 @@ /** * g_vprintf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vprintf() function which supports @@ -33049,8 +34880,10 @@ /** * g_vsnprintf: * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the terminating nul character). - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @n: the maximum number of bytes to produce (including the + * terminating nul character). + * @format: a standard printf() format string, but notice + * string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * A safer form of the standard vsprintf() function. The output is guaranteed @@ -33071,14 +34904,16 @@ * The format string may contain positional parameters, as specified in * the Single Unix Specification. * - * Returns: the number of bytes which would be produced if the buffer was large enough. + * Returns: the number of bytes which would be produced if the buffer + * was large enough. */ /** * g_vsprintf: * @string: the buffer to hold the output. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vsprintf() function which supports @@ -33160,13 +34995,18 @@ /** * g_warning: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * 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 newline character will automatically be appended to @..., and + * need not be entered manually. */ @@ -33186,6 +35026,45 @@ /** + * g_win32_get_command_line: + * + * 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. + * + * Returns: (transfer full): the commandline arguments in the GLib + * filename encoding (ie: UTF-8) + * Since: 2.40 + */ + + +/** * g_win32_get_package_installation_directory: * @package: (allow-none): You should pass %NULL for this. * @dll_name: (allow-none): The name of a DLL that a package provides in UTF-8, or %NULL. @@ -33200,10 +35079,10 @@ * * 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 @@ -33232,8 +35111,12 @@ * the main executable of the process was loaded is used instead in * the same way as above. * - * Returns: a string containing the installation directory for @package. The string is in the GLib file name encoding, i.e. UTF-8. The return value should be freed with g_free() when not needed any longer. If the function fails %NULL is returned. - * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to g_win32_get_package_installation_directory_of_module() instead. + * Returns: a string containing the installation directory for + * @package. The string is in the GLib file name encoding, + * i.e. UTF-8. The return value should be freed with g_free() when not + * needed any longer. If the function fails %NULL is returned. + * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to + * g_win32_get_package_installation_directory_of_module() instead. */ @@ -33265,7 +35148,11 @@ * construct names of files in the installation tree it calls this * function passing the DLL handle. * - * Returns: a string containing the guessed installation directory for the software package @hmodule is from. The string is in the GLib file name encoding, i.e. UTF-8. The return value should be freed with g_free() when not needed any longer. If the function fails %NULL is returned. + * Returns: a string containing the guessed installation directory for + * the software package @hmodule is from. The string is in the GLib + * file name encoding, i.e. UTF-8. The return value should be freed + * with g_free() when not needed any longer. If the function fails + * %NULL is returned. * Since: 2.16 */ @@ -33288,8 +35175,14 @@ * particular, note that it is deprecated to pass anything except NULL * as @package. * - * Returns: a string containing the complete path to @subdir inside the installation directory of @package. The returned string is in the GLib file name encoding, i.e. UTF-8. The return value should be freed with g_free() when no longer needed. If something goes wrong, %NULL is returned. - * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to g_win32_get_package_installation_directory_of_module() instead, and then construct a subdirectory pathname with g_build_filename(). + * Returns: a string containing the complete path to @subdir inside + * the installation directory of @package. The returned string is in + * the GLib file name encoding, i.e. UTF-8. The return value should be + * freed with g_free() when no longer needed. If something goes wrong, + * %NULL is returned. + * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to + * g_win32_get_package_installation_directory_of_module() instead, and + * then construct a subdirectory pathname with g_build_filename(). */ @@ -33350,7 +35243,8 @@ * The return value is dynamically allocated and should be freed with * g_free() when no longer needed. * - * Returns: The converted filename, or %NULL on conversion failure and lack of short names. + * Returns: The converted filename, or %NULL on conversion + * failure and lack of short names. * Since: 2.8 */ @@ -33367,7 +35261,7 @@ /** * gchar: * - * Corresponds to the standard C <type>char</type> type. + * Corresponds to the standard C char type. */ @@ -33385,7 +35279,7 @@ /** * gdouble: * - * 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. */ @@ -33393,7 +35287,7 @@ /** * gfloat: * - * 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. */ @@ -33401,7 +35295,7 @@ /** * gint: * - * 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. */ @@ -33455,7 +35349,7 @@ /** * gintptr: * - * 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 @@ -33476,9 +35370,9 @@ /** * glib_check_version: - * @required_major: the required major version. - * @required_minor: the required minor version. - * @required_micro: the required micro version. + * @required_major: the required major version + * @required_minor: the required minor version + * @required_micro: the required micro version * * Checks that the GLib library in use is compatible with the * given version. Generally you would pass in the constants @@ -33495,7 +35389,10 @@ * version @required_major.required_minor.@required_micro * (same major version.) * - * Returns: %NULL if the GLib library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GLib and must not be modified or freed. + * Returns: %NULL if the GLib library is compatible with the + * given version, or a string describing the version mismatch. + * The returned string is owned by GLib and must not be modified + * or freed. * Since: 2.6 */ @@ -33524,7 +35421,8 @@ /** * glib_pgettext: - * @msgctxtid: a combined message context and message id, separated by a \004 character + * @msgctxtid: a combined message context and message id, separated + * by a \004 character * @msgidoffset: the offset of the message id in @msgctxid * * This function is a variant of glib_gettext() which supports @@ -33541,7 +35439,7 @@ /** * glong: * - * 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. */ @@ -33550,7 +35448,7 @@ * goffset: * * 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. * @@ -33565,15 +35463,14 @@ * gpointer: * * 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*. */ /** * gshort: * - * 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. */ @@ -33582,10 +35479,10 @@ * gsize: * * 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 @@ -33597,7 +35494,7 @@ * gssize: * * 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. * @@ -33609,14 +35506,14 @@ /** * guchar: * - * Corresponds to the standard C <type>unsigned char</type> type. + * Corresponds to the standard C unsigned char type. */ /** * guint: * - * 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. */ @@ -33646,7 +35543,7 @@ /** * guint64: * - * 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). * @@ -33666,7 +35563,7 @@ /** * guintptr: * - * 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 @@ -33679,7 +35576,7 @@ /** * gulong: * - * 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. */ @@ -33687,7 +35584,7 @@ /** * gushort: * - * 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. */ diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c new file mode 100644 index 00000000..c1a66a55 --- /dev/null +++ b/gir/gmodule-2.0.c @@ -0,0 +1,275 @@ +/************************************************************/ +/* THIS FILE IS GENERATED DO NOT EDIT */ +/************************************************************/ + +/** + * GModule: + * + * The #GModule struct is an opaque data structure to represent a + * [dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. + * It should only be accessed via the following functions. + */ + + +/** + * GModuleCheckInit: + * @module: the #GModule corresponding to the module which has just been loaded + * + * Specifies the type of the module initialization function. + * If a module contains a function named g_module_check_init() it is called + * automatically when the module is loaded. It is passed the #GModule structure + * and should return %NULL on success or a string describing the initialization + * error. + * + * Returns: %NULL on success, or a string describing the initialization error + */ + + +/** + * GModuleFlags: + * @G_MODULE_BIND_LAZY: specifies that symbols are only resolved when + * needed. The default action is to bind all symbols when the module + * is loaded. + * @G_MODULE_BIND_LOCAL: specifies that symbols in the module should + * not be added to the global name space. The default action on most + * platforms is to place symbols in the module in the global name space, + * which may cause conflicts with existing symbols. + * @G_MODULE_BIND_MASK: mask for all flags. + * + * Flags passed to g_module_open(). + * Note that these flags are not supported on all platforms. + */ + + +/** + * GModuleUnload: + * @module: the #GModule about to be unloaded + * + * Specifies the type of the module function called when it is unloaded. + * If a module contains a function named g_module_unload() it is called + * automatically when the module is unloaded. + * It is passed the #GModule structure. + */ + + +/** + * G_MODULE_EXPORT: + * + * Used to declare functions exported by modules. This is a no-op on Linux + * and Unices, but when compiling for Windows, it marks a symbol to be + * exported from the library or executable being built. + */ + + +/** + * G_MODULE_IMPORT: + * + * Used to declare functions imported from modules. + */ + + +/** + * G_MODULE_SUFFIX: + * + * Expands to the proper shared library suffix for the current platform + * without the leading dot. For most Unices and Linux this is "so", and + * for Windows this is "dll". + */ + + +/** + * SECTION:modules + * @title: Dynamic Loading of Modules + * @short_description: portable method for dynamically loading 'plug-ins' + * + * These functions provide a portable way to dynamically load object files + * (commonly known as 'plug-ins'). The current implementation supports all + * systems that provide an implementation of dlopen() (e.g. Linux/Sun), as + * well as Windows platforms via DLLs. + * + * A program which wants to use these functions must be linked to the + * libraries output by the command `pkg-config --libs gmodule-2.0`. + * + * To use them you must first determine whether dynamic loading + * is supported on the platform by calling g_module_supported(). + * If it is, you can open a module with g_module_open(), + * find the module's symbols (e.g. function names) with g_module_symbol(), + * and later close the module with g_module_close(). + * g_module_name() will return the file name of a currently opened module. + * + * If any of the above functions fail, the error status can be found with + * g_module_error(). + * + * The #GModule implementation features reference counting for opened modules, + * and supports hook functions within a module which are called when the + * module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). + * + * If your module introduces static data to common subsystems in the running + * program, e.g. through calling + * `g_quark_from_static_string ("my-module-stuff")`, + * it must ensure that it is never unloaded, by calling g_module_make_resident(). + * + * Example: Calling a function defined in a GModule + * |[<!-- language="C" --> + * // the function signature for 'say_hello' + * typedef void (* SayHelloFunc) (const char *message); + * + * gboolean + * just_say_hello (const char *filename, GError **error) + * { + * SayHelloFunc say_hello; + * GModule *module; + * + * module = g_module_open (filename, G_MODULE_BIND_LAZY); + * if (!module) + * { + * g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH, + * "%s", g_module_error ()); + * return FALSE; + * } + * + * if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello)) + * { + * g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, + * "%s: %s", filename, g_module_error ()); + * if (!g_module_close (module)) + * g_warning ("%s: %s", filename, g_module_error ()); + * return FALSE; + * } + * + * if (say_hello == NULL) + * { + * g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, + * "symbol say_hello is NULL"); + * if (!g_module_close (module)) + * g_warning ("%s: %s", filename, g_module_error ()); + * return FALSE; + * } + * + * // call our function in the module + * say_hello ("Hello world!"); + * + * if (!g_module_close (module)) + * g_warning ("%s: %s", filename, g_module_error ()); + * return TRUE; + * } + * ]| + */ + + +/** + * g_module_build_path: + * @directory: (allow-none): 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 + * @module_name: the name of the module + * + * A portable way to build the filename of a module. The platform-specific + * prefix and suffix are added to the filename, if needed, and the result + * is added to the directory, using the correct separator character. + * + * The directory should specify the directory where the module can be found. + * It can be %NULL or an empty string to indicate that the module is in a + * 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 `/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`. + * + * Returns: the complete path of the module, including the standard library + * prefix and suffix. This should be freed when no longer needed + */ + + +/** + * g_module_close: + * @module: a #GModule to close + * + * Closes a module. + * + * Returns: %TRUE on success + */ + + +/** + * g_module_error: + * + * Gets a string describing the last module error. + * + * Returns: a string describing the last module error + */ + + +/** + * g_module_make_resident: + * @module: a #GModule to make permanently resident + * + * Ensures that a module will never be unloaded. + * Any future g_module_close() calls on the module will be ignored. + */ + + +/** + * g_module_name: + * @module: a #GModule + * + * Returns the filename that the module was opened with. + * + * If @module refers to the application itself, "main" is returned. + * + * Returns: (transfer none): the filename of the module + */ + + +/** + * g_module_open: + * @file_name: (allow-none): the name of the file containing the module, or %NULL + * to obtain a #GModule representing the main program itself + * @flags: the flags used for opening the module. This can be the + * logical OR of any of the #GModuleFlags + * + * Opens a module. If the module has already been opened, + * its reference count is incremented. + * + * First of all g_module_open() tries to open @file_name as a module. + * If that fails and @file_name has the ".la"-suffix (and is a libtool + * archive) it tries to open the corresponding module. If that fails + * and it doesn't have the proper module suffix for the platform + * (#G_MODULE_SUFFIX), this suffix will be appended and the corresponding + * module will be opended. If that fails and @file_name doesn't have the + * ".la"-suffix, this suffix is appended and g_module_open() tries to open + * the corresponding module. If eventually that fails as well, %NULL is + * returned. + * + * Returns: a #GModule on success, or %NULL on failure + */ + + +/** + * g_module_supported: + * + * Checks if modules are supported on the current platform. + * + * Returns: %TRUE if modules are supported + */ + + +/** + * g_module_symbol: + * @module: a #GModule + * @symbol_name: the name of the symbol to find + * @symbol: (out): returns the pointer to the symbol value + * + * Gets a symbol pointer from a module, such as one exported + * by #G_MODULE_EXPORT. Note that a valid symbol can be %NULL. + * + * Returns: %TRUE on success + */ + + + +/************************************************************/ +/* THIS FILE IS GENERATED DO NOT EDIT */ +/************************************************************/ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 81e65a32..ea1dbc16 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -63,13 +63,13 @@ * 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. */ @@ -77,7 +77,7 @@ /** * GParamSpecPool: * - * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be + * A #GParamSpecPool maintains a collection of #GParamSpecs which can be * quickly accessed by owner and name. The implementation of the #GObject property * system uses such a pool to store the #GParamSpecs of the properties all object * types. @@ -102,9 +102,9 @@ * objects. * * If the object's #GObjectClass.dispose method results in additional - * references to the object being held, any #GWeakRef<!-- -->s taken + * references to the object being held, any #GWeakRefs taken * before it was disposed will continue to point to %NULL. If - * #GWeakRef<!-- -->s are taken after the object is disposed and + * #GWeakRefs are taken after the object is disposed and * re-referenced, they will continue to point to it until its refcount * goes back to zero, at which point they too will be invalidated. */ @@ -114,7 +114,8 @@ * SECTION:enumerations_flags * @short_description: Enumeration and flags types * @title: Enumeration and Flag Types - * @see_also: #GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags() + * @see_also: #GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), + * g_param_spec_flags() * * The GLib type system provides fundamental types for enumeration and * flags types. (Flags types are like enumerations, but allow their @@ -127,9 +128,8 @@ * GLib type system, it can be used as value type for object * properties, using g_param_spec_enum() or g_param_spec_flags(). * - * GObject ships with a utility called <link - * linkend="glib-mkenums">glib-mkenums</link> that can construct - * suitable type registration functions from C enumeration + * GObject ships with a utility called [glib-mkenums][glib-mkenums], + * that can construct suitable type registration functions from C enumeration * definitions. */ @@ -145,21 +145,21 @@ * value is applied to the target property; for instance, the following * binding: * - * |[ + * |[<!-- language="C" --> * g_object_bind_property (object1, "property-a", * object2, "property-b", * G_BINDING_DEFAULT); * ]| * - * will cause <emphasis>object2:property-b</emphasis> to be updated every - * time g_object_set() or the specific accessor changes the value of - * <emphasis>object1:property-a</emphasis>. + * will cause the property named "property-b" of @object2 to be updated + * every time g_object_set() or the specific accessor changes the value of + * the property "property-a" of @object1. * * It is possible to create a bidirectional binding between two properties * of two #GObject instances, so that if either property changes, the * other is updated as well, for instance: * - * |[ + * |[<!-- language="C" --> * g_object_bind_property (object1, "property-a", * object2, "property-b", * G_BINDING_BIDIRECTIONAL); @@ -172,7 +172,7 @@ * transformation from the source value to the target value before * applying it; for instance, the following binding: * - * |[ + * |[<!-- language="C" --> * g_object_bind_property_full (adjustment1, "value", * adjustment2, "value", * G_BINDING_BIDIRECTIONAL, @@ -181,15 +181,15 @@ * NULL, NULL); * ]| * - * will keep the <emphasis>value</emphasis> property of the two adjustments - * in sync; the <function>celsius_to_fahrenheit</function> function will be - * called whenever the <emphasis>adjustment1:value</emphasis> property changes - * and will transform the current value of the property before applying it - * to the <emphasis>adjustment2:value</emphasis> property; vice versa, the - * <function>fahrenheit_to_celsius</function> function will be called whenever - * the <emphasis>adjustment2:value</emphasis> property changes, and will - * transform the current value of the property before applying it to the - * <emphasis>adjustment1:value</emphasis>. + * will keep the "value" property of the two adjustments in sync; the + * @celsius_to_fahrenheit function will be called whenever the "value" + * property of @adjustment1 changes and will transform the current value + * of the property before applying it to the "value" property of @adjustment2. + * + * Vice versa, the @fahrenheit_to_celsius function will be called whenever + * the "value" property of @adjustment2 changes, and will transform the + * current value of the property before applying it to the "value" property + * of @adjustment1. * * Note that #GBinding does not resolve cycles by itself; a cycle like * @@ -210,13 +210,19 @@ * either one of the #GObject instances it refers to are finalized, or when * the #GBinding instance loses its last reference. * + * Bindings for languages with garbage collection can use + * g_binding_unbind() to explicitly release a binding between the source + * and target properties, instead of relying on the last reference on the + * binding, source, and target instances to drop. + * * #GBinding is available since GObject 2.26 */ /** * SECTION:gboxed - * @short_description: A mechanism to wrap opaque C structures registered by the type system + * @short_description: A mechanism to wrap opaque C structures registered + * by the type system * @see_also: #GParamSpecBoxed, g_param_spec_boxed() * @title: Boxed Types * @@ -238,13 +244,13 @@ * A #GClosure represents a callback supplied by the programmer. It * will generally comprise a function of some kind and a marshaller * used to call it. It is the reponsibility of the marshaller to - * convert the arguments for the invocation from #GValue<!-- -->s into + * convert the arguments for the invocation from #GValues into * a suitable form, perform the callback on the converted arguments, * and transform the return value back into a #GValue. * * In the case of C programs, a closure usually just holds a pointer * to a function and maybe a data argument, and the marshaller - * converts between #GValue<!-- --> and native C types. The GObject + * converts between #GValue and native C types. The GObject * library provides the #GCClosure type for this purpose. Bindings for * other languages need marshallers which convert between #GValue<!-- * -->s and suitable representations in the runtime of the language in @@ -256,9 +262,8 @@ * marshaller for any closure which is connected to this * signal. GObject provides a number of C marshallers for this * purpose, see the g_cclosure_marshal_*() functions. Additional C - * marshallers can be generated with the <link - * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures - * can be explicitly connected to signals with + * marshallers can be generated with the [glib-genmarshal][glib-genmarshal] + * utility. Closures can be explicitly connected to signals with * g_signal_connect_closure(), but it usually more convenient to let * GObject create a closure automatically by using one of the * g_signal_connect_*() functions which take a callback function/user @@ -266,29 +271,29 @@ * * Using closures has a number of important advantages over a simple * callback function/data pointer combination: - * <itemizedlist> - * <listitem><para> - * Closures allow the callee to get the types of the callback parameters, - * which means that language bindings don't have to write individual glue - * for each callback type. - * </para></listitem> - * <listitem><para> - * The reference counting of #GClosure makes it easy to handle reentrancy - * right; if a callback is removed while it is being invoked, the closure - * and its parameters won't be freed until the invocation finishes. - * </para></listitem> - * <listitem><para> - * g_closure_invalidate() and invalidation notifiers allow callbacks to be - * automatically removed when the objects they point to go away. - * </para></listitem> - * </itemizedlist> + * + * - Closures allow the callee to get the types of the callback parameters, + * which means that language bindings don't have to write individual glue + * for each callback type. + * + * - The reference counting of #GClosure makes it easy to handle reentrancy + * right; if a callback is removed while it is being invoked, the closure + * and its parameters won't be freed until the invocation finishes. + * + * - g_closure_invalidate() and invalidation notifiers allow callbacks to be + * automatically removed when the objects they point to go away. */ /** * SECTION:generic_values - * @short_description: A polymorphic type that can hold values of any other type - * @see_also: The fundamental types which all support #GValue operations and thus can be used as a type initializer for g_value_init() are defined by a separate interface. See the <link linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values API</link> for details. + * @short_description: A polymorphic type that can hold values of any + * other type + * @see_also: The fundamental types which all support #GValue + * operations and thus can be used as a type initializer for + * g_value_init() are defined by a separate interface. See the + * [standard values API][gobject-Standard-Parameter-and-Value-Types] + * for details * @title: Generic values * * The #GValue structure is basically a variable container that consists @@ -306,8 +311,8 @@ * The code in the example program below demonstrates #GValue's * features. * - * |[ - * #include <glib-object.h> + * |[<!-- language="C" --> + * #include <glib-object.h> * * static void * int2string (const GValue *src_value, @@ -323,42 +328,40 @@ * main (int argc, * char *argv[]) * { - * /* GValues must be initialized */ + * // GValues must be initialized * GValue a = G_VALUE_INIT; * GValue b = G_VALUE_INIT; * const gchar *message; * - * g_type_init (); - * - * /* The GValue starts empty */ - * g_assert (!G_VALUE_HOLDS_STRING (&a)); + * // The GValue starts empty + * g_assert (!G_VALUE_HOLDS_STRING (&a)); * - * /* Put a string in it */ - * g_value_init (&a, G_TYPE_STRING); - * g_assert (G_VALUE_HOLDS_STRING (&a)); - * g_value_set_static_string (&a, "Hello, world!"); - * g_printf ("%s\n", g_value_get_string (&a)); + * // Put a string in it + * g_value_init (&a, G_TYPE_STRING); + * g_assert (G_VALUE_HOLDS_STRING (&a)); + * g_value_set_static_string (&a, "Hello, world!"); + * g_printf ("%s\n", g_value_get_string (&a)); * - * /* Reset it to its pristine state */ - * g_value_unset (&a); + * // Reset it to its pristine state + * g_value_unset (&a); * - * /* It can then be reused for another type */ - * g_value_init (&a, G_TYPE_INT); - * g_value_set_int (&a, 42); + * // It can then be reused for another type + * g_value_init (&a, G_TYPE_INT); + * g_value_set_int (&a, 42); * - * /* Attempt to transform it into a GValue of type STRING */ - * g_value_init (&b, G_TYPE_STRING); + * // Attempt to transform it into a GValue of type STRING + * g_value_init (&b, G_TYPE_STRING); * - * /* An INT is transformable to a STRING */ + * // An INT is transformable to a STRING * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); * - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); * - * /* Attempt to transform it again using a custom transform function */ + * // Attempt to transform it again using a custom transform function * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); * return 0; * } * ]| @@ -368,47 +371,51 @@ /** * SECTION:gparamspec * @short_description: Metadata for parameter specifications - * @see_also: g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func() + * @see_also: g_object_class_install_property(), g_object_set(), + * g_object_get(), g_object_set_property(), g_object_get_property(), + * g_value_register_transform_func() * @title: GParamSpec * * #GParamSpec is an object structure that encapsulates the metadata * required to specify parameters, such as e.g. #GObject properties. * - * <para id="canonical-parameter-name"> - * Parameter names need to start with a letter (a-z or A-Z). Subsequent - * characters can be letters, numbers or a '-'. + * ## Parameter names # {#canonical-parameter-names} + * + * Parameter names need to start with a letter (a-z or A-Z). + * Subsequent characters can be letters, numbers or a '-'. * All other characters are replaced by a '-' during construction. - * The result of this replacement is called the canonical name of the - * parameter. - * </para> + * The result of this replacement is called the canonical name of + * the parameter. */ /** * SECTION:gtype - * @short_description: The GLib Runtime type identification and management system + * @short_description: The GLib Runtime type identification and + * management system * @title: Type Information * * The GType API is the foundation of the GObject system. It provides the * facilities for registering and managing all fundamental data types, - * user-defined object and interface types. Before using any GType - * or GObject functions, g_type_init() must be called to initialize the - * type system. + * user-defined object and interface types. * * For type creation and registration purposes, all types fall into one of * two categories: static or dynamic. Static types are never loaded or * unloaded at run-time as dynamic types may be. Static types are created * with g_type_register_static() that gets type specific information passed * in via a #GTypeInfo structure. + * * Dynamic types are created with g_type_register_dynamic() which takes a * #GTypePlugin structure instead. The remaining type information (the * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin * and the g_type_plugin_*() API. + * * These registration functions are usually called only once from a * function whose only purpose is to return the type identifier for a * specific class. Once the type (or class or interface) is registered, * it may be instantiated, inherited, or implemented depending on exactly * what sort of type it is. + * * There is also a third registration function for registering fundamental * types called g_type_register_fundamental() which requires both a #GTypeInfo * structure and a #GTypeFundamentalInfo structure but it is seldom used @@ -421,32 +428,30 @@ * separately (typically by using #GArray or #GPtrArray) and put a pointer * to the buffer in the structure. * - * A final word about type names. - * Such an identifier needs to be at least three characters long. There is no - * upper length limit. The first character needs to be a letter (a-z or A-Z) - * or an underscore '_'. Subsequent characters can be letters, numbers or - * any of '-_+'. + * A final word about type names: Such an identifier needs to be at least + * three characters long. There is no upper length limit. The first character + * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent + * characters can be letters, numbers or any of '-_+'. */ /** * SECTION:gtypemodule * @short_description: Type loading modules - * @see_also: <variablelist> <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist> + * @see_also: #GTypePlugin, #GModule * @title: GTypeModule * * #GTypeModule provides a simple implementation of the #GTypePlugin * interface. The model of #GTypeModule is a dynamically loaded module - * which implements some number of types and interface - * implementations. When the module is loaded, it registers its types - * and interfaces using g_type_module_register_type() and - * g_type_module_add_interface(). As long as any instances of these - * types and interface implementations are in use, the module is kept - * loaded. When the types and interfaces are gone, the module may be - * unloaded. If the types and interfaces become used again, the module - * will be reloaded. Note that the last unref cannot happen in module - * code, since that would lead to the caller's code being unloaded before - * g_object_unref() returns to it. + * which implements some number of types and interface implementations. + * When the module is loaded, it registers its types and interfaces + * using g_type_module_register_type() and g_type_module_add_interface(). + * As long as any instances of these types and interface implementations + * are in use, the module is kept loaded. When the types and interfaces + * are gone, the module may be unloaded. If the types and interfaces + * become used again, the module will be reloaded. Note that the last + * unref cannot happen in module code, since that would lead to the + * caller's code being unloaded before g_object_unref() returns to it. * * Keeping track of whether the module should be loaded or not is done by * using a use count - it starts at zero, and whenever it is greater than @@ -471,49 +476,40 @@ * @see_also: #GTypeModule and g_type_register_dynamic(). * @title: GTypePlugin * - * The GObject type system supports dynamic loading of types. The - * #GTypePlugin interface is used to handle the lifecycle of - * dynamically loaded types. It goes as follows: - * - * <orderedlist> - * <listitem><para> - * The type is initially introduced (usually upon loading the module - * the first time, or by your main application that knows what modules - * introduces what types), like this: - * |[ - * new_type_id = g_type_register_dynamic (parent_type_id, - * "TypeName", - * new_type_plugin, - * type_flags); - * ]| - * where <literal>new_type_plugin</literal> is an implementation of the - * #GTypePlugin interface. - * </para></listitem> - * <listitem><para> - * The type's implementation is referenced, e.g. through + * The GObject type system supports dynamic loading of types. + * The #GTypePlugin interface is used to handle the lifecycle + * of dynamically loaded types. It goes as follows: + * + * 1. The type is initially introduced (usually upon loading the module + * the first time, or by your main application that knows what modules + * introduces what types), like this: + * |[<!-- language="C" --> + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where @new_type_plugin is an implementation of the + * #GTypePlugin interface. + * + * 2. The type's implementation is referenced, e.g. through * g_type_class_ref() or through g_type_create_instance() (this is * being called by g_object_new()) or through one of the above done on - * a type derived from <literal>new_type_id</literal>. - * </para></listitem> - * <listitem><para> - * This causes the type system to load the type's implementation by calling - * g_type_plugin_use() and g_type_plugin_complete_type_info() on - * <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * At some point the type's implementation isn't required anymore, e.g. after - * g_type_class_unref() or g_type_free_instance() (called when the reference - * count of an instance drops to zero). - * </para></listitem> - * <listitem><para> - * This causes the type system to throw away the information retrieved from - * g_type_plugin_complete_type_info() and then it calls - * g_type_plugin_unuse() on <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * Things may repeat from the second step. - * </para></listitem> - * </orderedlist> + * a type derived from @new_type_id. + * + * 3. This causes the type system to load the type's implementation by + * calling g_type_plugin_use() and g_type_plugin_complete_type_info() + * on @new_type_plugin. + * + * 4. At some point the type's implementation isn't required anymore, + * e.g. after g_type_class_unref() or g_type_free_instance() (called + * when the reference count of an instance drops to zero). + * + * 5. This causes the type system to throw away the information retrieved + * from g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on @new_type_plugin. + * + * 6. Things may repeat from the second step. * * So basically, you need to implement a #GTypePlugin type that * carries a use_count, once use_count goes from zero to one, you need @@ -540,57 +536,59 @@ * methods for all object types in GTK+, Pango and other libraries * based on GObject. The GObject class provides methods for object * construction and destruction, property access methods, and signal - * support. Signals are described in detail in <xref - * linkend="gobject-Signals"/>. + * support. Signals are described in detail [here][gobject-Signals]. + * + * ## Floating references # {#floating-ref} * - * <para id="floating-ref"> * GInitiallyUnowned is derived from GObject. The only difference between * the two is that the initial reference of a GInitiallyUnowned is flagged - * as a <firstterm>floating</firstterm> reference. - * This means that it is not specifically claimed to be "owned" by - * any code portion. The main motivation for providing floating references is - * C convenience. In particular, it allows code to be written as: - * |[ + * as a "floating" reference. This means that it is not specifically + * claimed to be "owned" by any code portion. The main motivation for + * providing floating references is C convenience. In particular, it + * allows code to be written as: + * |[<!-- language="C" --> * container = create_container (); * container_add_child (container, create_child()); * ]| - * If <function>container_add_child()</function> will g_object_ref_sink() the - * passed in child, no reference of the newly created child is leaked. - * Without floating references, <function>container_add_child()</function> - * can only g_object_ref() the new child, so to implement this code without - * reference leaks, it would have to be written as: - * |[ + * If container_add_child() calls g_object_ref_sink() on the passed-in child, + * no reference of the newly created child is leaked. Without floating + * references, container_add_child() can only g_object_ref() the new child, + * so to implement this code without reference leaks, it would have to be + * written as: + * |[<!-- language="C" --> * Child *child; * container = create_container (); * child = create_child (); * container_add_child (container, child); * g_object_unref (child); * ]| - * The floating reference can be converted into - * an ordinary reference by calling g_object_ref_sink(). - * For already sunken objects (objects that don't have a floating reference - * anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns - * a new reference. + * The floating reference can be converted into an ordinary reference by + * calling g_object_ref_sink(). For already sunken objects (objects that + * don't have a floating reference anymore), g_object_ref_sink() is equivalent + * to g_object_ref() and returns a new reference. + * * Since floating references are useful almost exclusively for C convenience, * language bindings that provide automated reference and memory ownership * maintenance (such as smart pointers or garbage collection) should not * expose floating references in their API. - * </para> * * Some object implementations may need to save an objects floating state * across certain code portions (an example is #GtkMenu), to achieve this, * the following sequence can be used: * - * |[ - * /* save floating state */ + * |[<!-- language="C" --> + * // save floating state * gboolean was_floating = g_object_is_floating (object); * g_object_ref_sink (object); - * /* protected code portion */ - * ...; - * /* restore floating state */ + * // protected code portion + * + * ... + * + * // restore floating state * if (was_floating) * g_object_force_floating (object); - * g_object_unref (object); /* release previously acquired reference */ + * else + * g_object_unref (object); // release previously acquired reference * ]| */ @@ -617,61 +615,60 @@ /** * SECTION:signals - * @short_description: A means for customization of object behaviour and a general purpose notification mechanism + * @short_description: A means for customization of object behaviour + * and a general purpose notification mechanism * @title: Signals * - * The basic concept of the signal system is that of the - * <emphasis>emission</emphasis> of a signal. Signals are introduced - * per-type and are identified through strings. Signals introduced - * for a parent type are available in derived types as well, so - * basically they are a per-type facility that is inherited. A signal - * emission mainly involves invocation of a certain set of callbacks - * in precisely defined manner. There are two main categories of such - * callbacks, per-object - * <footnote><para>Although signals can deal with any kind of instantiatable - * type, i'm referring to those types as "object types" in the following, - * simply because that is the context most users will encounter signals in. - * </para></footnote> - * ones and user provided ones. + * The basic concept of the signal system is that of the emission + * of a signal. Signals are introduced per-type and are identified + * through strings. Signals introduced for a parent type are available + * in derived types as well, so basically they are a per-type facility + * that is inherited. + * + * A signal emission mainly involves invocation of a certain set of + * callbacks in precisely defined manner. There are two main categories + * of such callbacks, per-object ones and user provided ones. + * (Although signals can deal with any kind of instantiatable type, I'm + * referring to those types as "object types" in the following, simply + * because that is the context most users will encounter signals in.) * The per-object callbacks are most often referred to as "object method * handler" or "default (signal) handler", while user provided callbacks are * usually just called "signal handler". + * * The object method handler is provided at signal creation time (this most * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a certain - * signal on certain object instances. + * provided handlers are frequently connected and disconnected to/from a + * certain signal on certain object instances. * * A signal emission consists of five stages, unless prematurely stopped: - * <variablelist> - * <varlistentry><term></term><listitem><para> - * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * </para></listitem></varlistentry> - * </variablelist> + * + * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + * + * 2. Invocation of normal user-provided signal handlers (where the @after + * flag is not set) + * + * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + * + * 4. Invocation of user provided signal handlers (where the @after flag is set) + * + * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + * * The user-provided signal handlers are called in the order they were * connected in. + * * All handlers may prematurely stop a signal emission, and any number of * handlers may be connected, disconnected, blocked or unblocked during * a signal emission. + * * There are certain criteria for skipping user handlers in stages 2 and 4 * of a signal emission. - * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted - * during callback invocation, to return from the "blocked" state, a - * handler has to get unblocked exactly the same amount of times - * it has been blocked before. + * + * First, user handlers may be blocked. Blocked handlers are omitted during + * callback invocation, to return from the blocked state, a handler has to + * get unblocked exactly the same amount of times it has been blocked before. + * * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional - * "detail" argument passed in to g_signal_emit() has to match the detail + * @detail argument passed in to g_signal_emit() has to match the detail * argument of the signal handler currently subject to invocation. * Specification of no detail argument for signal handlers (omission of the * detail part of the signal specification upon connection) serves as a @@ -681,7 +678,8 @@ /** * SECTION:value_arrays - * @short_description: A container structure to maintain an array of generic values + * @short_description: A container structure to maintain an array of + * generic values * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() * @title: Value arrays * @@ -696,13 +694,13 @@ * g_value_unset() as the clear function using g_array_set_clear_func(), * for instance, the following code: * - * |[ + * |[<!-- language="C" --> * GValueArray *array = g_value_array_new (10); * ]| * * can be replaced by: * - * |[ + * |[<!-- language="C" --> * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); * ]| @@ -713,7 +711,7 @@ * g_binding_get_flags: * @binding: a #GBinding * - * Retrieves the flags passed when constructing the #GBinding + * Retrieves the flags passed when constructing the #GBinding. * * Returns: the #GBindingFlags used by the #GBinding * Since: 2.26 @@ -724,7 +722,7 @@ * g_binding_get_source: * @binding: a #GBinding * - * Retrieves the #GObject instance used as the source of the binding + * Retrieves the #GObject instance used as the source of the binding. * * Returns: (transfer none): the source #GObject * Since: 2.26 @@ -736,7 +734,7 @@ * @binding: a #GBinding * * Retrieves the name of the property of #GBinding:source used as the source - * of the binding + * of the binding. * * Returns: the name of the source property * Since: 2.26 @@ -747,7 +745,7 @@ * g_binding_get_target: * @binding: a #GBinding * - * Retrieves the #GObject instance used as the target of the binding + * Retrieves the #GObject instance used as the target of the binding. * * Returns: (transfer none): the target #GObject * Since: 2.26 @@ -759,7 +757,7 @@ * @binding: a #GBinding * * Retrieves the name of the property of #GBinding:target used as the target - * of the binding + * of the binding. * * Returns: the name of the target property * Since: 2.26 @@ -767,13 +765,29 @@ /** + * g_binding_unbind: + * @binding: a #GBinding + * + * Explicitly releases the binding between the source and the target + * property expressed by @binding. + * + * 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. + * + * Since: 2.38 + */ + + +/** * g_boxed_copy: * @boxed_type: The type of @src_boxed. * @src_boxed: The boxed structure to be copied. * * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. * - * Returns: The newly created copy of the boxed structure. + * Returns: (transfer full): The newly created copy of the boxed structure. */ @@ -806,11 +820,12 @@ * @return_value: a #GValue which can store the returned #gboolean * @n_param_values: 2 * @param_values: a #GValue array holding instance and arg1 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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. */ @@ -821,11 +836,12 @@ * @return_value: a #GValue, which can store the returned string * @n_param_values: 3 * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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 */ @@ -844,11 +860,12 @@ * @return_value: a #GValue, which can store the returned string * @n_param_values: 3 * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -858,11 +875,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gboolean parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -872,11 +890,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GBoxed* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -886,11 +905,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gchar parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -900,11 +920,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gdouble parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -914,11 +935,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the enumeration parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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.. */ @@ -928,11 +950,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the flags parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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. */ @@ -942,11 +965,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gfloat parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -956,11 +980,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gint parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -970,11 +995,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #glong parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -984,11 +1010,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GObject* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -998,11 +1025,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1012,11 +1040,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gpointer parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1026,11 +1055,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gchar* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1040,11 +1070,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #guchar parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1054,11 +1085,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #guint parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1068,11 +1100,12 @@ * @return_value: ignored * @n_param_values: 3 * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1082,11 +1115,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gulong parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ @@ -1096,11 +1130,12 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GVariant* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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 */ @@ -1112,25 +1147,31 @@ * @return_value: ignored * @n_param_values: 1 * @param_values: a #GValue array holding only the instance - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * 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)`. */ /** * g_cclosure_marshal_generic: * @closure: A #GClosure. - * @return_gvalue: A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. + * @return_gvalue: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValue<!-- -->s holding the arguments on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to g_closure_invoke(). - * @marshal_data: Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * 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 */ @@ -1280,9 +1321,13 @@ /** * g_closure_invoke: * @closure: a #GClosure - * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure + * doesn't return a value. * @n_param_values: the length of the @param_values array - * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @param_values: (array length=n_param_values): an array of + * #GValues holding the arguments on which to + * invoke the callback of @closure * @invocation_hint: (allow-none): a context-dependent invocation hint * * Invokes the closure, i.e. executes the callback represented by the @closure. @@ -1291,8 +1336,10 @@ /** * g_closure_new_object: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> - * @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure + * @sizeof_closure: the size of the structure to allocate, must be at least + * `sizeof (GClosure)` + * @object: a #GObject pointer to store in the @data field of the newly + * allocated #GClosure * * A variant of g_closure_new_simple() which stores @object in the * @data field of the closure and calls g_object_watch_closure() on @@ -1305,14 +1352,15 @@ /** * g_closure_new_simple: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> + * @sizeof_closure: the size of the structure to allocate, must be at least + * `sizeof (GClosure)` * @data: data to store in the @data field of the newly allocated #GClosure * * 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 * { @@ -1363,7 +1411,8 @@ /** * g_closure_remove_finalize_notifier: (skip) * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_finalize_notifier() when registering @notify_func + * @notify_data: data which was passed to g_closure_add_finalize_notifier() + * when registering @notify_func * @notify_func: the callback function to remove * * Removes a finalization notifier. @@ -1375,7 +1424,8 @@ /** * g_closure_remove_invalidate_notifier: (skip) * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func + * @notify_data: data which was passed to g_closure_add_invalidate_notifier() + * when registering @notify_func * @notify_func: the callback function to remove * * Removes an invalidation notifier. @@ -1389,7 +1439,7 @@ * @closure: a #GClosure * @marshal: a #GClosureMarshal function * - * 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_*() @@ -1407,9 +1457,8 @@ * 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. @@ -1424,30 +1473,31 @@ /** * g_closure_sink: - * @closure: #GClosure to decrement the initial reference count on, if it's still being held + * @closure: #GClosure to decrement the initial reference count on, if it's + * still being held * * 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) @@ -1482,14 +1532,16 @@ /** * g_enum_complete_type_info: * @g_enum_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * @info: (out callee-allocates): the #GTypeInfo struct to be filled in + * @const_values: An array of #GEnumValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. * - * 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, @@ -1515,7 +1567,8 @@ * * Returns the #GEnumValue for a value. * - * Returns: the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration + * Returns: (transfer none): the #GEnumValue for @value, or %NULL + * if @value is not a member of the enumeration */ @@ -1526,7 +1579,9 @@ * * Looks up a #GEnumValue by name. * - * Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name + * Returns: (transfer none): the #GEnumValue with name @name, + * or %NULL if the enumeration doesn't have a member + * with that name */ @@ -1537,21 +1592,25 @@ * * Looks up a #GEnumValue by nickname. * - * Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname + * Returns: (transfer none): the #GEnumValue with nickname @nick, + * or %NULL if the enumeration doesn't have a member + * with that nickname */ /** * g_enum_register_static: * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * @const_static_values: An array of #GEnumValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. GObject keeps a reference to the data, so it cannot + * be stack-allocated. * * 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(). * * Returns: The new type identifier. */ @@ -1560,8 +1619,10 @@ /** * g_flags_complete_type_info: * @g_flags_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * @info: (out callee-allocates): the #GTypeInfo struct to be filled in + * @const_values: An array of #GFlagsValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. * * This function is meant to be called from the complete_type_info() * function of a #GTypePlugin implementation, see the example for @@ -1576,7 +1637,8 @@ * * Returns the first #GFlagsValue which is set in @value. * - * Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set + * Returns: (transfer none): the first #GFlagsValue which is set in + * @value, or %NULL if none is set */ @@ -1587,7 +1649,8 @@ * * Looks up a #GFlagsValue by name. * - * Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with that name + * Returns: (transfer none): the #GFlagsValue with name @name, + * or %NULL if there is no flag with that name */ @@ -1598,21 +1661,23 @@ * * Looks up a #GFlagsValue by nickname. * - * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname + * Returns: (transfer none): the #GFlagsValue with nickname @nick, + * or %NULL if there is no flag with that nickname */ /** * g_flags_register_static: * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * @const_static_values: An array of #GFlagsValue structs for the possible + * flags values. The array is terminated by a struct with all members being 0. + * GObject keeps a reference to the data, so it cannot be stack-allocated. * * 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(). * * Returns: The new type identifier. */ @@ -1621,7 +1686,9 @@ /** * g_object_add_toggle_ref: (skip) * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @notify: a function to call when this reference is the + * last reference to the object, or is no longer + * the last reference. * @data: data to pass to @notify * * Increases the reference count of the object by one and sets a @@ -1640,8 +1707,8 @@ * 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 @@ -1705,7 +1772,9 @@ * * A #GObject can have multiple bindings. * - * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. + * Returns: (transfer none): the #GBinding instance representing the + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * Since: 2.26 */ @@ -1717,10 +1786,14 @@ * @target: (type GObject.Object): the target #GObject * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding - * @transform_to: (scope notified) (allow-none): the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: (scope notified) (allow-none): the transformation function from the @target to the @source, or %NULL to use the default - * @user_data: custom data to be passed to the transformation functions, or %NULL - * @notify: function to be called when disposing the binding, to free the resources used by the transformation functions + * @transform_to: (scope notified) (allow-none): the transformation function + * from the @source to the @target, or %NULL to use the default + * @transform_from: (scope notified) (allow-none): the transformation function + * from the @target to the @source, or %NULL to use the default + * @user_data: custom data to be passed to the transformation functions, + * or %NULL + * @notify: function to be called when disposing the binding, to free the + * resources used by the transformation functions * * Complete version of g_object_bind_property(). * @@ -1740,37 +1813,42 @@ * * 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. * - * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. + * Returns: (transfer none): the #GBinding instance representing the + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * Since: 2.26 */ /** - * g_object_bind_property_with_closures: + * g_object_bind_property_with_closures: (rename-to g_object_bind_property_full) * @source: (type GObject.Object): the source #GObject * @source_property: the property on @source to bind * @target: (type GObject.Object): the target #GObject * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding - * @transform_to: a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default + * @transform_to: a #GClosure wrapping the transformation function + * from the @source to the @target, or %NULL to use the default + * @transform_from: a #GClosure wrapping the transformation function + * from the @target to the @source, or %NULL to use the default * * Creates a binding between @source_property on @source and @target_property * 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. * - * Rename to: g_object_bind_property_full - * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. + * Returns: (transfer none): the #GBinding instance representing the + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * Since: 2.26 */ @@ -1782,17 +1860,19 @@ * * Looks up the #GParamSpec for a property of a class. * - * Returns: (transfer none): the #GParamSpec for the property, or %NULL if the class doesn't have a property of that name + * Returns: (transfer none): the #GParamSpec for the property, or + * %NULL if the class doesn't have a property of that name */ /** * g_object_class_install_properties: * @oclass: a #GObjectClass - * @n_pspecs: the length of the #GParamSpec<!-- -->s array - * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array defining the new properties + * @n_pspecs: the length of the #GParamSpecs array + * @pspecs: (array length=n_pspecs): the #GParamSpecs array + * defining the new properties * - * 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 @@ -1802,10 +1882,10 @@ * 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 * }; @@ -1838,7 +1918,7 @@ * * allows calling g_object_notify_by_pspec() to notify of property changes: * - * |[ + * |[<!-- language="C" --> * void * my_object_set_foo (MyObject *self, gint foo) * { @@ -1875,7 +1955,8 @@ * * Get an array of #GParamSpec* for all properties of a class. * - * Returns: (array length=n_properties) (transfer container): an array of #GParamSpec* which should be freed after use + * Returns: (array length=n_properties) (transfer container): an array of + * #GParamSpec* which should be freed after use */ @@ -1883,15 +1964,15 @@ * g_object_class_override_property: * @oclass: a #GObjectClass * @property_id: the new property ID - * @name: the name of a property registered in a parent class or in an interface of this class. + * @name: the name of a property registered in a parent class or + * in an interface of this class. * - * 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 @@ -1902,7 +1983,6 @@ * 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 */ @@ -1912,78 +1992,31 @@ * g_object_connect: (skip) * @object: a #GObject * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL + * @...: #GCallback for the first signal, followed by data for the + * first signal, followed optionally by more signal + * spec/callback/data triples, followed by %NULL * * 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, * NULL), * "signal::event", gtk_menu_window_event, menu, * "signal::size_request", gtk_menu_window_size_request, menu, - * "signal::destroy", gtk_widget_destroyed, &menu->toplevel, + * "signal::destroy", gtk_widget_destroyed, &menu->toplevel, * NULL); * ]| * @@ -1995,7 +2028,9 @@ * g_object_disconnect: (skip) * @object: a #GObject * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL + * @...: #GCallback for the first signal, followed by data for the first signal, + * followed optionally by more signal spec/callback/data triples, + * followed by %NULL * * A convenience function to disconnect multiple signals at once. * @@ -2028,7 +2063,10 @@ * threads are using object data on the same key on the same * object. * - * Returns: the result of calling @dup_func on the value associated with @key on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. + * Returns: the result of calling @dup_func on the value + * associated with @key on @object, or %NULL if not set. + * If @dup_func is %NULL, the value is returned + * unmodified. * Since: 2.34 */ @@ -2055,7 +2093,10 @@ * threads are using object data on the same key on the same * object. * - * Returns: the result of calling @dup_func on the value associated with @quark on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. + * Returns: the result of calling @dup_func on the value + * associated with @quark on @object, or %NULL if not set. + * If @dup_func is %NULL, the value is returned + * unmodified. * Since: 2.34 */ @@ -2064,11 +2105,10 @@ * g_object_force_floating: * @object: a #GObject * - * 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 */ @@ -2094,7 +2134,8 @@ * g_object_get: (skip) * @object: a #GObject * @first_property_name: name of the first property to get - * @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * @...: return location for the first property, followed optionally by more + * name/return location pairs, followed by %NULL * * Gets properties of an object. * @@ -2102,12 +2143,9 @@ * 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; @@ -2122,8 +2160,7 @@ * * g_free (strval); * g_object_unref (objval); - * </programlisting> - * </example> + * ]| */ @@ -2172,7 +2209,8 @@ * g_object_get_valist: (skip) * @object: a #GObject * @first_property_name: name of the first property to get - * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * @var_args: return location for the first property, followed optionally by more + * name/return location pairs, followed by %NULL * * Gets properties of an object. * @@ -2186,7 +2224,8 @@ /** * g_object_interface_find_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface * @property_name: name of a property to lookup. * * Find the #GParamSpec with the given name for an @@ -2196,13 +2235,16 @@ * g_type_default_interface_peek(). * * Since: 2.4 - * Returns: (transfer none): the #GParamSpec for the property of the interface with the name @property_name, or %NULL if no such property exists. + * Returns: (transfer none): the #GParamSpec for the property of the + * interface with the name @property_name, or %NULL if no + * such property exists. */ /** * g_object_interface_install_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface. + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface. * @pspec: the #GParamSpec for the new property * * Add a property to an interface; this is only useful for interfaces @@ -2226,7 +2268,8 @@ /** * g_object_interface_list_properties: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface * @n_properties_p: (out): location to store number of properties returned. * * Lists the properties of an interface.Generally, the interface @@ -2235,7 +2278,11 @@ * already been loaded, g_type_default_interface_peek(). * * Since: 2.4 - * Returns: (array length=n_properties_p) (transfer container): a pointer to an array of pointers to #GParamSpec structures. The paramspecs are owned by GLib, but the array should be freed with g_free() when you are done with it. + * Returns: (array length=n_properties_p) (transfer container): a + * pointer to an array of pointers to #GParamSpec + * structures. The paramspecs are owned by GLib, but the + * array should be freed with g_free() when you are done with + * it. */ @@ -2243,8 +2290,7 @@ * g_object_is_floating: * @object: (type GObject.Object): a #GObject * - * Checks whether @object has a <link linkend="floating-ref">floating</link> - * reference. + * Checks whether @object has a [floating][floating-ref] reference. * * Since: 2.10 * Returns: %TRUE if @object has a floating reference @@ -2255,7 +2301,8 @@ * g_object_new: (skip) * @object_type: the type id of the #GObject subtype to instantiate * @first_property_name: the name of the first property - * @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL + * @...: the value of the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Creates a new instance of a #GObject subtype and sets its properties. * @@ -2270,7 +2317,8 @@ * g_object_new_valist: (skip) * @object_type: the type id of the #GObject subtype to instantiate * @first_property_name: the name of the first property - * @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL + * @var_args: the value of the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Creates a new instance of a #GObject subtype and sets its properties. * @@ -2282,7 +2330,7 @@ /** - * g_object_newv: + * g_object_newv: (rename-to g_object_new) * @object_type: the type id of the #GObject subtype to instantiate * @n_parameters: the length of the @parameters array * @parameters: (array length=n_parameters): an array of #GParameter @@ -2292,8 +2340,8 @@ * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) * which are not explicitly specified are set to their default values. * - * Rename to: g_object_new - * Returns: (type GObject.Object) (transfer full): a new instance of @object_type + * Returns: (type GObject.Object) (transfer full): a new instance of + * @object_type */ @@ -2307,6 +2355,11 @@ * When possible, eg. when signaling a property change from within the class * that registered the property, you should use g_object_notify_by_pspec() * instead. + * + * Note that emission of the notify signal may be blocked with + * g_object_freeze_notify(). In this case, the signal emissions are queued + * and will be emitted (in reverse order) when g_object_thaw_notify() is + * called. */ @@ -2325,7 +2378,7 @@ * instead, is to store the GParamSpec used with * g_object_class_install_property() inside a static array, e.g.: * - * |[ + * |[<!-- language="C" --> * enum * { * PROP_0, @@ -2350,7 +2403,7 @@ * * and then notify a change on the "foo" property with: * - * |[ + * |[<!-- language="C" --> * g_object_notify_by_pspec (self, properties[PROP_FOO]); * ]| * @@ -2373,8 +2426,7 @@ * @object: (type GObject.Object): a #GObject * * 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 @@ -2390,7 +2442,9 @@ /** * g_object_remove_toggle_ref: (skip) * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @notify: a function to call when this reference is the + * last reference to the object, or is no longer + * the last reference. * @data: data to pass to @notify * * Removes a reference added with g_object_add_toggle_ref(). The @@ -2429,14 +2483,13 @@ * * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including - * the registred destroy notify for it (passed out in @old_destroy). + * the registered destroy notify for it (passed out in @old_destroy). * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * - * Return: %TRUE if the existing value for @key was replaced + * Returns: %TRUE if the existing value for @key was replaced * by @newval, %FALSE otherwise. - * * Since: 2.34 */ @@ -2459,14 +2512,13 @@ * * If the previous value was replaced then ownership of the * old value (@oldval) is passed to the caller, including - * the registred destroy notify for it (passed out in @old_destroy). + * the registered destroy notify for it (passed out in @old_destroy). * Its up to the caller to free this as he wishes, which may * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * - * Return: %TRUE if the existing value for @quark was replaced + * Returns: %TRUE if the existing value for @quark was replaced * by @newval, %FALSE otherwise. - * * Since: 2.34 */ @@ -2486,9 +2538,14 @@ * g_object_set: (skip) * @object: a #GObject * @first_property_name: name of the first property to set - * @...: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * @...: value for the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Sets properties on an object. + * + * Note that the "notify" signals are queued and only emitted (in + * reverse order) after all properties have been set. See + * g_object_freeze_notify(). */ @@ -2553,7 +2610,8 @@ * @object: The GObject to set store a user data pointer * @quark: A #GQuark, naming the user data pointer * @data: An opaque user data pointer - * @destroy: Function to invoke with @data as argument, when @data needs to be freed + * @destroy: Function to invoke with @data as argument, when @data + * needs to be freed * * This function works like g_object_set_qdata(), but in addition, * a void (*destroy) (gpointer) function may be specified which is @@ -2567,7 +2625,8 @@ * g_object_set_valist: (skip) * @object: a #GObject * @first_property_name: name of the first property to set - * @var_args: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * @var_args: value for the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Sets properties on an object. */ @@ -2596,7 +2655,7 @@ * 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) @@ -2639,7 +2698,8 @@ * and when it reaches zero, queued "notify" signals are emitted. * * Duplicate notifications for each property are squashed so that at most one - * #GObject::notify signal is emitted for each property. + * #GObject::notify signal is emitted for each property, in the reverse order + * in which they have been queued. * * It is an error to call this function when the freeze count is zero. */ @@ -2701,7 +2761,20 @@ /** - * g_param_spec_boolean: (skip) + * g_param_get_default_value: + * @param: a #GParamSpec + * + * Gets the default value of @param as a pointer to a #GValue. + * + * The #GValue will remain value for the life of @param. + * + * Returns: a pointer to a #GValue which must not be modified + * Since: 2.38 + */ + + +/** + * g_param_spec_boolean: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2713,12 +2786,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_boxed: (skip) + * g_param_spec_boxed: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2730,12 +2803,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_char: (skip) + * g_param_spec_char: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2746,12 +2819,12 @@ * * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_double: (skip) + * g_param_spec_double: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2765,12 +2838,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_enum: (skip) + * g_param_spec_enum: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2783,12 +2856,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_flags: (skip) + * g_param_spec_flags: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2801,12 +2874,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_float: (skip) + * g_param_spec_float: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2819,7 +2892,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -2880,16 +2953,18 @@ * for an example of the use of this capability. * * Since: 2.4 - * Returns: (transfer none): paramspec to which requests on this paramspec should be redirected, or %NULL if none. + * Returns: (transfer none): paramspec to which requests on this + * paramspec should be redirected, or %NULL if none. */ /** - * g_param_spec_gtype: (skip) + * g_param_spec_gtype: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified - * @is_a_type: a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) + * @is_a_type: a #GType whose subtypes are allowed as values + * of the property (use %G_TYPE_NONE for any type) * @flags: flags for the property specified * * Creates a new #GParamSpecGType instance specifying a @@ -2898,12 +2973,12 @@ * See g_param_spec_internal() for details on property names. * * Since: 2.10 - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_int: (skip) + * g_param_spec_int: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2916,12 +2991,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_int64: (skip) + * g_param_spec_int64: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2934,7 +3009,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -2958,7 +3033,7 @@ * 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 @@ -2969,7 +3044,7 @@ /** - * g_param_spec_long: (skip) + * g_param_spec_long: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2982,12 +3057,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_object: (skip) + * g_param_spec_object: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -2999,7 +3074,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -3018,7 +3093,7 @@ /** - * g_param_spec_param: (skip) + * g_param_spec_param: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3030,12 +3105,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_pointer: (skip) + * g_param_spec_pointer: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3045,7 +3120,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -3065,10 +3140,12 @@ * @owner_type: the owner to look for * @n_pspecs_p: (out): return location for the length of the returned array * - * 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. * - * Returns: (array length=n_pspecs_p) (transfer container): a newly allocated array containing pointers to all #GParamSpecs owned by @owner_type in the pool + * Returns: (array length=n_pspecs_p) (transfer container): a newly + * allocated array containing pointers to all #GParamSpecs + * owned by @owner_type in the pool */ @@ -3077,10 +3154,12 @@ * @pool: a #GParamSpecPool * @owner_type: the owner to look for * - * 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. * - * Returns: (transfer container) (element-type GObject.ParamSpec): a #GList of all #GParamSpec<!-- -->s owned by @owner_type in the pool#GParamSpec<!-- -->s. + * Returns: (transfer container) (element-type GObject.ParamSpec): a + * #GList of all #GParamSpecs owned by @owner_type in + * the pool#GParamSpecs. */ @@ -3089,11 +3168,13 @@ * @pool: a #GParamSpecPool * @param_name: the name to look for * @owner_type: the owner to look for - * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. + * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name + * owned by an ancestor of @owner_type. * * Looks up a #GParamSpec in the pool. * - * Returns: (transfer none): The found #GParamSpec, or %NULL if no matching #GParamSpec was found. + * Returns: (transfer none): The found #GParamSpec, or %NULL if no + * matching #GParamSpec was found. */ @@ -3162,10 +3243,11 @@ * @pspec: the #GParamSpec to set store a user data pointer * @quark: a #GQuark, naming the user data pointer * @data: an opaque user data pointer - * @destroy: function to invoke with @data as argument, when @data needs to be freed + * @destroy: function to invoke with @data as argument, when @data needs to + * be freed * * 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. @@ -3179,8 +3261,8 @@ * 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). */ @@ -3201,7 +3283,7 @@ /** - * g_param_spec_string: (skip) + * g_param_spec_string: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3212,12 +3294,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_uchar: (skip) + * g_param_spec_uchar: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3228,12 +3310,12 @@ * * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_uint: (skip) + * g_param_spec_uint: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3246,12 +3328,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_uint64: (skip) + * g_param_spec_uint64: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3265,12 +3347,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_ulong: (skip) + * g_param_spec_ulong: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3284,12 +3366,12 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ /** - * g_param_spec_unichar: (skip) + * g_param_spec_unichar: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified @@ -3302,7 +3384,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: a newly created parameter specification + * Returns: (transfer full): a newly created parameter specification */ @@ -3319,7 +3401,8 @@ * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @element_spec: a #GParamSpec describing the elements contained in + * arrays of this property, may be %NULL * @flags: flags for the property specified * * Creates a new #GParamSpecValueArray instance specifying a @@ -3334,12 +3417,13 @@ /** - * g_param_spec_variant: (skip) + * g_param_spec_variant: * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified * @type: a #GVariantType - * @default_value: (allow-none): a #GVariant of type @type to use as the default value, or %NULL + * @default_value: (allow-none) (transfer full): a #GVariant of type @type to + * use as the default value, or %NULL * @flags: flags for the property specified * * Creates a new #GParamSpecVariant instance specifying a #GVariant @@ -3349,7 +3433,7 @@ * * See g_param_spec_internal() for details on property names. * - * Returns: the newly created #GParamSpec + * Returns: (transfer full): the newly created #GParamSpec * Since: 2.26 */ @@ -3373,7 +3457,8 @@ * @pspec: a valid #GParamSpec * @src_value: souce #GValue * @dest_value: destination #GValue of correct type for @pspec - * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications + * @strict_validation: %TRUE requires @dest_value to conform to @pspec + * without modifications * * Transforms @src_value into @dest_value if possible, and then * validates @dest_value, in order for it to conform to @pspec. If @@ -3383,7 +3468,8 @@ * See also g_value_type_transformable(), g_value_transform() and * g_param_value_validate(). * - * Returns: %TRUE if transformation and validation were successful, %FALSE otherwise and @dest_value is left untouched. + * Returns: %TRUE if transformation and validation were successful, + * %FALSE otherwise and @dest_value is left untouched. */ @@ -3483,8 +3569,8 @@ * 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 * Returns: standard #GSignalAccumulator result @@ -3509,7 +3595,9 @@ /** * g_signal_chain_from_overridden: - * @instance_and_params: (array): the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @instance_and_params: (array): the argument list of the signal emission. + * The first element in the array is a #GValue for the instance the signal + * is being emitted on. The rest are any arguments to be passed to the signal. * @return_value: Location for the return value. * * Calls the original class closure of a signal. This function should only @@ -3520,9 +3608,11 @@ /** - * g_signal_chain_from_overridden_handler: + * g_signal_chain_from_overridden_handler: (skip) * @instance: the instance the signal is being emitted on. - * @...: parameters to be passed to the parent class closure, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @...: parameters to be passed to the parent class closure, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Calls the original class closure of a signal. This function should * only be called from an overridden class closure; see @@ -3535,34 +3625,36 @@ /** * g_signal_connect_closure: - * @instance: the instance to connect to. + * @instance: (type GObject.Object): the instance to connect to. * @detailed_signal: a string of the form "signal-name::detail". * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * @after: whether the handler should be called before or after the + * default handler of the signal. * * Connects a closure to a signal for a particular object. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ /** * g_signal_connect_closure_by_id: - * @instance: the instance to connect to. + * @instance: (type GObject.Object): the instance to connect to. * @signal_id: the id of the signal. * @detail: the detail. * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * @after: whether the handler should be called before or after the + * default handler of the signal. * * Connects a closure to a signal for a particular object. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ /** * g_signal_connect_data: - * @instance: the instance to connect to. + * @instance: (type GObject.Object): the instance to connect to. * @detailed_signal: a string of the form "signal-name::detail". * @c_handler: the #GCallback to connect. * @data: data to pass to @c_handler calls. @@ -3572,10 +3664,10 @@ * 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. * - * Returns: the handler id + * Returns: the handler id (always greater than 0 for successful connections) */ @@ -3591,24 +3683,10 @@ * ensures that the @gobject stays alive during the call to @c_handler * by temporarily adding a reference count to @gobject. * - * Note that there is a bug in GObject that makes this function - * much less useful than it might seem otherwise. Once @gobject is - * disposed, the callback will no longer be called, but, the signal - * handler is <emphasis>not</emphasis> currently disconnected. If the - * @instance is itself being freed at the same time than this doesn't - * matter, since the signal will automatically be removed, but - * if @instance persists, then the signal handler will leak. You - * should not remove the signal yourself because in a future versions of - * GObject, the handler <emphasis>will</emphasis> automatically - * be disconnected. - * - * It's possible to work around this problem in a way that will - * continue to work with future versions of GObject by checking - * that the signal handler is still connected before disconnected it: - * <informalexample><programlisting> - * if (g_signal_handler_is_connected (instance, id)) - * g_signal_handler_disconnect (instance, id); - * </programlisting></informalexample> + * When the @gobject is destroyed the signal handler will be automatically + * disconnected. Note that this is not currently threadsafe (ie: + * emitting a signal while @gobject is being destroyed in another thread + * is not safe). * * Returns: the handler id. */ @@ -3616,10 +3694,12 @@ /** * g_signal_emit: - * @instance: the instance the signal is being emitted on. + * @instance: (type GObject.Object): the instance the signal is being emitted on. * @signal_id: the signal id * @detail: the detail - * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @...: parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Emits a signal. * @@ -3630,9 +3710,11 @@ /** * g_signal_emit_by_name: - * @instance: the instance the signal is being emitted on. + * @instance: (type GObject.Object): the instance the signal is being emitted on. * @detailed_signal: a string of the form "signal-name::detail". - * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @...: parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Emits a signal. * @@ -3642,11 +3724,13 @@ /** - * g_signal_emit_valist: + * g_signal_emit_valist: (skip) * @instance: the instance the signal is being emitted on. * @signal_id: the signal id * @detail: the detail - * @var_args: a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @var_args: a list of parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Emits a signal. * @@ -3657,7 +3741,9 @@ /** * g_signal_emitv: - * @instance_and_params: (array): argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @instance_and_params: (array): argument list for the signal emission. + * The first element in the array is a #GValue for the instance the signal + * is being emitted on. The rest are any arguments to be passed to the signal. * @signal_id: the signal id * @detail: the detail * @return_value: Location to store the return value of the signal emission. @@ -3671,7 +3757,7 @@ /** * g_signal_get_invocation_hint: - * @instance: the instance to query + * @instance: (type GObject.Object): the instance to query * * Returns the invocation hint of the innermost signal emission of instance. * @@ -3681,7 +3767,7 @@ /** * g_signal_handler_block: - * @instance: The instance to block the signal handler of. + * @instance: (type GObject.Object): The instance to block the signal handler of. * @handler_id: Handler id of the handler to be blocked. * * Blocks a handler of an instance so it will not be called during any @@ -3697,7 +3783,7 @@ /** * g_signal_handler_disconnect: - * @instance: The instance to remove the signal handler from. + * @instance: (type GObject.Object): The instance to remove the signal handler from. * @handler_id: Handler id of the handler to be disconnected. * * Disconnects a handler from an instance so it will not be called during @@ -3711,8 +3797,9 @@ /** * g_signal_handler_find: - * @instance: The instance owning the signal handler to be found. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. + * @instance: (type GObject.Object): The instance owning the signal handler to be found. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handler has to match. * @signal_id: Signal the handler has to be connected to. * @detail: Signal detail the handler has to be connected to. * @closure: (allow-none): The closure the handler will invoke. @@ -3731,7 +3818,7 @@ /** * g_signal_handler_is_connected: - * @instance: The instance where a signal handler is sought. + * @instance: (type GObject.Object): The instance where a signal handler is sought. * @handler_id: the handler id. * * Returns whether @handler_id is the id of a handler connected to @instance. @@ -3742,7 +3829,7 @@ /** * g_signal_handler_unblock: - * @instance: The instance to unblock the signal handler of. + * @instance: (type GObject.Object): The instance to unblock the signal handler of. * @handler_id: Handler id of the handler to be unblocked. * * Undoes the effect of a previous g_signal_handler_block() call. A @@ -3763,8 +3850,9 @@ /** * g_signal_handlers_block_matched: - * @instance: The instance to block handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @instance: (type GObject.Object): The instance to block handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: (allow-none): The closure the handlers will invoke. @@ -3784,9 +3872,16 @@ /** + * g_signal_handlers_destroy: + * @instance: (type GObject.Object): The instance where a signal handler is sought. + */ + + +/** * g_signal_handlers_disconnect_matched: - * @instance: The instance to remove handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @instance: (type GObject.Object): The instance to remove handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: (allow-none): The closure the handlers will invoke. @@ -3808,8 +3903,9 @@ /** * g_signal_handlers_unblock_matched: - * @instance: The instance to unblock handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @instance: (type GObject.Object): The instance to unblock handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: (allow-none): The closure the handlers will invoke. @@ -3831,7 +3927,7 @@ /** * g_signal_has_handler_pending: - * @instance: the object whose signal handlers are sought. + * @instance: (type GObject.Object): the object whose signal handlers are sought. * @signal_id: the signal id. * @detail: the detail. * @may_be_blocked: whether blocked handlers should count as match. @@ -3844,7 +3940,8 @@ * emit the signal if no one is attached anyway, thus saving the cost * of building the arguments. * - * Returns: %TRUE if a handler is connected to the signal, %FALSE otherwise. + * Returns: %TRUE if a handler is connected to the signal, %FALSE + * otherwise. */ @@ -3893,13 +3990,20 @@ /** * g_signal_new: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_offset: The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_offset: The offset of the function pointer in the class structure + * for this type. Used to invoke a class method generically. Pass 0 to + * not associate a class method slot with this signal. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @c_marshaller: (allow-none): the function to translate arrays of parameter + * values to signal emissions into C language callback invocations or %NULL. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. * @n_params: the number of parameter types to follow. * @...: a list of types, one for each parameter. * @@ -3914,9 +4018,8 @@ * 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. @@ -3928,13 +4031,20 @@ /** * g_signal_new_class_handler: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_handler: a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_handler: a #GCallback which acts as class implementation of + * this signal. Used to invoke a class method generically. Pass %NULL to + * not associate a class method with this signal. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @c_marshaller: (allow-none): the function to translate arrays of parameter + * values to signal emissions into C language callback invocations or %NULL. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. * @n_params: the number of parameter types to follow. * @...: a list of types, one for each parameter. * @@ -3963,13 +4073,18 @@ /** * g_signal_new_valist: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * @class_closure: The closure to invoke on signal emission; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @c_marshaller: (allow-none): the function to translate arrays of parameter + * values to signal emissions into C language callback invocations or %NULL. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. * @n_params: the number of parameter types in @args. * @args: va_list of #GType, one for each parameter. * @@ -3987,15 +4102,23 @@ /** * g_signal_newv: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - * @class_closure: (allow-none): The closure to invoke on signal emission; may be %NULL + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST + * @class_closure: (allow-none): The closure to invoke on signal emission; + * may be %NULL * @accumulator: (allow-none): the accumulator for this signal; may be %NULL * @accu_data: user data for the @accumulator - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value + * @c_marshaller: (allow-none): the function to translate arrays of + * parameter values to signal emissions into C language callback + * invocations or %NULL + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value * @n_params: the length of @param_types - * @param_types: (array length=n_params): an array of types, one for each parameter + * @param_types: (array length=n_params): an array of types, one for + * each parameter * * Creates a new signal. (This is usually done in the class initializer.) * @@ -4011,7 +4134,8 @@ /** * g_signal_override_class_closure: * @signal_id: the signal id - * @instance_type: the instance type on which to override the class closure for the signal. + * @instance_type: the instance type on which to override the class closure + * for the signal. * @class_closure: the closure. * * Overrides the class closure (i.e. the default handler) for the given signal @@ -4027,12 +4151,13 @@ /** * g_signal_override_class_handler: * @signal_name: the name for the signal - * @instance_type: the instance type on which to override the class handler for the signal. + * @instance_type: the instance type on which to override the class handler + * for the signal. * @class_handler: the handler. * * Overrides the class closure (i.e. the default handler) for the * given signal for emissions on instances of @instance_type with - * callabck @class_handler. @instance_type must be derived from the + * callback @class_handler. @instance_type must be derived from the * type to which the signal belongs. * * See g_signal_chain_from_overridden() and @@ -4061,7 +4186,8 @@ /** * g_signal_query: * @signal_id: The signal id of the signal to query information for. - * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. + * @query: (out caller-allocates): A user provided structure that is + * filled in with constant values upon success. * * Queries the signal system for in-depth information about a * specific signal. This function will fill in a user-provided @@ -4075,7 +4201,8 @@ /** * g_signal_remove_emission_hook: * @signal_id: the id of the signal - * @hook_id: the id of the emission hook, as returned by g_signal_add_emission_hook() + * @hook_id: the id of the emission hook, as returned by + * g_signal_add_emission_hook() * * Deletes an emission hook. */ @@ -4083,7 +4210,7 @@ /** * g_signal_stop_emission: - * @instance: the object whose signal handlers you wish to stop. + * @instance: (type GObject.Object): the object whose signal handlers you wish to stop. * @signal_id: the signal identifier, as returned by g_signal_lookup(). * @detail: the detail which the signal was emitted with. * @@ -4099,7 +4226,7 @@ /** * g_signal_stop_emission_by_name: - * @instance: the object whose signal handlers you wish to stop. + * @instance: (type GObject.Object): the object whose signal handlers you wish to stop. * @detailed_signal: a string of the form "signal-name::detail". * * Stops a signal's current emission. @@ -4112,7 +4239,8 @@ /** * g_signal_type_cclosure_new: * @itype: the #GType identifier of an interface or classed type - * @struct_offset: the offset of the member function of @itype's class structure which is to be invoked by the new closure + * @struct_offset: the offset of the member function of @itype's class + * structure which is to be invoked by the new closure * * Creates a new closure which invokes the function found at the offset * @struct_offset in the class structure of the interface or classed type @@ -4182,8 +4310,8 @@ /** * g_type_add_class_private: - * @class_type: GType of an classed type. - * @private_size: size of private structure. + * @class_type: GType of an classed type + * @private_size: size of private structure * * Registers a private class structure for a classed type; * when the class is allocated, the private structures for @@ -4201,14 +4329,15 @@ /** * g_type_add_interface_check: (skip) * @check_data: data to pass to @check_func - * @check_func: function to be called after each interface is initialized. + * @check_func: function to be called after each interface + * is initialized * * 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. @@ -4219,9 +4348,9 @@ /** * g_type_add_interface_dynamic: - * @instance_type: the #GType value of an instantiable type. - * @interface_type: the #GType value of an interface type. - * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. + * @instance_type: #GType value of an instantiable type + * @interface_type: #GType value of an interface type + * @plugin: #GTypePlugin structure to retrieve the #GInterfaceInfo from * * Adds the dynamic @interface_type to @instantiable_type. The information * contained in the #GTypePlugin structure pointed to by @plugin @@ -4231,43 +4360,46 @@ /** * g_type_add_interface_static: - * @instance_type: #GType value of an instantiable type. - * @interface_type: #GType value of an interface type. - * @info: The #GInterfaceInfo structure for this (@instance_type, @interface_type) combination. + * @instance_type: #GType value of an instantiable type + * @interface_type: #GType value of an interface type + * @info: #GInterfaceInfo structure for this + * (@instance_type, @interface_type) combination * - * 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. */ /** * g_type_check_instance: - * @instance: A valid #GTypeInstance structure. + * @instance: a valid #GTypeInstance structure * - * 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. * - * Returns: %TRUE if @instance is valid, %FALSE otherwise. + * Returns: %TRUE if @instance is valid, %FALSE otherwise */ /** * g_type_children: - * @type: The parent type. - * @n_children: (out) (allow-none): Optional #guint pointer to contain the number of child types. + * @type: the parent type + * @n_children: (out) (allow-none): location to store the length of + * the returned array, or %NULL * - * 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. * - * Returns: (array length=n_children) (transfer full): Newly allocated and 0-terminated array of child types. + * Returns: (array length=n_children) (transfer full): Newly allocated + * and 0-terminated array of child types, free with g_free() */ /** * g_type_class_add_private: * @g_class: class structure for an instantiatable type - * @private_size: size of private structure. + * @private_size: size of private structure * * Registers a private structure for an instantiatable type. * @@ -4277,21 +4409,20 @@ * structures. * * Note that the accumulated size of the private structures of - * a type and all its parent types cannot excced 64 KiB. + * a type and all its parent types cannot exceed 64 KiB. * * This function should be called in the type's class_init() function. * 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; * @@ -4337,64 +4468,88 @@ /** + * g_type_class_get_instance_private_offset: (skip) + * @g_class: a #GTypeClass + * + * Gets the offset of the private data for instances of @g_class. + * + * This is how many bytes you should add to the instance pointer of a + * class in order to get the private data for the type represented by + * @g_class. + * + * You can only call this function after you have registered a private + * data area for @g_class using g_type_class_add_private(). + * + * Returns: the offset, in bytes + * Since: 2.38 + */ + + +/** * g_type_class_peek: - * @type: Type ID of a classed type. + * @type: type ID of a classed type * - * 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). * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist. + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist */ /** * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to retrieve the parent class for. + * @g_class: (type GObject.TypeClass): the #GTypeClass structure to + * retrieve the parent class for * * 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))) * - * Returns: (type GObject.TypeClass) (transfer none): The parent class of @g_class. + * Returns: (type GObject.TypeClass) (transfer none): the parent class + * of @g_class */ /** * g_type_class_peek_static: - * @type: Type ID of a classed type. + * @type: type ID of a classed type * * A more efficient version of g_type_class_peek() which works only for * static types. * + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist or is dynamically loaded * Since: 2.4 - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded. */ /** * g_type_class_ref: - * @type: Type ID of a classed type. + * @type: type ID of a classed type * * Increments the reference count of the class structure belonging to * @type. This function will demand-create the class if it doesn't * exist already. * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID. + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID */ /** * g_type_class_unref: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref * * Decrements the reference count of the class structure being passed in. * Once the last reference count of a class has been released, classes @@ -4405,18 +4560,18 @@ /** * g_type_class_unref_uncached: (skip) - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref * * 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. */ /** * g_type_create_instance: (skip) - * @type: An instantiatable type to create an instance for. + * @type: an instantiatable type to create an instance for * * Creates and initializes an instance of @type if @type is valid and * can be instantiated. The type system only performs basic allocation @@ -4424,15 +4579,16 @@ * 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. * - * Returns: An allocated and initialized instance, subject to further treatment by the fundamental type implementation. + * 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. + * + * Returns: an allocated and initialized instance, subject to further + * treatment by the fundamental type implementation */ @@ -4444,7 +4600,9 @@ * default interface vtable. * * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default vtable for the interface, or %NULL if the type is not currently in use. + * Returns: (type GObject.TypeInterface) (transfer none): the default + * vtable for the interface, or %NULL if the type is not currently + * in use */ @@ -4458,27 +4616,28 @@ * 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. * * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default vtable for the interface; call g_type_default_interface_unref() when you are done using the interface. + * Returns: (type GObject.TypeInterface) (transfer none): the default + * vtable for the interface; call g_type_default_interface_unref() + * when you are done using the interface. */ /** * g_type_default_interface_unref: - * @g_iface: (type GObject.TypeInterface): the default vtable structure for a interface, as returned by g_type_default_interface_ref() + * @g_iface: (type GObject.TypeInterface): the default vtable + * structure for a interface, as returned by g_type_default_interface_ref() * * 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 */ @@ -4486,18 +4645,18 @@ /** * g_type_depth: - * @type: A #GType value. + * @type: a #GType * * Returns the length of the ancestry of the passed in type. This * includes the type itself, so that e.g. a fundamental type has depth 1. * - * Returns: The depth of @type. + * Returns: the depth of @type */ /** * g_type_ensure: - * @type: a #GType. + * @type: a #GType * * Ensures that the indicated @type has been registered with the * type system, and its _class_init() method has been run. @@ -4518,7 +4677,7 @@ /** * g_type_free_instance: - * @instance: an instance of a type. + * @instance: an instance of a type * * Frees an instance of a type, returning it to the instance pool for * the type, if there is one. @@ -4530,14 +4689,14 @@ /** * g_type_from_name: - * @name: Type name to lookup. + * @name: type name to lookup * * Lookup the type ID from a given type name, returning 0 if no type * has been registered under this name (this is the preferred method * to find out by name whether a specific type has been registered * yet). * - * Returns: Corresponding type ID or 0. + * Returns: corresponding type ID or 0 */ @@ -4546,7 +4705,7 @@ * @type_id: valid type ID * * Internal function, used to extract the fundamental type ID portion. - * use G_TYPE_FUNDAMENTAL() instead. + * Use G_TYPE_FUNDAMENTAL() instead. * * Returns: fundamental type ID */ @@ -4560,18 +4719,19 @@ * The returned type ID represents the highest currently registered * fundamental type identifier. * - * Returns: The nextmost fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs. + * Returns: the next available fundamental type ID to be registered, + * or 0 if the type system ran out of fundamental type IDs */ /** * g_type_get_plugin: - * @type: The #GType to retrieve the plugin for. + * @type: #GType to retrieve the plugin for * - * Returns the #GTypePlugin structure for @type or - * %NULL if @type does not have a #GTypePlugin structure. + * Returns the #GTypePlugin structure for @type. * - * Returns: (transfer none): The corresponding plugin if @type is a dynamic type, %NULL otherwise. + * Returns: (transfer none): the corresponding plugin + * if @type is a dynamic type, %NULL otherwise */ @@ -4592,36 +4752,50 @@ /** - * g_type_init: + * g_type_get_type_registration_serial: * - * Prior to any use of the type system, g_type_init() has to be called - * to initialize the type system and assorted other code portions - * (such as the various fundamental type implementations or the signal - * system). + * 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. * - * This function is idempotent: If you call it multiple times, all but - * the first calls will be silently ignored. + * Since: 2.36 + * Returns: An unsigned int, representing the state of type registrations + */ + + +/** + * g_type_init: * - * There is no way to undo the effect of g_type_init(). + * This function used to initialise the type system. Since GLib 2.36, + * the type system is initialised automatically and this function does + * nothing. * - * Since version 2.24 this also initializes the thread system + * Deprecated: 2.36: the type system is now initialised automatically */ /** * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. + * @debug_flags: bitwise combination of #GTypeDebugFlags values for + * debugging purposes + * + * This function used to initialise the type system with debugging + * flags. Since GLib 2.36, the type system is initialised automatically + * and this function does nothing. * - * Similar to g_type_init(), but additionally sets debug flags. + * If you need to enable debugging features, use the GOBJECT_DEBUG + * environment variable. * - * This function is idempotent. + * Deprecated: 2.36: the type system is now initialised automatically */ /** * g_type_interface_add_prerequisite: - * @interface_type: #GType value of an interface type. - * @prerequisite_type: #GType value of an interface or instantiatable type. + * @interface_type: #GType value of an interface type + * @prerequisite_type: #GType value of an interface or instantiatable type * * Adds @prerequisite_type to the list of prerequisites of @interface_type. * This means that any type implementing @interface_type must also implement @@ -4633,78 +4807,89 @@ /** * g_type_interface_get_plugin: - * @instance_type: the #GType value of an instantiatable type. - * @interface_type: the #GType value of an interface type. + * @instance_type: #GType of an instantiatable type + * @interface_type: #GType of an interface type * * 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(). * - * Returns: (transfer none): the #GTypePlugin for the dynamic interface @interface_type of @instance_type. + * Returns: (transfer none): the #GTypePlugin for the dynamic + * interface @interface_type of @instance_type */ /** * g_type_interface_peek: - * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. - * @iface_type: An interface ID which this class conforms to. + * @instance_class: (type GObject.TypeClass): a #GTypeClass structure + * @iface_type: an interface ID which this class conforms to * * Returns the #GTypeInterface structure of an interface to which the * passed in class conforms. * - * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface structure of iface_type if implemented by @instance_class, %NULL otherwise + * Returns: (type GObject.TypeInterface) (transfer none): the #GTypeInterface + * structure of @iface_type if implemented by @instance_class, %NULL + * otherwise */ /** * g_type_interface_peek_parent: - * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. + * @g_iface: (type GObject.TypeInterface): a #GTypeInterface structure * * Returns the corresponding #GTypeInterface structure of the parent type * of the instance type to which @g_iface belongs. This is useful when * deriving the implementation of an interface from the parent type and * then possibly overriding some methods. * - * Returns: (transfer none) (type GObject.TypeInterface): 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. + * Returns: (transfer none) (type GObject.TypeInterface): 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 */ /** * g_type_interface_prerequisites: * @interface_type: an interface type - * @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL + * @n_prerequisites: (out) (allow-none): location to return the number + * of prerequisites, or %NULL * * Returns the prerequisites of an interfaces type. * * Since: 2.2 - * Returns: (array length=n_prerequisites) (transfer full): a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type + * Returns: (array length=n_prerequisites) (transfer full): a + * newly-allocated zero-terminated array of #GType containing + * the prerequisites of @interface_type */ /** * g_type_interfaces: - * @type: The type to list interface types for. - * @n_interfaces: (out) (allow-none): Optional #guint pointer to contain the number of interface types. + * @type: the type to list interface types for + * @n_interfaces: (out) (allow-none): location to store the length of + * the returned array, or %NULL * - * 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. * - * Returns: (array length=n_interfaces) (transfer full): Newly allocated and 0-terminated array of interface types. + * Returns: (array length=n_interfaces) (transfer full): Newly allocated + * and 0-terminated array of interface types, free with g_free() */ /** * g_type_is_a: - * @type: Type to check anchestry for. - * @is_a_type: Possible anchestor of @type or interface @type could conform to. + * @type: type to check anchestry for + * @is_a_type: possible anchestor of @type or interface that @type + * could conform to * * 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. * - * Returns: %TRUE if @type is_a @is_a_type holds true. + * Returns: %TRUE if @type is a @is_a_type */ @@ -4728,7 +4913,10 @@ * g_type_module_register_enum: * @module: a #GTypeModule * @name: name for the type - * @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * @const_static_values: an array of #GEnumValue structs for the + * possible enumeration values. The array is + * terminated by a struct with all members being + * 0. * * Looks up or registers an enumeration that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, @@ -4747,7 +4935,10 @@ * g_type_module_register_flags: * @module: a #GTypeModule * @name: name for the type - * @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. + * @const_static_values: an array of #GFlagsValue structs for the + * possible flags values. The array is + * terminated by a struct with all members being + * 0. * * Looks up or registers a flags type that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, @@ -4816,13 +5007,14 @@ * If loading the plugin fails, the use count is reset to * its prior value. * - * Returns: %FALSE if the plugin needed to be loaded and loading the plugin failed. + * Returns: %FALSE if the plugin needed to be loaded and + * loading the plugin failed. */ /** * g_type_name: - * @type: Type to return name for. + * @type: type to return name for * * Get the unique name that is assigned to a type ID. Note that this * function (like all other GType API) cannot cope with invalid type @@ -4830,42 +5022,43 @@ * other validly registered type ID, but randomized type IDs should * not be passed in and will most likely lead to a crash. * - * Returns: Static type name or %NULL. + * Returns: static type name or %NULL */ /** * g_type_next_base: - * @leaf_type: Descendant of @root_type and the type to be returned. - * @root_type: Immediate parent of the returned type. + * @leaf_type: descendant of @root_type and the type to be returned + * @root_type: immediate parent of the returned type * * 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 * descended from the root type. * - * Returns: Immediate child of @root_type and anchestor of @leaf_type. + * Returns: immediate child of @root_type and anchestor of @leaf_type */ /** * g_type_parent: - * @type: The derived type. + * @type: the derived type * - * 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. * - * Returns: The parent type. + * Returns: the parent type */ /** * g_type_plugin_complete_interface_info: * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added + * @instance_type: the #GType of an instantiable type to which the interface + * is added * @interface_type: the #GType of the interface whose info is completed * @info: the #GInterfaceInfo to fill in * @@ -4910,18 +5103,19 @@ /** * g_type_qname: - * @type: Type to return quark of type name for. + * @type: type to return quark of type name for * * Get the corresponding quark of the type IDs name. * - * Returns: The type names quark or 0. + * Returns: the type names quark or 0 */ /** * g_type_query: - * @type: the #GType value of a static, classed type. - * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. + * @type: #GType of a static, classed type + * @query: (out caller-allocates): a user provided structure that is + * filled in with constant values upon success * * Queries the type system for information about a specific type. * This function will fill in a user-provided structure to hold @@ -4934,10 +5128,10 @@ /** * g_type_register_dynamic: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from. - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @plugin: #GTypePlugin structure to retrieve the #GTypeInfo from + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new dynamic type derived from * @parent_type. The type system uses the information contained in the @@ -4945,56 +5139,56 @@ * instances (if not abstract). The value of @flags determines the nature * (e.g. abstract or not) of the type. * - * Returns: The new type identifier or #G_TYPE_INVALID if registration failed. + * Returns: the new type identifier or #G_TYPE_INVALID if registration failed */ /** * g_type_register_fundamental: - * @type_id: A predefined type identifier. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @finfo: The #GTypeFundamentalInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * @type_id: a predefined type identifier + * @type_name: 0-terminated string used as the name of the new type + * @info: #GTypeInfo structure for this type + * @finfo: #GTypeFundamentalInfo structure for this type + * @flags: bitwise combination of #GTypeFlags values * * 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. * - * Returns: The predefined type identifier. + * Returns: the predefined type identifier */ /** * g_type_register_static: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @info: #GTypeInfo structure for this type + * @flags: bitwise combination of #GTypeFlags values * * 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. * - * Returns: The new type identifier. + * Returns: the new type identifier */ /** * g_type_register_static_simple: (skip) - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @class_size: Size of the class structure (see #GTypeInfo) - * @class_init: Location of the class initialization function (see #GTypeInfo) - * @instance_size: Size of the instance structure (see #GTypeInfo) - * @instance_init: Location of the instance initialization function (see #GTypeInfo) - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @class_size: size of the class structure (see #GTypeInfo) + * @class_init: location of the class initialization function (see #GTypeInfo) + * @instance_size: size of the instance structure (see #GTypeInfo) + * @instance_init: location of the instance initialization function (see #GTypeInfo) + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new static type derived from * @parent_type. The value of @flags determines the nature (e.g. @@ -5002,7 +5196,7 @@ * struct and calling g_type_register_static(). * * Since: 2.12 - * Returns: The new type identifier. + * Returns: the new type identifier */ @@ -5041,14 +5235,16 @@ /** * g_type_value_table_peek: (skip) - * @type: A #GType value. + * @type: a #GType * * 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. * - * Returns: Location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type. + * Returns: location of the #GTypeValueTable associated with @type or + * %NULL if there is no #GTypeValueTable associated with @type */ @@ -5102,7 +5298,7 @@ /** * g_value_array_insert: * @value_array: #GValueArray to add an element to - * @index_: insertion position, must be <= value_array->n_values + * @index_: insertion position, must be <= value_array->n_values * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * * Insert a copy of @value at specified position into @value_array. If @value @@ -5142,7 +5338,8 @@ /** * g_value_array_remove: * @value_array: #GValueArray to remove an element from - * @index_: position of value to remove, which must be less than <code>value_array-><link linkend="GValueArray.n-values">n_values</link></code> + * @index_: position of value to remove, which must be less than + * @value_array->n_values * * Remove the value at position @index_ from @value_array. * @@ -5159,7 +5356,8 @@ * Sort @value_array using @compare_func to compare the elements according to * the semantics of #GCompareFunc. * - * The current implementation uses Quick-Sort as sorting algorithm. + * The current implementation uses the same sorting algorithm as standard + * C qsort() function. * * Returns: (transfer none): the #GValueArray passed in as @value_array * Deprecated: 2.32: Use #GArray and g_array_sort(). @@ -5167,7 +5365,7 @@ /** - * g_value_array_sort_with_data: + * g_value_array_sort_with_data: (rename-to g_value_array_sort) * @value_array: #GValueArray to sort * @compare_func: (scope call): function to compare elements * @user_data: (closure): extra data argument provided for @compare_func @@ -5175,9 +5373,9 @@ * Sort @value_array using @compare_func to compare the elements according * to the semantics of #GCompareDataFunc. * - * The current implementation uses Quick-Sort as sorting algorithm. + * The current implementation uses the same sorting algorithm as standard + * C qsort() function. * - * Rename to: g_value_array_sort * Returns: (transfer none): the #GValueArray passed in as @value_array * Deprecated: 2.32: Use #GArray and g_array_sort_with_data(). */ @@ -5213,7 +5411,8 @@ * its reference count. If the contents of the #GValue are %NULL, then * %NULL will be returned. * - * Returns: (type GObject.Object) (transfer full): object content of @value, should be unreferenced when no longer needed. + * Returns: (type GObject.Object) (transfer full): object content of @value, + * should be unreferenced when no longer needed. */ @@ -5224,7 +5423,8 @@ * Get the contents of a %G_TYPE_PARAM #GValue, increasing its * reference count. * - * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed. + * Returns: #GParamSpec content of @value, should be unreferenced when + * no longer needed. */ @@ -5244,7 +5444,8 @@ * * Get the contents of a variant #GValue, increasing its refcount. * - * Returns: variant contents of @value, should be unrefed using g_variant_unref() when no longer needed + * Returns: variant contents of @value, should be unrefed using + * g_variant_unref() when no longer needed * Since: 2.26 */ @@ -5492,9 +5693,10 @@ * g_value_peek_pointer: * @value: An initialized #GValue structure. * - * - * - * Returns: (transfer none): the value contents as pointer. This function asserts that g_value_fits_pointer() returned %TRUE for the passed in value. This is an internal function introduced mainly for C marshallers. + * Returns: (transfer none): the value contents as pointer. This + * function asserts that g_value_fits_pointer() returned %TRUE for the + * passed in value. This is an internal function introduced mainly + * for C marshallers. */ @@ -5502,7 +5704,8 @@ * g_value_register_transform_func: (skip) * @src_type: Source type. * @dest_type: Target type. - * @transform_func: a function which transforms values of type @src_type into value of type @dest_type + * @transform_func: a function which transforms values of type @src_type + * into value of type @dest_type * * Registers a value transformation function for use in g_value_transform(). * A previously registered transformation function for @src_type and @dest_type @@ -5894,7 +6097,8 @@ * results and shouldn't be relied upon for production code (such * as rcfile value or object property serialization). * - * Returns: Whether a transformation rule was found and could be applied. Upon failing transformations, @dest_value is left untouched. + * Returns: Whether a transformation rule was found and could be applied. + * Upon failing transformations, @dest_value is left untouched. */ @@ -5916,7 +6120,9 @@ * @dest_type: Target type. * * 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. * * Returns: %TRUE if the transformation is possible, %FALSE otherwise. */ @@ -5936,8 +6142,6 @@ /** * g_variant_get_gtype: * - * - * * Since: 2.24 * Deprecated: 2.26 */ @@ -5945,7 +6149,8 @@ /** * g_weak_ref_clear: (skip) - * @weak_ref: (inout): location of a weak reference, which may be empty + * @weak_ref: (inout): location of a weak reference, which + * may be empty * * Frees resources associated with a non-statically-allocated #GWeakRef. * After this call, the #GWeakRef is left in an undefined state. @@ -5971,14 +6176,16 @@ * The caller should release the resulting reference in the usual way, * by using g_object_unref(). * - * Returns: (transfer full) (type GObject.Object): the object pointed to by @weak_ref, or %NULL if it was empty + * Returns: (transfer full) (type GObject.Object): the object pointed to + * by @weak_ref, or %NULL if it was empty * Since: 2.32 */ /** * g_weak_ref_init: (skip) - * @weak_ref: (inout): uninitialized or empty location for a weak reference + * @weak_ref: (inout): uninitialized or empty location for a weak + * reference * @object: (allow-none): a #GObject or %NULL * * Initialise a non-statically-allocated #GWeakRef. diff --git a/gir/win32-1.0.gir b/gir/win32-1.0.gir new file mode 100644 index 00000000..ac9db850 --- /dev/null +++ b/gir/win32-1.0.gir @@ -0,0 +1,19 @@ +<?xml version="1.0"?> +<repository version="1.2" + xmlns="http://www.gtk.org/introspection/core/1.0" + xmlns:c="http://www.gtk.org/introspection/c/1.0"> + <namespace name="win32" version="1.0" + c:identifier-prefixes="" + c:symbol-prefixes="Win32"> + <alias name="HWND" c:type="HWND"> + <type name="guint" c:type="guint"/> + </alias> + <alias name="HICON" c:type="HICON"> + <type name="gulong" c:type="gulong"/> + </alias> + <alias name="HGDIOBJ" c:type="HGDIOBJ"> + <type name="gulong" c:type="gulong"/> + </alias> + </namespace> +</repository> + |