diff options
| -rw-r--r-- | gir/gio-2.0.c | 788 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 1036 | ||||
| -rw-r--r-- | gir/gmodule-2.0.c | 28 | ||||
| -rw-r--r-- | gir/gobject-2.0.c | 267 |
4 files changed, 1594 insertions, 525 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index c1ffdd09..eec568cf 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -746,6 +746,15 @@ * of the other peer here after the connection has been successfully * initialized. * + * Note that the + * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) + * uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the + * term ‘GUID’ for historical reasons. + * + * Despite its name, the format of #GDBusConnection:guid does not follow + * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft + * GUID format. + * * Since: 2.26 */ @@ -1426,7 +1435,9 @@ /** * GDBusServer:guid: * - * The guid of the server. + * The GUID of the server. + * + * See #GDBusConnection:guid for more details. * * Since: 2.26 */ @@ -1443,27 +1454,27 @@ /** - * GDataOutputStream:byte-order: + * GDataInputStream:byte-order: * - * Determines the byte ordering that is used when writing - * multi-byte entities (such as integers) to the stream. + * The :byte-order property determines the byte ordering that + * is used when reading multi-byte entities (such as integers) + * from the stream. */ /** - * GDataStream:byte-order: + * GDataInputStream:newline-type: * - * The ::byte-order property determines the byte ordering that - * is used when reading multi-byte entities (such as integers) - * from the stream. + * The :newline-type property determines what is considered + * as a line ending when reading complete lines from the stream. */ /** - * GDataStream:newline-type: + * GDataOutputStream:byte-order: * - * The :newline-type property determines what is considered - * as a line ending when reading complete lines from the stream. + * Determines the byte ordering that is used when writing + * multi-byte entities (such as integers) to the stream. */ @@ -1680,6 +1691,15 @@ /** + * GDtlsConnection:ciphersuite-name: (nullable) + * + * The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). + * + * Since: 2.70 + */ + + +/** * GDtlsConnection:database: (nullable) * * The certificate database to use when verifying this TLS connection. @@ -1740,6 +1760,15 @@ /** + * GDtlsConnection:protocol-version: + * + * The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). + * + * Since: 2.70 + */ + + +/** * GDtlsConnection:rehandshake-mode: * * The rehandshaking mode. See @@ -2654,6 +2683,35 @@ /** + * GPowerProfileMonitor: + * + * #GPowerProfileMonitor monitors system power profile and notifies on + * changes. + * + * Since: 2.70 + */ + + +/** + * GPowerProfileMonitor:power-saver-enabled: + * + * Whether “Power Saver” mode is enabled on the system. + * + * Since: 2.70 + */ + + +/** + * GPowerProfileMonitorInterface: + * @g_iface: The parent interface. + * + * The virtual function table for #GPowerProfileMonitor. + * + * Since: 2.70 + */ + + +/** * GPropertyAction: * * This type is opaque. @@ -3615,6 +3673,26 @@ /** + * GTlsCertificate:dns-names: (nullable) (element-type GBytes) (transfer container) + * + * The DNS names from the certificate's Subject Alternative Names (SANs), + * %NULL if unavailable. + * + * Since: 2.70 + */ + + +/** + * GTlsCertificate:ip-addresses: (nullable) (element-type GInetAddress) (transfer container) + * + * The IP addresses from the certificate's Subject Alternative Names (SANs), + * %NULL if unavailable. + * + * Since: 2.70 + */ + + +/** * GTlsCertificate:issuer: * * A #GTlsCertificate representing the entity that issued this @@ -3622,17 +3700,59 @@ * self-signed, or else the certificate of the issuer is not * available. * + * Beware the issuer certificate may not be the same as the + * certificate that would actually be used to construct a valid + * certification path during certificate verification. + * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains + * why an issuer certificate cannot be naively assumed to be part of the + * the certification path (though GLib's TLS backends may not follow the + * path building strategies outlined in this RFC). Due to the complexity + * of certification path building, GLib does not provide any way to know + * which certification path will actually be used. Accordingly, this + * property cannot be used to make security-related decisions. Only + * GLib itself should make security decisions about TLS certificates. + * * Since: 2.28 */ /** + * GTlsCertificate:issuer-name: (nullable) + * + * The issuer from the certificate, + * %NULL if unavailable. + * + * Since: 2.70 + */ + + +/** + * GTlsCertificate:not-valid-after: (nullable) + * + * The time at which this cert is no longer valid, + * %NULL if unavailable. + * + * Since: 2.70 + */ + + +/** + * GTlsCertificate:not-valid-before: (nullable) + * + * The time at which this cert is considered to be valid, + * %NULL if unavailable. + * + * Since: 2.70 + */ + + +/** * GTlsCertificate:pkcs11-uri: (nullable) * - * A URI referencing the PKCS \#11 objects containing an X.509 certificate - * and optionally a private key. + * A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) + * objects containing an X.509 certificate and optionally a private key. * - * If %NULL the certificate is either not backed by PKCS \#11 or the + * If %NULL, the certificate is either not backed by PKCS \#11 or the * #GTlsBackend does not support PKCS \#11. * * Since: 2.68 @@ -3640,35 +3760,51 @@ /** - * GTlsCertificate:private-key: + * GTlsCertificate:private-key: (nullable) * * The DER (binary) encoded representation of the certificate's - * private key, in either PKCS#1 format or unencrypted PKCS#8 - * format. This property (or the #GTlsCertificate:private-key-pem - * 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 `openssl rsa` - * tool to convert PKCS#8 keys to PKCS#1. + * private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) + * or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208) + * PKCS \#8 format is supported since 2.32; earlier releases only + * support PKCS \#1. You can use the `openssl rsa` tool to convert + * PKCS \#8 keys to PKCS \#1. + * + * This property (or the #GTlsCertificate:private-key-pem property) + * can be set when constructing a key (for example, from a file). + * Since GLib 2.70, it is now also readable; however, be aware that if + * the private key is backed by a PKCS \#11 URI – for example, if it + * is stored on a smartcard – then this property will be %NULL. If so, + * the private key must be referenced via its PKCS \#11 URI, + * #GTlsCertificate:private-key-pkcs11-uri. You must check both + * properties to see if the certificate really has a private key. + * When this property is read, the output format will be unencrypted + * PKCS \#8. * * Since: 2.28 */ /** - * GTlsCertificate:private-key-pem: + * GTlsCertificate:private-key-pem: (nullable) * * The PEM (ASCII) encoded representation of the certificate's - * 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 `openssl rsa` - * tool to convert PKCS#8 keys to PKCS#1. + * private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) + * ("`BEGIN RSA PRIVATE KEY`") or unencrypted + * [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208) + * ("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32; + * earlier releases only support PKCS \#1. You can use the `openssl rsa` + * tool to convert PKCS \#8 keys to PKCS \#1. + * + * This property (or the #GTlsCertificate:private-key property) + * can be set when constructing a key (for example, from a file). + * Since GLib 2.70, it is now also readable; however, be aware that if + * the private key is backed by a PKCS \#11 URI - for example, if it + * is stored on a smartcard - then this property will be %NULL. If so, + * the private key must be referenced via its PKCS \#11 URI, + * #GTlsCertificate:private-key-pkcs11-uri. You must check both + * properties to see if the certificate really has a private key. + * When this property is read, the output format will be unencrypted + * PKCS \#8. * * Since: 2.28 */ @@ -3677,13 +3813,24 @@ /** * GTlsCertificate:private-key-pkcs11-uri: (nullable) * - * A URI referencing a PKCS \#11 object containing a private key. + * A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) + * object containing a private key. * * Since: 2.68 */ /** + * GTlsCertificate:subject-name: (nullable) + * + * The subject from the cert, + * %NULL if unavailable. + * + * Since: 2.70 + */ + + +/** * GTlsClientConnection: * * Abstract base class for the backend-specific client connection @@ -3846,6 +3993,15 @@ /** + * GTlsConnection:ciphersuite-name: (nullable) + * + * The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). + * + * Since: 2.70 + */ + + +/** * GTlsConnection:database: (nullable) * * The certificate database to use when verifying this TLS connection. @@ -3906,6 +4062,15 @@ /** + * GTlsConnection:protocol-version: + * + * The TLS protocol version in use. See g_tls_connection_get_protocol_version(). + * + * Since: 2.70 + */ + + +/** * GTlsConnection:rehandshake-mode: * * The rehandshaking mode. See @@ -4841,13 +5006,13 @@ * respectively. * * 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). + * [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/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). + * [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/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). + * [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). */ @@ -4918,7 +5083,7 @@ * } * ]| * The complete example can be found here: - * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) + * [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/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. @@ -4969,7 +5134,7 @@ * instance. * * The complete example can be found here: - * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) + * [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) * * If handling the commandline requires a lot of work, it may * be better to defer it. @@ -5011,7 +5176,7 @@ * 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) + * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) */ @@ -5618,22 +5783,22 @@ * ## 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) + * [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/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) + * [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) * * ## An example for file descriptor passing # {#gdbus-unix-fd-client} * * Here is an example for passing UNIX file descriptors: - * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-unix-fd-client.c) + * [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) * * ## 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) + * [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) */ @@ -5796,7 +5961,7 @@ * Convenience API for owning bus names. * * 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) + * [gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c) */ @@ -5809,7 +5974,7 @@ * Convenience API for watching bus names. * * 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) + * [gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c) */ @@ -6007,6 +6172,13 @@ * the message bus launching an owner (unless * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). * + * If the proxy is for a stateless D-Bus service, where the name owner may + * be started and stopped between calls, the #GDBusProxy:g-name-owner tracking + * of #GDBusProxy will cause the proxy to drop signal and property changes from + * the service after it has restarted for the first time. When interacting + * with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus + * method calls and signal connections. + * * 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 @@ -6021,7 +6193,7 @@ * of the thread where the instance was constructed. * * 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) + * [gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c) */ @@ -6040,7 +6212,7 @@ * session or system bus, you should instead use g_bus_own_name(). * * An example of peer-to-peer communication with GDBus can be found - * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). + * in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). * * Note that a minimal #GDBusServer will accept connections from any * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver @@ -6481,6 +6653,11 @@ * g_file_query_writable_namespaces() to discover the settable attributes * of a particular file at runtime. * + * The direct accessors, such as g_file_info_get_name(), are slightly more + * optimized than the generic attribute accessors, such as + * g_file_info_get_attribute_byte_string().This optimization will matter + * only if calling the API in a tight loop. + * * #GFileAttributeMatcher allows for searching through a #GFileInfo for * attributes. */ @@ -6943,13 +7120,14 @@ * There is also an implementation for use inside Flatpak sandboxes. * * Possible actions to take when the signal is received are: - * - Free caches - * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed - * - Run a garbage collection cycle - * - Try and compress fragmented allocations - * - Exit on idle if the process has no reason to stay around - * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to - * the kernel (if supported by your libc) + * + * - Free caches + * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed + * - Run a garbage collection cycle + * - Try and compress fragmented allocations + * - Exit on idle if the process has no reason to stay around + * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + * the kernel (if supported by your libc) * * Note that some actions may not always improve system performance, and so * should be profiled for your application. `malloc_trim()`, for example, may @@ -7315,6 +7493,29 @@ * not running, applications using #GNotification should be able to be * started as a D-Bus service, using #GApplication. * + * In order for #GNotification to work, the application must have installed + * a `.desktop` file. For example: + * |[ + * [Desktop Entry] + * Name=Test Application + * Comment=Description of what Test Application does + * Exec=gnome-test-application + * Icon=org.gnome.TestApplication + * Terminal=false + * Type=Application + * Categories=GNOME;GTK;TestApplication Category; + * StartupNotify=true + * DBusActivatable=true + * X-GNOME-UsesNotifications=true + * ]| + * + * The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center + * that this application uses notifications, so it can be listed in the + * Control Center’s ‘Notifications’ panel. + * + * The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, + * where `org.gnome.TestApplication` is the ID passed to g_application_new(). + * * 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 @@ -7413,6 +7614,39 @@ /** + * SECTION:gpowerprofilemonitor + * @title: GPowerProfileMonitor + * @short_description: Power profile monitor + * @include: gio/gio.h + * + * #GPowerProfileMonitor makes it possible for applications as well as OS components + * to monitor system power profiles and act upon them. It currently only exports + * whether the system is in “Power Saver” mode (known as “Low Power” mode on + * some systems). + * + * When in “Low Power” mode, it is recommended that applications: + * - disabling automatic downloads + * - reduce the rate of refresh from online sources such as calendar or + * email synchronisation + * - if the application has expensive visual effects, reduce them + * + * It is also likely that OS components providing services to applications will + * lower their own background activity, for the sake of the system. + * + * There are a variety of tools that exist for power consumption analysis, but those + * usually depend on the OS and hardware used. On Linux, one could use `upower` to + * monitor the battery discharge rate, `powertop` to check on the background activity + * or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to + * profile GPU usage. + * + * Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled + * signal, and unref the #GPowerProfileMonitor itself when exiting. + * + * Since: 2.70 + */ + + +/** * SECTION:gpropertyaction * @title: GPropertyAction * @short_description: A GAction reflecting a GObject property @@ -7835,7 +8069,7 @@ * 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) + * [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) * * The [glib-compile-schemas][glib-compile-schemas] tool expects schema * files to have the extension `.gschema.xml`. @@ -9430,7 +9664,7 @@ * * 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) + * [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/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 @@ -9982,7 +10216,7 @@ /** - * SECTION:gzcompressor + * SECTION:gzlibcompressor * @short_description: Zlib compressor * @include: gio/gio.h * @@ -9992,7 +10226,7 @@ /** - * SECTION:gzdecompressor + * SECTION:gzlibdecompressor * @short_description: Zlib decompressor * @include: gio/gio.h * @@ -12205,6 +12439,8 @@ * * To cancel the busy indication, use g_application_unmark_busy(). * + * The application must be registered before calling this function. + * * Since: 2.38 */ @@ -12374,7 +12610,7 @@ * 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 - * [gapplication-example-cmdline2.c][gapplication-example-cmdline2] + * [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] * for an example. * * If, after the above is done, the use count of the application is zero @@ -15274,7 +15510,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -15298,7 +15534,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -16544,6 +16780,9 @@ * g_dbus_connection_signal_subscribe() is called, in order to avoid memory * leaks through callbacks queued on the #GMainContext after it’s stopped being * iterated. + * Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT + * that was scheduled after unsubscription, also indicates that all resources + * of this subscription are released. * * Since: 2.26 */ @@ -16845,8 +17084,14 @@ * Generate a D-Bus GUID that can be used with * e.g. g_dbus_connection_new(). * - * See the D-Bus specification regarding what strings are valid D-Bus - * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * See the + * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids) + * regarding what strings are valid D-Bus GUIDs. The specification refers to + * these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as + * ‘GUIDs’. The terms are interchangeable. + * + * Note that D-Bus GUIDs do not follow + * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). * * Returns: A valid D-Bus GUID. Free with g_free(). * Since: 2.26 @@ -17055,7 +17300,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -17278,15 +17523,30 @@ /** + * g_dbus_is_error_name: + * @string: The string to check. + * + * Check whether @string is a valid D-Bus error name. + * + * This function returns the same result as g_dbus_is_interface_name(), + * because D-Bus error names are defined to have exactly the + * same syntax as interface names. + * + * Returns: %TRUE if valid, %FALSE otherwise. + * Since: 2.70 + */ + + +/** * g_dbus_is_guid: * @string: The string to check. * * Checks if @string is a D-Bus GUID. * - * See the D-Bus specification regarding what strings are valid D-Bus - * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). + * See the documentation for g_dbus_generate_guid() for more information about + * the format of a GUID. * - * Returns: %TRUE if @string is a guid, %FALSE otherwise. + * Returns: %TRUE if @string is a GUID, %FALSE otherwise. * Since: 2.26 */ @@ -17610,7 +17870,9 @@ * * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. * - * Returns: The value. + * This will always be non-%NULL, but may be an empty string. + * + * Returns: (not nullable): The value. * Since: 2.26 */ @@ -17796,7 +18058,7 @@ * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 * ]| * - * Returns: A string that should be freed with g_free(). + * Returns: (not nullable): A string that should be freed with g_free(). * Since: 2.26 */ @@ -18035,7 +18297,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -18423,7 +18685,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -18671,7 +18933,7 @@ * Gets the interface proxy for @interface_name at @object_path, if * any. * - * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free + * Returns: (transfer full) (nullable): A #GDBusInterface instance or %NULL. Free * with g_object_unref(). * Since: 2.30 */ @@ -18684,7 +18946,7 @@ * * Gets the #GDBusObjectProxy at @object_path, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. Free with + * Returns: (transfer full) (nullable): A #GDBusObject or %NULL. Free with * g_object_unref(). * Since: 2.30 */ @@ -18755,7 +19017,7 @@ * * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer full): A #GDBusConnection object or %NULL if + * Returns: (transfer full) (nullable): 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 @@ -18925,7 +19187,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -19169,7 +19431,7 @@ * * Gets the connection @proxy is for. * - * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free. + * Returns: (transfer none) (not nullable): A #GDBusConnection owned by @proxy. Do not free. * Since: 2.26 */ @@ -19220,7 +19482,7 @@ * * Gets the D-Bus interface name @proxy is for. * - * Returns: A string owned by @proxy. Do not free. + * Returns: (not nullable): A string owned by @proxy. Do not free. * Since: 2.26 */ @@ -19231,7 +19493,11 @@ * * Gets the name that @proxy was constructed for. * - * Returns: A string owned by @proxy. Do not free. + * When connected to a message bus, this will usually be non-%NULL. + * However, it may be %NULL for a proxy that communicates using a peer-to-peer + * pattern. + * + * Returns: (nullable): A string owned by @proxy. Do not free. * Since: 2.26 */ @@ -19257,7 +19523,7 @@ * * Gets the object path @proxy is for. * - * Returns: A string owned by @proxy. Do not free. + * Returns: (not nullable): A string owned by @proxy. Do not free. * Since: 2.26 */ @@ -19495,7 +19761,9 @@ * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) * string that can be used by clients to connect to @server. * - * Returns: A D-Bus address string. Do not free, the string is owned + * This is valid and non-empty if initializing the #GDBusServer succeeded. + * + * Returns: (not nullable): A D-Bus address string. Do not free, the string is owned * by @server. * Since: 2.26 */ @@ -19516,9 +19784,9 @@ * g_dbus_server_get_guid: * @server: A #GDBusServer. * - * Gets the GUID for @server. + * Gets the GUID for @server, as provided to g_dbus_server_new_sync(). * - * Returns: A D-Bus GUID. Do not free this string, it is owned by @server. + * Returns: (not nullable): A D-Bus GUID. Do not free this string, it is owned by @server. * Since: 2.26 */ @@ -19597,7 +19865,7 @@ * If @info is statically allocated does nothing. Otherwise increases * the reference count. * - * Returns: The same @info. + * Returns: (not nullable): The same @info. * Since: 2.26 */ @@ -20629,6 +20897,24 @@ /** + * g_dtls_connection_get_ciphersuite_name: + * @conn: a #GDTlsConnection + * + * Returns the name of the current DTLS ciphersuite, or %NULL if the + * connection has not handshaked or has been closed. Beware that the TLS + * backend may use any of multiple different naming conventions, because + * OpenSSL and GnuTLS have their own ciphersuite naming conventions that + * are different from each other and different from the standard, IANA- + * registered ciphersuite names. The ciphersuite name is intended to be + * displayed to the user for informative purposes only, and parsing it + * is not recommended. + * + * Returns: (nullable): The name of the current DTLS ciphersuite, or %NULL + * Since: 2.70 + */ + + +/** * g_dtls_connection_get_database: * @conn: a #GDtlsConnection * @@ -20697,6 +20983,20 @@ /** + * g_dtls_connection_get_protocol_version: + * @conn: a #GDTlsConnection + * + * Returns the current DTLS protocol version, which may be + * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or + * has been closed, or if the TLS backend has implemented a protocol version + * that is not a recognized #GTlsProtocolVersion. + * + * Returns: The current DTLS protocol version + * Since: 2.70 + */ + + +/** * g_dtls_connection_get_rehandshake_mode: * @conn: a #GDtlsConnection * @@ -22541,6 +22841,22 @@ /** + * g_file_info_get_access_date_time: + * @info: a #GFileInfo. + * + * Gets the access time of the current @info and returns it as a + * #GDateTime. + * + * This requires the %G_FILE_ATTRIBUTE_TIME_ACCESS attribute. If + * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime + * will have microsecond precision. + * + * Returns: (transfer full) (nullable): access time, or %NULL if unknown + * Since: 2.70 + */ + + +/** * g_file_info_get_attribute_as_string: * @info: a #GFileInfo. * @attribute: a file attribute key. @@ -22724,6 +23040,22 @@ /** + * g_file_info_get_creation_date_time: + * @info: a #GFileInfo. + * + * Gets the creation time of the current @info and returns it as a + * #GDateTime. + * + * This requires the %G_FILE_ATTRIBUTE_TIME_CREATED attribute. If + * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime + * will have microsecond precision. + * + * Returns: (transfer full) (nullable): creation time, or %NULL if unknown + * Since: 2.70 + */ + + +/** * g_file_info_get_deletion_date: * @info: a #GFileInfo. * @@ -22960,6 +23292,19 @@ /** + * g_file_info_set_access_date_time: + * @info: a #GFileInfo. + * @atime: (not nullable): a #GDateTime. + * + * Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and + * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the + * given date/time value. + * + * Since: 2.70 + */ + + +/** * g_file_info_set_attribute: * @info: a #GFileInfo. * @attribute: a file attribute key. @@ -23111,6 +23456,19 @@ /** + * g_file_info_set_creation_date_time: + * @info: a #GFileInfo. + * @creation_time: (not nullable): a #GDateTime. + * + * Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and + * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the + * given date/time value. + * + * Since: 2.70 + */ + + +/** * g_file_info_set_display_name: * @info: a #GFileInfo. * @display_name: a string containing a display name. @@ -26357,7 +26715,7 @@ * @stream: a #GInputStream. * @buffer: (array length=count) (element-type guint8) (out caller-allocates): * 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 + * @count: (in): the number of bytes that will be read from the stream * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -26392,7 +26750,7 @@ * @stream: a #GInputStream. * @buffer: (array length=count) (element-type guint8) (out caller-allocates): * 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 + * @count: (in): 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: (nullable): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore @@ -26426,7 +26784,7 @@ * @stream: A #GInputStream * @buffer: (array length=count) (element-type guint8) (out caller-allocates): * 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 + * @count: (in): the number of bytes that will be read from the stream * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied @@ -26474,7 +26832,7 @@ * @stream: A #GInputStream. * @buffer: (array length=count) (element-type guint8) (out caller-allocates): * 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 + * @count: (in): the number of bytes that will be read from the stream * @io_priority: the [I/O priority][io-priority] * of the request. * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. @@ -29937,6 +30295,22 @@ /** + * g_notification_set_category: + * @notification: a #GNotification + * @category: (nullable): the category for @notification, or %NULL for no category + * + * Sets the type of @notification to @category. Categories have a main + * type like `email`, `im` or `device` and can have a detail separated + * by a `.`, e.g. `im.received` or `email.arrived`. Setting the category + * helps the notification server to select proper feedback to the user. + * + * Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html). + * + * Since: 2.70 + */ + + +/** * g_notification_set_default_action: * @notification: a #GNotification * @detailed_action: a detailed action name @@ -31019,9 +31393,9 @@ /** * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking) * @stream: a #GPollableInputStream - * @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 you want to read + * @buffer: (array length=count) (element-type guint8) (out caller-allocates): a + * buffer to read data into (which should be at least @count bytes long). + * @count: (in): the number of bytes you want to read * @cancellable: (nullable): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. * @@ -31284,6 +31658,31 @@ /** + * g_power_profile_monitor_dup_default: + * + * Gets a reference to the default #GPowerProfileMonitor for the system. + * + * Returns: (not nullable) (transfer full): a new reference to the default #GPowerProfileMonitor + * Since: 2.70 + */ + + +/** + * g_power_profile_monitor_get_power_saver_enabled: + * @monitor: a #GPowerProfileMonitor + * + * Gets whether the system is in “Power Saver” mode. + * + * You are expected to listen to the + * #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has + * changed. + * + * Returns: Whether the system is in “Power Saver” mode. + * Since: 2.70 + */ + + +/** * g_property_action_new: * @name: the name of the action to create * @object: (type GObject.Object): the object that has the property @@ -32350,7 +32749,8 @@ * * Tells the current position within the stream. * - * Returns: the offset from the beginning of the buffer. + * Returns: the (positive or zero) offset from the beginning of the + * buffer, zero if the target is not seekable. */ @@ -36277,7 +36677,7 @@ * This is the asynchronous version of g_socket_listener_accept(). * * When the operation is finished @callback will be - * called. You can then call g_socket_listener_accept_socket() + * called. You can then call g_socket_listener_accept_finish() * to get the result of the operation. * * Since: 2.22 @@ -37655,7 +38055,7 @@ * * 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(). + * be used with g_spawn_check_wait_status(). * * It is more likely that you want to use g_subprocess_get_if_exited() * followed by g_subprocess_get_exit_status(). @@ -38215,7 +38615,7 @@ * @cancellable: a #GCancellable * @error: a #GError * - * Combines g_subprocess_wait() with g_spawn_check_exit_status(). + * Combines g_subprocess_wait() with g_spawn_check_wait_status(). * * Returns: %TRUE on success, %FALSE if process exited abnormally, or * @cancellable was cancelled @@ -38230,7 +38630,7 @@ * @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(). + * Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). * * This is the asynchronous version of g_subprocess_wait_check(). * @@ -38730,9 +39130,9 @@ * * Although GLib currently rate-limits the tasks queued via * g_task_run_in_thread(), you should not assume that it will always - * do this. If you have a very large number of tasks to run, but don't - * want them to all run at once, you should only queue a limited - * number of them at a time. + * do this. If you have a very large number of tasks to run (several tens of + * tasks), but don't want them to all run at once, you should only queue a + * limited number of them (around ten) at a time. * * Since: 2.36 */ @@ -39302,6 +39702,30 @@ /** + * g_tls_certificate_get_dns_names: + * @cert: a #GTlsCertificate + * + * Gets the value of #GTlsCertificate:dns-names. + * + * Returns: (nullable) (element-type GBytes) (transfer container): A #GPtrArray of + * #GBytes elements, or %NULL if it's not available. + * Since: 2.70 + */ + + +/** + * g_tls_certificate_get_ip_addresses: + * @cert: a #GTlsCertificate + * + * Gets the value of #GTlsCertificate:ip-addresses. + * + * Returns: (nullable) (element-type GInetAddress) (transfer container): A #GPtrArray + * of #GInetAddress elements, or %NULL if it's not available. + * Since: 2.70 + */ + + +/** * g_tls_certificate_get_issuer: * @cert: a #GTlsCertificate * @@ -39315,6 +39739,50 @@ /** + * g_tls_certificate_get_issuer_name: + * @cert: a #GTlsCertificate + * + * Returns the issuer name from the certificate. + * + * Returns: (nullable) (transfer full): The issuer name, or %NULL if it's not available. + * Since: 2.70 + */ + + +/** + * g_tls_certificate_get_not_valid_after: + * @cert: a #GTlsCertificate + * + * Returns the time at which the certificate became or will become invalid. + * + * Returns: (nullable) (transfer full): The not-valid-after date, or %NULL if it's not available. + * Since: 2.70 + */ + + +/** + * g_tls_certificate_get_not_valid_before: + * @cert: a #GTlsCertificate + * + * Returns the time at which the certificate became or will become valid. + * + * Returns: (nullable) (transfer full): The not-valid-before date, or %NULL if it's not available. + * Since: 2.70 + */ + + +/** + * g_tls_certificate_get_subject_name: + * @cert: a #GTlsCertificate + * + * Returns the subject name from the certificate. + * + * Returns: (nullable) (transfer full): The subject name, or %NULL if it's not available. + * Since: 2.70 + */ + + +/** * g_tls_certificate_is_same: * @cert_one: first certificate to compare * @cert_two: second certificate to compare @@ -39432,13 +39900,14 @@ * @private_key_pkcs11_uri: (nullable): A PKCS \#11 URI * @error: #GError for error reporting, or %NULL to ignore. * - * Creates a #GTlsCertificate from a PKCS \#11 URI. + * Creates a #GTlsCertificate from a + * [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI. * * An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` * * Where the token’s layout is: * - * ``` + * |[ * Object 0: * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private * Type: Private key (RSA-2048) @@ -39448,7 +39917,7 @@ * URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert * Type: X.509 Certificate (RSA-2048) * ID: 01 - * ``` + * ]| * * In this case the certificate and private key would both be detected and used as expected. * @pkcs_uri may also just reference an X.509 certificate object and then optionally @@ -39487,6 +39956,13 @@ * (All other #GTlsCertificateFlags values will always be set or unset * as appropriate.) * + * Because TLS session context is not used, #GTlsCertificate may not + * perform as many checks on the certificates as #GTlsConnection would. + * For example, certificate constraints cannot be honored, and some + * revocation checks cannot be performed. The best way to verify TLS + * certificates used by a TLS connection is to let #GTlsConnection + * handle the verification. + * * Returns: the appropriate #GTlsCertificateFlags * Since: 2.28 */ @@ -39719,6 +40195,24 @@ /** + * g_tls_connection_get_ciphersuite_name: + * @conn: a #GTlsConnection + * + * Returns the name of the current TLS ciphersuite, or %NULL if the + * connection has not handshaked or has been closed. Beware that the TLS + * backend may use any of multiple different naming conventions, because + * OpenSSL and GnuTLS have their own ciphersuite naming conventions that + * are different from each other and different from the standard, IANA- + * registered ciphersuite names. The ciphersuite name is intended to be + * displayed to the user for informative purposes only, and parsing it + * is not recommended. + * + * Returns: (nullable): The name of the current TLS ciphersuite, or %NULL + * Since: 2.70 + */ + + +/** * g_tls_connection_get_database: * @conn: a #GTlsConnection * @@ -39787,6 +40281,20 @@ /** + * g_tls_connection_get_protocol_version: + * @conn: a #GTlsConnection + * + * Returns the current TLS protocol version, which may be + * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or + * has been closed, or if the TLS backend has implemented a protocol version + * that is not a recognized #GTlsProtocolVersion. + * + * Returns: The current TLS protocol version + * Since: 2.70 + */ + + +/** * g_tls_connection_get_rehandshake_mode: * @conn: a #GTlsConnection * @@ -40146,14 +40654,26 @@ * @cancellable: (nullable): a #GCancellable, or %NULL * @error: (nullable): a #GError, or %NULL * - * Look up the issuer of @certificate in the database. - * - * The #GTlsCertificate:issuer property - * of @certificate is not modified, and the two certificates are not hooked - * into a chain. - * - * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform - * the lookup operation asynchronously. + * Look up the issuer of @certificate in the database. The + * #GTlsCertificate:issuer property of @certificate is not modified, and + * the two certificates are not hooked into a chain. + * + * This function can block. Use g_tls_database_lookup_certificate_issuer_async() + * to perform the lookup operation asynchronously. + * + * Beware this function cannot be used to build certification paths. The + * issuer certificate returned by this function may not be the same as + * the certificate that would actually be used to construct a valid + * certification path during certificate verification. + * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains + * why an issuer certificate cannot be naively assumed to be part of the + * the certification path (though GLib's TLS backends may not follow the + * path building strategies outlined in this RFC). Due to the complexity + * of certification path building, GLib does not provide any way to know + * which certification path will actually be used when verifying a TLS + * certificate. Accordingly, this function cannot be used to make + * security-related decisions. Only GLib itself should make security + * decisions about TLS certificates. * * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, * or %NULL. Use g_object_unref() to release the certificate. @@ -40260,15 +40780,11 @@ * @cancellable: (nullable): a #GCancellable, or %NULL * @error: (nullable): a #GError, or %NULL * - * Determines the validity of a certificate chain after looking up and - * adding any missing certificates to the chain. + * Determines the validity of a certificate chain, outside the context + * of a TLS session. * * @chain is a chain of #GTlsCertificate objects each pointing to the next - * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially - * consist of one or more certificates. After the verification process is - * complete, @chain may be modified by adding missing certificates, or removing - * extra certificates. If a certificate anchor was found, then it is added to - * the @chain. + * certificate in the chain by its #GTlsCertificate:issuer property. * * @purpose describes the purpose (or usage) for which the certificate * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER @@ -40295,8 +40811,27 @@ * accordingly. @error is not set when @chain is successfully analyzed * but found to be invalid. * - * This function can block, use g_tls_database_verify_chain_async() to perform - * the verification operation asynchronously. + * Prior to GLib 2.48, GLib's default TLS backend modified @chain to + * represent the certification path built by #GTlsDatabase during + * certificate verification by adjusting the #GTlsCertificate:issuer + * property of each certificate in @chain. Since GLib 2.48, this no + * longer occurs, so you cannot rely on #GTlsCertificate:issuer to + * represent the actual certification path used during certificate + * verification. + * + * Because TLS session context is not used, #GTlsDatabase may not + * perform as many checks on the certificates as #GTlsConnection would. + * For example, certificate constraints cannot be honored, and some + * revocation checks cannot be performed. The best way to verify TLS + * certificates used by a TLS connection is to let #GTlsConnection + * handle the verification. + * + * The TLS backend may attempt to look up and add missing certificates + * to the chain. Since GLib 2.70, this may involve HTTP requests to + * download missing certificates. + * + * 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. @@ -40612,9 +41147,9 @@ /** - * g_tls_password_get_value: + * g_tls_password_get_value: (virtual get_value) * @password: a #GTlsPassword object - * @length: (nullable): location to place the length of the password. + * @length: (optional): location to place the length of the password. * * Get the password value. If @length is not %NULL then it will be * filled in with the length of the password value. (Note that the @@ -40622,7 +41157,7 @@ * for @length in contexts where you know the password will have a * certain fixed length.) * - * Returns: The password value (owned by the password object). + * Returns: (array length=length): The password value (owned by the password object). * Since: 2.30 */ @@ -41296,7 +41831,9 @@ * If more mounts have the same mount path, the last matching mount * is returned. * - * Returns: (transfer full): a #GUnixMountEntry. + * This will return %NULL if there is no mount point at @mount_path. + * + * Returns: (transfer full) (nullable): a #GUnixMountEntry. */ @@ -41335,7 +41872,10 @@ * If more mounts have the same mount path, the last matching mount * is returned. * - * Returns: (transfer full): a #GUnixMountEntry. + * This will return %NULL if looking up the mount entry fails, if + * @file_path doesn’t exist or there is an I/O error. + * + * Returns: (transfer full) (nullable): a #GUnixMountEntry. * Since: 2.52 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 80bc0d71..5ea15d63 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -79,9 +79,9 @@ /** * GAsyncQueue: * - * The GAsyncQueue struct is an opaque data structure which represents - * an asynchronous queue. It should only be accessed through the - * g_async_queue_* functions. + * An opaque data structure which represents an asynchronous queue. + * + * It should only be accessed through the `g_async_queue_*` functions. */ @@ -232,9 +232,9 @@ /** * GData: * - * 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. + * An opaque data structure that represents a keyed data list. + * + * See also: [Keyed data lists][glib-Keyed-Data-Lists]. */ @@ -256,15 +256,15 @@ * @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 + * 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 + * 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 #GDate-struct is obtained from g_date_new(), it will be safe + * If the `GDate` 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 @@ -290,7 +290,8 @@ * GDateDay: * * Integer representing a day of the month; between 1 and 31. - * #G_DATE_BAD_DAY represents an invalid day of the month. + * + * The %G_DATE_BAD_DAY value represents an invalid day of the month. */ @@ -310,8 +311,8 @@ * @G_DATE_NOVEMBER: November * @G_DATE_DECEMBER: December * - * Enumeration representing a month; values are #G_DATE_JANUARY, - * #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. + * Enumeration representing a month; values are %G_DATE_JANUARY, + * %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value. */ @@ -334,9 +335,13 @@ /** * GDateYear: * - * Integer representing a year; #G_DATE_BAD_YEAR is the invalid - * value. The year must be 1 or higher; negative (BC) years are not - * allowed. The year is represented with four digits. + * Integer type representing a year. + * + * The %G_DATE_BAD_YEAR value is the invalid value. The year + * must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era)) + * years are not allowed. + * + * The year is represented with four digits. */ @@ -1083,7 +1088,7 @@ /** * GKeyFileError: * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in - * an unknown encoding + * 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 @@ -1098,13 +1103,13 @@ * 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. + * (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. + * (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. */ @@ -2062,7 +2067,9 @@ * * 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. + * with a 64-bit `time_t`. + * + * Unrelated to #GTimer. * * Note that #GTime is defined to always be a 32-bit integer, * unlike `time_t` which may be 64-bit on some systems. Therefore, @@ -2071,6 +2078,7 @@ * function. * * Instead, do the following: + * * |[<!-- language="C" --> * time_t ttime; * GTime gtime; @@ -2090,7 +2098,8 @@ * @tv_usec: microseconds * * Represents a precise time, with seconds and microseconds. - * Similar to the struct timeval returned by the gettimeofday() + * + * Similar to the struct timeval returned by the `gettimeofday()` * UNIX system call. * * GLib is attempting to unify around the use of 64-bit integers to @@ -3623,7 +3632,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ACTIONS: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list * giving the available application actions. * * Since: 2.38 @@ -3633,7 +3642,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_CATEGORIES: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list * of strings giving the categories in which the desktop entry * should be shown in a menu. * @@ -3644,7 +3653,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_COMMENT: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the tooltip for the desktop entry. * * Since: 2.14 @@ -3654,8 +3663,8 @@ /** * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true - * if the application is D-Bus activatable. + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * set to true if the application is D-Bus activatable. * * Since: 2.38 */ @@ -3664,7 +3673,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_EXEC: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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 `Application` type. * @@ -3675,7 +3684,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the generic name of the desktop entry. * * Since: 2.14 @@ -3685,7 +3694,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_HIDDEN: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the desktop entry has been deleted by the user. * * Since: 2.14 @@ -3695,7 +3704,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ICON: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the name of the icon to be displayed for the desktop * entry. * @@ -3706,7 +3715,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list * of strings giving the MIME types supported by this desktop entry. * * Since: 2.14 @@ -3716,7 +3725,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NAME: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * string giving the specific name of the desktop entry. * * Since: 2.14 @@ -3726,7 +3735,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * strings identifying the environments that should not display the * desktop entry. * @@ -3737,7 +3746,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the desktop entry should be shown in menus. * * Since: 2.14 @@ -3747,7 +3756,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * strings identifying the environments that should display the * desktop entry. * @@ -3758,7 +3767,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_PATH: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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 `Application` type. * @@ -3769,7 +3778,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * stating whether the application supports the * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). * @@ -3780,7 +3789,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string * identifying the WM class or name hint of a window that the application * will create, which can be used to emulate Startup Notification with * older applications. @@ -3792,10 +3801,10 @@ /** * G_KEY_FILE_DESKTOP_KEY_TERMINAL: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + * 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 - * `Application` type. + * + * It is only valid for desktop entries with the `Application` type. * * Since: 2.14 */ @@ -3804,7 +3813,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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 `Application` type. @@ -3816,11 +3825,12 @@ /** * G_KEY_FILE_DESKTOP_KEY_TYPE: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string - * giving the type of the desktop entry. Usually - * #G_KEY_FILE_DESKTOP_TYPE_APPLICATION, - * #G_KEY_FILE_DESKTOP_TYPE_LINK, or - * #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * giving the type of the desktop entry. + * + * Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION, + * %G_KEY_FILE_DESKTOP_TYPE_LINK, or + * %G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. * * Since: 2.14 */ @@ -3829,7 +3839,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_URL: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * 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 `Link` type. * @@ -3840,7 +3850,7 @@ /** * G_KEY_FILE_DESKTOP_KEY_VERSION: * - * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string * giving the version of the Desktop Entry Specification used for * the desktop entry file. * @@ -3851,7 +3861,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_APPLICATION: * - * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing applications. * * Since: 2.14 @@ -3861,7 +3871,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY: * - * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing directories. * * Since: 2.14 @@ -3871,7 +3881,7 @@ /** * G_KEY_FILE_DESKTOP_TYPE_LINK: * - * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * entries representing links to documents. * * Since: 2.14 @@ -3932,7 +3942,7 @@ * @name: the name of the lock * * Works like g_mutex_lock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. */ @@ -3940,16 +3950,17 @@ * G_LOCK_DEFINE: * @name: the name of the lock * - * The #G_LOCK_ macros provide a convenient interface to #GMutex. - * #G_LOCK_DEFINE defines a lock. It can appear in any place where + * 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 - * give_me_next_number() example using the #G_LOCK macros: + * give_me_next_number() example using the `G_LOCK` macros: + * + * Here is an example for using the `G_LOCK` convenience macros: * - * Here is an example for using the #G_LOCK convenience macros: * |[<!-- language="C" --> * G_LOCK_DEFINE (current_number); * @@ -3973,7 +3984,7 @@ * G_LOCK_DEFINE_STATIC: * @name: the name of the lock * - * This works like #G_LOCK_DEFINE, but it creates a static object. + * This works like %G_LOCK_DEFINE, but it creates a static object. */ @@ -3981,7 +3992,7 @@ * G_LOCK_EXTERN: * @name: the name of the lock * - * This declares a lock, that is defined with #G_LOCK_DEFINE in another + * This declares a lock, that is defined with %G_LOCK_DEFINE in another * module. */ @@ -4416,9 +4427,11 @@ /** * G_SHELL_ERROR: * - * Error domain for shell functions. Errors in this domain will be from - * the #GShellError enumeration. See #GError for information on error - * domains. + * Error domain for shell functions. + * + * Errors in this domain will be from the #GShellError enumeration. + * + * See #GError for information on error domains. */ @@ -4576,7 +4589,7 @@ * @name: the name of the lock * * Works like g_mutex_trylock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. * * Returns: %TRUE, if the lock could be locked. */ @@ -4617,7 +4630,7 @@ * @name: the name of the lock * * Works like g_mutex_unlock(), but for a lock defined with - * #G_LOCK_DEFINE. + * %G_LOCK_DEFINE. */ @@ -5236,7 +5249,7 @@ * 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) + * [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel) * * A bookmark file might contain more than one bookmark; each bookmark * is accessed through its URI. @@ -5682,6 +5695,12 @@ * function (the file being opened, or whatever - though in the * g_file_get_contents() case, the @message already contains a filename). * + * Since error messages may be displayed to the user, they need to be valid + * UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in + * particular when formatting error messages with filenames, which are in + * the 'filename encoding', and need to be turned into UTF-8 using + * g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid(). + * * Note, however, that many error messages are too technical to display to the * user in an application, so prefer to use g_error_matches() to categorize errors * from called functions, and build an appropriate error message for the context @@ -6396,19 +6415,19 @@ * concurrently accessed in any way from any number of threads without * problems. * - * #GVariant is heavily optimised for dealing with data in serialised + * #GVariant is heavily optimised for dealing with data in serialized * form. It works particularly well with data located in memory-mapped - * files. It can perform nearly all deserialisation operations in a + * files. It can perform nearly all deserialization operations in a * small constant time, usually touching only a single memory page. - * Serialised #GVariant data can also be sent over the network. + * Serialized #GVariant data can also be sent over the network. * * #GVariant is largely compatible with D-Bus. Almost all types of * #GVariant instances can be sent over D-Bus. See #GVariantType for - * exceptions. (However, #GVariant's serialisation format is not the same - * as the serialisation format of a D-Bus message body: use #GDBusMessage, + * exceptions. (However, #GVariant's serialization format is not the same + * as the serialization format of a D-Bus message body: use #GDBusMessage, * in the gio library, for those.) * - * For space-efficiency, the #GVariant serialisation format does not + * For space-efficiency, the #GVariant serialization format does not * automatically include the variant's length, type or endianness, * which must either be implied from context (such as knowledge that a * particular file format always contains a little-endian @@ -6438,14 +6457,14 @@ * in the future. * * The memory allocated by #GVariant can be grouped into 4 broad - * purposes: memory for serialised data, memory for the type + * purposes: memory for serialized data, memory for the type * information cache, buffer management memory and memory for the * #GVariant structure itself. * - * ## Serialised Data Memory + * ## Serialized 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 + * serialized form. This is what would be sent over the network or * what would end up on disk, not counting any indicator of the * endianness, or of the length or type of the top-level variant. * @@ -6479,7 +6498,7 @@ * * 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. + * the serialization. * * If we add an item "width" that maps to the int32 value of 500 then * we will use 4 byte to store the int32 (so 6 for the variant @@ -6505,7 +6524,7 @@ * * 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. + * type information structure is required for rapid deserialization. * * Continuing with the above example, if a #GVariant exists with the * type "a{sv}" then a type information struct will exist for @@ -6550,14 +6569,14 @@ * ## Buffer Management Memory * * #GVariant uses an internal buffer management structure to deal - * with the various different possible sources of serialised data + * with the various different possible sources of serialized data * that it uses. The buffer is responsible for ensuring that the * correct call is made when the data is no longer in use by * #GVariant. This may involve a g_free() or a g_slice_free() or * even g_mapped_file_unref(). * * One buffer management structure is used for each chunk of - * serialised data. The size of the buffer management structure + * serialized data. The size of the buffer management structure * is 4 * (void *). On 32-bit systems, that's 16 bytes. * * ## GVariant structure @@ -6567,7 +6586,7 @@ * * #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) + * serialized data for the example given above (with the dictionary) * then although there are 9 individual values that comprise the * entire dictionary (two keys, two values, two variants containing * the values, two dictionary entries, plus the dictionary itself), @@ -6577,8 +6596,8 @@ * 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 + * type information is shared. The serialized data and the buffer + * management structure for that serialized data is shared by the * child. * * ## Summary @@ -6586,12 +6605,12 @@ * 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 bytes of memory - * for the serialised data, 16 bytes for buffer management and 24 + * for the serialized data, 16 bytes for buffer management and 24 * bytes for the #GVariant instance, or a total of 160 bytes, plus * malloc overhead. If we were to use g_variant_get_child_value() to * access the two dictionary entries, we would use an additional 48 * bytes. If we were to have other dictionaries of the same type, we - * would use more memory for the serialised data and buffer + * would use more memory for the serialized data and buffer * management for those dictionaries, but the type information would * be shared. */ @@ -7255,7 +7274,7 @@ * thread-safe. * * Each event source is assigned a priority. The default priority, - * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. + * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. * Values greater than 0 denote lower priorities. Events from high priority * sources are always processed before events from lower priority sources. * @@ -7766,7 +7785,7 @@ * { "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, &randomize, "Randomize the data", NULL }, - * { NULL } + * G_OPTION_ENTRY_NULL * }; * * int @@ -8324,7 +8343,7 @@ * gpointer user_data) * { * g_message ("Child %" G_PID_FORMAT " exited %s", pid, - * g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally"); + * g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally"); * * // Free any resources associated with the child here, such as I/O channels * // on its stdout and stderr FDs. If you have no code to put in the @@ -9209,7 +9228,7 @@ * @array: a #GArray. * @target: a pointer to the item to look up. * @compare_func: A #GCompareFunc used to locate @target. - * @out_match_index: (optional) (out caller-allocates): return location + * @out_match_index: (optional) (out): return location * for the index of the element, if found. * * Checks whether @target exists in @array by performing a binary @@ -9490,6 +9509,27 @@ * functions, @clear_func is expected to clear the contents of * the array element it is given, but not free the element itself. * + * |[<!-- language="C" --> + * typedef struct + * { + * gchar *str; + * GObject *obj; + * } ArrayElement; + * + * static void + * array_element_clear (ArrayElement *element) + * { + * g_clear_pointer (&element->str, g_free); + * g_clear_object (&element->obj); + * } + * + * // main code + * GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement)); + * g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear); + * // assign data to the structure + * g_array_free (garray, TRUE); + * ]| + * * Since: 2.32 */ @@ -9558,7 +9598,7 @@ /** * g_array_steal: * @array: a #GArray. - * @len: (optional) (out caller-allocates): pointer to retrieve the number of + * @len: (optional) (out): pointer to retrieve the number of * elements of the original array * * Frees the data in the array and resets the size to zero, while @@ -10560,7 +10600,7 @@ /** * g_async_queue_new_full: - * @item_free_func: function to free queue elements + * @item_free_func: (nullable): function to free queue elements * * Creates a new asynchronous queue and sets up a destroy notify * function that is used to free any remaining queue items when @@ -11467,6 +11507,10 @@ * * Atomically decreases the reference count. * + * If %TRUE is returned, the reference count reached 0. After this point, @arc + * is an undefined state and must be reinitialized with + * g_atomic_ref_count_init() to be used again. + * * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise * Since: 2.58 */ @@ -11486,7 +11530,7 @@ * g_atomic_ref_count_init: * @arc: the address of an atomic reference count variable * - * Initializes a reference count variable. + * Initializes a reference count variable to 1. * * Since: 2.58 */ @@ -11890,7 +11934,8 @@ * * This function accesses @address atomically. All other accesses to * @address must be atomic in order for this function to work - * reliably. + * reliably. While @address has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. * * Since: 2.24 */ @@ -11954,7 +11999,8 @@ * * This function accesses @address atomically. All other accesses to * @address must be atomic in order for this function to work - * reliably. + * reliably. While @address has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. * * Returns: %TRUE if the lock was acquired * Since: 2.24 @@ -11972,7 +12018,8 @@ * * This function accesses @address atomically. All other accesses to * @address must be atomic in order for this function to work - * reliably. + * reliably. While @address has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. * * Since: 2.24 */ @@ -13175,7 +13222,7 @@ /** * g_byte_array_steal: * @array: a #GByteArray. - * @len: (optional) (out caller-allocates): pointer to retrieve the number of + * @len: (optional) (out): pointer to retrieve the number of * elements of the original array * * Frees the data in the array and resets the size to zero, while @@ -13259,6 +13306,39 @@ /** + * g_bytes_get_region: + * @bytes: a #GBytes + * @element_size: a non-zero element size + * @offset: an offset to the start of the region within the @bytes + * @n_elements: the number of elements in the region + * + * Gets a pointer to a region in @bytes. + * + * The region starts at @offset many bytes from the start of the data + * and contains @n_elements many elements of @element_size size. + * + * @n_elements may be zero, but @element_size must always be non-zero. + * Ideally, @element_size is a static constant (eg: sizeof a struct). + * + * This function does careful bounds checking (including checking for + * arithmetic overflows) and returns a non-%NULL pointer if the + * specified region lies entirely within the @bytes. If the region is + * in some way out of range, or if an overflow has occurred, then %NULL + * is returned. + * + * Note: it is possible to have a valid zero-size region. In this case, + * the returned pointer will be equal to the base pointer of the data of + * @bytes, plus @offset. This will be non-%NULL except for the case + * where @bytes itself was a zero-sized region. Since it is unlikely + * that you will be using this function to check for a zero-sized region + * in a zero-sized @bytes, %NULL effectively always means "error". + * + * Returns: (nullable): the requested region, or %NULL in case of an error + * Since: 2.70 + */ + + +/** * g_bytes_get_size: * @bytes: a #GBytes * @@ -13612,16 +13692,16 @@ /** * g_child_watch_add: * @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). + * 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 * * Sets a function to be called when the child indicated by @pid - * exits, at a default priority, #G_PRIORITY_DEFAULT. + * exits, at a default priority, %G_PRIORITY_DEFAULT. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to + * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * * Note that on platforms where #GPid must be explicitly closed @@ -13646,7 +13726,7 @@ /** * 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. + * 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 @@ -13657,10 +13737,10 @@ * exits, at the priority @priority. * * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() - * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to + * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to * the spawn function for the child watching to work. * - * In many programs, you will want to call g_spawn_check_exit_status() + * In many programs, you will want to call g_spawn_check_wait_status() * in the callback to determine whether or not the child exited * successfully. * @@ -14281,7 +14361,7 @@ * @...: format string, followed by parameters to insert * into the format string (as with printf()) * - * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). + * Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL). * * Critical warnings are intended to be used in the event of an error * that originated in the current process (a programmer error). @@ -16843,15 +16923,16 @@ * @err_no: an "errno" value * * Gets a #GFileError constant based on the passed-in @err_no. + * * For example, if you pass in `EEXIST` this function returns - * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably + * %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 * from a function that manipulates files. So you would use * g_file_error_from_errno() when constructing a #GError. * - * Returns: #GFileError corresponding to the given @errno + * Returns: #GFileError corresponding to the given @err_no */ @@ -17818,7 +17899,7 @@ * This folder is used for application data * that is not user specific. For example, an application can store * a spell-check dictionary, a database of clip art, or a log file in the - * CSIDL_COMMON_APPDATA folder. This information will not roam and is available + * FOLDERID_ProgramData folder. This information will not roam and is available * to anyone using the computer. * * The return value is cached and modifying it at runtime is not supported, as @@ -17847,8 +17928,8 @@ * the first elements in the list are the Application Data * and Documents folders for All Users. (These can be determined only * on Windows 2000 or later and are not present in the list on other - * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and - * CSIDL_COMMON_DOCUMENTS. + * Windows versions.) See documentation for FOLDERID_ProgramData and + * FOLDERID_PublicDocuments. * * Then follows the "share" subfolder in the installation folder for * the package containing the DLL that calls this function, if it can @@ -17913,7 +17994,7 @@ * If `XDG_CACHE_HOME` is undefined, the directory that serves as a common * repository for temporary Internet files is used instead. A typical path is * `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`. - * See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache). + * See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). * * The return value is cached and modifying it at runtime is not supported, as * it’s not thread-safe to modify environment variables at runtime. @@ -17938,7 +18019,7 @@ * On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined. * If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed * to roaming) application data is used instead. See the - * [documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). + * [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). * Note that in this case on Windows it will be the same * as what g_get_user_data_dir() returns. * @@ -17965,7 +18046,7 @@ * On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME` * is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as * opposed to roaming) application data is used instead. See the - * [documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). + * [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). * Note that in this case on Windows it will be the same * as what g_get_user_config_dir() returns. * @@ -18221,7 +18302,7 @@ /** * g_hash_table_get_keys_as_array: * @hash_table: a #GHashTable - * @length: (out): the length of the returned array + * @length: (out) (optional): the length of the returned array * * Retrieves every key inside @hash_table, as an array. * @@ -19207,7 +19288,7 @@ * * Adds a function to be called whenever there are no higher priority * events pending to the default main loop. The function is given the - * default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function + * default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function * returns %FALSE it is automatically removed from the list of event * sources and will not be called again. * @@ -19227,13 +19308,15 @@ /** * 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. + * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. * @function: function to call * @data: data to pass to @function * @notify: (nullable): function to call when the idle is removed, or %NULL * * Adds a function to be called whenever there are no higher priority - * events pending. If the function returns %FALSE it is automatically + * events pending. + * + * If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically * removed from the list of event sources and will not be called again. * * See [memory management of sources][mainloop-memory-management] for details @@ -21599,11 +21682,11 @@ /** * g_log: - * @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL - * for the default + * @log_domain: (nullable): the log domain, usually %G_LOG_DOMAIN, or %NULL + * for the default * @log_level: the log level, either from #GLogLevelFlags - * or a user-defined level - * @format: the message format. See the printf() documentation + * or a user-defined level + * @format: the message format. See the `printf()` documentation * @...: the parameters to insert into the format string * * Logs an error or debugging message. @@ -21741,40 +21824,44 @@ /** * g_log_set_handler: * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain + * 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. + * 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 * * Sets the log handler for a domain and a set of log levels. + * * To handle fatal and recursive messages the @log_levels parameter - * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION + * must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION * bit flags. * - * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if + * Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if * you want to set a handler for this log level you must combine it with - * #G_LOG_FLAG_FATAL. + * %G_LOG_FLAG_FATAL. * * This has no effect if structured logging is enabled; see * [Using Structured Logging][using-structured-logging]. * * 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); * ]| * * 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); * ]| * * 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); @@ -21787,11 +21874,11 @@ /** * g_log_set_handler_full: (rename-to g_log_set_handler) * @log_domain: (nullable): the log domain, or %NULL for the default "" - * application domain + * 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. + * 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 * @destroy: destroy notify for @user_data, or %NULL @@ -21836,10 +21923,12 @@ * by the key "MESSAGE", followed by a printf()-style message format, * followed by parameters to insert in the format string * - * Log a message with structured data. The message will be passed through to - * the log writer set by the application using g_log_set_writer_func(). If the - * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will - * be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns + * Log a message with structured data. + * + * The message will be passed through to the log writer set by the application + * using g_log_set_writer_func(). If the message is fatal (i.e. its log level + * is %G_LOG_LEVEL_ERROR), the program will be aborted by calling + * G_BREAKPOINT() at the end of this function. If the log writer returns * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. * See the documentation for #GLogWriterFunc for information on chaining * writers. @@ -21873,9 +21962,10 @@ * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including - * glib.h. + * `glib.h`. * * For example: + * * |[<!-- language="C" --> * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", @@ -21896,6 +21986,7 @@ * interpreted as a string. * * For example: + * * |[<!-- language="C" --> * const GLogField fields[] = { * { "MESSAGE", "This is a debug message.", -1 }, @@ -22398,7 +22489,7 @@ * * In any other case, an idle source is created to call @function and * that source is attached to @context (presumably to be run in another - * thread). The idle source is attached with #G_PRIORITY_DEFAULT + * thread). The idle source is attached with %G_PRIORITY_DEFAULT * priority. If you want a different priority, use * g_main_context_invoke_full(). * @@ -25314,7 +25405,7 @@ /** - * g_pattern_match: + * g_pattern_match: (skip) * @pspec: a #GPatternSpec * @string_length: the length of @string (in bytes, i.e. strlen(), * not g_utf8_strlen()) @@ -25340,6 +25431,7 @@ * g_utf8_strreverse() function to reverse UTF-8 encoded strings. * * Returns: %TRUE if @string matches @pspec + * Deprecated: 2.70: Use g_pattern_spec_match() instead */ @@ -25358,7 +25450,7 @@ /** - * g_pattern_match_string: + * g_pattern_match_string: (skip) * @pspec: a #GPatternSpec * @string: the UTF-8 encoded string to match * @@ -25367,6 +25459,18 @@ * g_pattern_match() instead while supplying the reversed string. * * Returns: %TRUE if @string matches @pspec + * Deprecated: 2.70: Use g_pattern_spec_match_string() instead + */ + + +/** + * g_pattern_spec_copy: + * @pspec: a #GPatternSpec + * + * Copies @pspec in a new #GPatternSpec. + * + * Returns: (transfer full): a copy of @pspec. + * Since: 2.70 */ @@ -25391,6 +25495,51 @@ /** + * g_pattern_spec_match: + * @pspec: a #GPatternSpec + * @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: (nullable): the reverse of @string or %NULL + * + * Matches a string against a compiled pattern. Passing the correct + * length of the string given is mandatory. The reversed string can be + * omitted by passing %NULL, this is more efficient if the reversed + * version of the string to be matched is not at hand, as + * g_pattern_match() will only construct it if the compiled pattern + * requires reverse matches. + * + * Note that, if the user code will (possibly) match a string against a + * multitude of patterns containing wildcards, chances are high that + * some patterns will require a reversed string. In this case, it's + * more efficient to provide the reversed string to avoid multiple + * constructions thereof in the various calls to g_pattern_match(). + * + * Note also that the reverse of a UTF-8 encoded string can in general + * 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 + * Since: 2.70 + */ + + +/** + * g_pattern_spec_match_string: + * @pspec: a #GPatternSpec + * @string: the UTF-8 encoded string to match + * + * Matches a string against a compiled pattern. If the string is to be + * matched against more than one pattern, consider using + * g_pattern_match() instead while supplying the reversed string. + * + * Returns: %TRUE if @string matches @pspec + * Since: 2.70 + */ + + +/** * g_pattern_spec_new: * @pattern: a zero-terminated UTF-8 encoded string * @@ -25411,6 +25560,9 @@ * For portability reasons, you may only lock on the bottom 32 bits of * the pointer. * + * While @address has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. + * * Since: 2.30 */ @@ -25420,12 +25572,15 @@ * @address: (not nullable): a pointer to a #gpointer-sized value * @lock_bit: a bit value between 0 and 31 * - * This is equivalent to g_bit_trylock, but working on pointers (or + * This is equivalent to g_bit_trylock(), but working on pointers (or * other pointer-sized values). * * For portability reasons, you may only lock on the bottom 32 bits of * the pointer. * + * While @address has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. + * * Returns: %TRUE if the lock was acquired * Since: 2.30 */ @@ -25442,6 +25597,9 @@ * For portability reasons, you may only lock on the bottom 32 bits of * the pointer. * + * While @address has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. + * * Since: 2.30 */ @@ -25495,6 +25653,18 @@ /** + * g_prefix_error_literal: + * @err: (allow-none): a return location for a #GError, or %NULL + * @prefix: string to prefix @err with + * + * Prefixes @prefix to an existing error message. If @err or *@err is + * %NULL (i.e.: no error variable) then do nothing. + * + * Since: 2.70 + */ + + +/** * g_print: * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string @@ -25715,7 +25885,7 @@ * g_ptr_array_find: (skip) * @haystack: pointer array to be searched * @needle: pointer to look for - * @index_: (optional) (out caller-allocates): return location for the index of + * @index_: (optional) (out): return location for the index of * the element, if found * * Checks whether @needle exists in @haystack. If the element is found, %TRUE is @@ -25738,7 +25908,7 @@ * @equal_func: (nullable): the function to call for each element, which should * return %TRUE when the desired element is found; or %NULL to use pointer * equality - * @index_: (optional) (out caller-allocates): return location for the index of + * @index_: (optional) (out): return location for the index of * the element, if found * * Checks whether @needle exists in @haystack, using the given @equal_func. @@ -26107,7 +26277,7 @@ /** * g_ptr_array_steal: * @array: a #GPtrArray. - * @len: (optional) (out caller-allocates): pointer to retrieve the number of + * @len: (optional) (out): pointer to retrieve the number of * elements of the original array * * Frees the data in the array and resets the size to zero, while @@ -27306,6 +27476,10 @@ * * Decreases the reference count. * + * If %TRUE is returned, the reference count reached 0. After this point, @rc + * is an undefined state and must be reinitialized with + * g_ref_count_init() to be used again. + * * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise * Since: 2.58 */ @@ -27325,7 +27499,7 @@ * g_ref_count_init: * @rc: the address of a reference count variable * - * Initializes a reference count variable. + * Initializes a reference count variable to 1. * * Since: 2.58 */ @@ -29366,12 +29540,16 @@ * Parses a command line into an argument vector, in much the same way * the shell would, but without many of the expansions the shell would * perform (variable expansion, globs, operators, filename expansion, - * etc. are not supported). The results are defined to be the same as - * those you would get from a UNIX98 /bin/sh, as long as the input - * contains none of the unsupported shell expansions. If the input - * does contain such expansions, they are passed through - * literally. Possible errors are those from the #G_SHELL_ERROR - * domain. Free the returned vector with g_strfreev(). + * etc. are not supported). + * + * The results are defined to be the same as those you would get from + * a UNIX98 `/bin/sh`, as long as the input contains none of the + * unsupported shell expansions. If the input does contain such expansions, + * they are passed through literally. + * + * Possible errors are those from the %G_SHELL_ERROR domain. + * + * Free the returned vector with g_strfreev(). * * Returns: %TRUE on success, %FALSE if error set */ @@ -29382,13 +29560,17 @@ * @unquoted_string: (type filename): a literal string * * Quotes a string so that the shell (/bin/sh) will interpret the - * quoted string to mean @unquoted_string. If you pass a filename to - * the shell, for example, you should first quote it with this - * function. The return value must be freed with g_free(). The - * quoting style used is undefined (single or double quotes may be + * quoted string to mean @unquoted_string. + * + * If you pass a filename to the shell, for example, you should first + * quote it with this function. + * + * The return value must be freed with g_free(). + * + * The quoting style used is undefined (single or double quotes may be * used). * - * Returns: (type filename): quoted string + * Returns: (type filename) (transfer full): quoted string */ @@ -29397,27 +29579,33 @@ * @quoted_string: (type filename): shell-quoted string * @error: error return location or NULL * - * Unquotes a string as the shell (/bin/sh) would. Only handles - * quotes; if a string contains file globs, arithmetic operators, - * variables, backticks, redirections, or other special-to-the-shell - * features, the result will be different from the result a real shell - * would produce (the variables, backticks, etc. will be passed - * through literally instead of being expanded). This function is - * guaranteed to succeed if applied to the result of + * Unquotes a string as the shell (/bin/sh) would. + * + * This function only handles quotes; if a string contains file globs, + * arithmetic operators, variables, backticks, redirections, or other + * special-to-the-shell features, the result will be different from the + * result a real shell would produce (the variables, backticks, etc. + * will be passed through literally instead of being expanded). + * + * This function is guaranteed to succeed if applied to the result of * g_shell_quote(). If it fails, it returns %NULL and sets the - * error. The @quoted_string need not actually contain quoted or - * escaped text; g_shell_unquote() simply goes through the string and - * unquotes/unescapes anything that the shell would. Both single and - * double quotes are handled, as are escapes including escaped - * newlines. The return value must be freed with g_free(). Possible - * errors are in the #G_SHELL_ERROR domain. + * error. + * + * The @quoted_string need not actually contain quoted or escaped text; + * g_shell_unquote() simply goes through the string and unquotes/unescapes + * anything that the shell would. Both single and double quotes are + * handled, as are escapes including escaped newlines. + * + * The return value must be freed with g_free(). + * + * Possible errors are in the %G_SHELL_ERROR domain. * * Shell quoting rules are a bit strange. Single quotes preserve the * literal string exactly. escape sequences are not allowed; not even - * \' - if you want a ' in the quoted text, you have to do something - * like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to - * be escaped with backslash. Otherwise double quotes preserve things - * literally. + * `\'` - if you want a `'` in the quoted text, you have to do something + * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and + * newline to be escaped with backslash. Otherwise double quotes + * preserve things literally. * * Returns: (type filename): an unquoted string */ @@ -29464,17 +29652,19 @@ * @block_size: the number of bytes to allocate * * Allocates a block of memory from the slice allocator. + * * The block address handed out can be expected to be aligned - * 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. + * 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 [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * - * Returns: a pointer to the allocated memory block, which will be %NULL if and - * only if @mem_size is 0 + * Returns: a pointer to the allocated memory block, which will + * be %NULL if and only if @mem_size is 0 * Since: 2.10 */ @@ -29579,6 +29769,7 @@ * @next: the field name of the next pointer in @type * * Frees a linked list of memory blocks of structure type @type. + * * The memory blocks must be equal-sized, allocated via * g_slice_alloc() or g_slice_alloc0() and linked together by * a @next pointer (similar to #GSList). The name of the @@ -30277,6 +30468,10 @@ * * This function is safe to call from any thread, regardless of which thread * the #GMainContext is running in. + * + * If the source is currently attached to a #GMainContext, destroying it + * will effectively unset the callback similar to calling g_source_set_callback(). + * This can mean, that the data's #GDestroyNotify gets called right away. */ @@ -30678,6 +30873,9 @@ * It is safe to call this function multiple times on a source which has already * been attached to a context. The changes will take effect for the next time * the source is dispatched after this call returns. + * + * Note that g_source_destroy() for a currently attached source has the effect + * of also unsetting the callback. */ @@ -30773,6 +30971,8 @@ * the value, and changing the value will free it while the other thread * may be attempting to use it. * + * Also see g_source_set_static_name(). + * * Since: 2.26 */ @@ -30853,6 +31053,19 @@ /** + * g_source_set_static_name: + * @source: a #GSource + * @name: debug name for the source + * + * A variant of g_source_set_name() that does not + * duplicate the @name, and can only be used with + * string literals. + * + * Since: 2.70 + */ + + +/** * g_source_unref: * @source: a #GSource * @@ -30892,13 +31105,15 @@ * @child_pid: (out) (optional): return location for child process reference, or %NULL * @error: return location for error * + * Executes a child program asynchronously. + * * See g_spawn_async_with_pipes() for a full description; this function * simply calls the g_spawn_async_with_pipes() without any pipes. * * You should call g_spawn_close_pid() on the returned child process * reference when you don't need it any more. * - * If you are writing a GTK+ application, and the program you are spawning is a + * If you are writing a GTK application, and the program you are spawning is a * graphical application too, then to ensure that the spawned program opens its * windows on the right screen, you may want to use #GdkAppLaunchContext, * #GAppLaunchContext, or set the %DISPLAY environment variable. @@ -30925,6 +31140,8 @@ * @stderr_fd: file descriptor to use for child's stderr, or `-1` * @error: return location for error * + * Executes a child program asynchronously. + * * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, * so no FD assignments are used. * @@ -30985,52 +31202,53 @@ * @error: return location for error * * 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 `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 - * @working_directory, if specified); this might be unexpected or even + * 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 `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 @working_directory, if specified); this might be unexpected or even * dangerous in some cases when the current directory is world-writable. * * On Windows, note that all the string or string vector arguments to - * this function and the other g_spawn*() functions are in UTF-8, the + * this function and the other `g_spawn*()` functions are in UTF-8, the * GLib file name encoding. Unicode characters that are not part of * the system codepage passed in these arguments will be correctly * available in the spawned program only if it uses wide character API * to retrieve its command line. For C programs built with Microsoft's - * tools it is enough to make the program have a wmain() instead of - * main(). wmain() has a wide character argument vector as parameter. + * tools it is enough to make the program have a `wmain()` instead of + * `main()`. `wmain()` has a wide character argument vector as parameter. * - * At least currently, mingw doesn't support wmain(), so if you use + * At least currently, mingw doesn't support `wmain()`, so if you use * mingw to develop the spawned program, it should call * g_win32_get_command_line() to get arguments in UTF-8. * - * On Windows the low-level child process creation API CreateProcess() + * 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() + * 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 + * passed to `main()`. Complications arise when you have argument vector * elements that contain spaces or 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. + * `spawn()` function. * * The returned @child_pid on Windows is a handle to the child * process, not its identifier. Process handles and process @@ -31049,13 +31267,13 @@ * free resources which may be associated with the child process. (On Unix, * using a child watch is equivalent to calling waitpid() or handling * the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid() - * is equivalent to calling CloseHandle() on the process handle returned + * is equivalent to calling `CloseHandle()` on the process handle returned * in @child_pid). See g_child_watch_add(). * * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that * other open file descriptors will be inherited by the child; otherwise all - * descriptors except stdin/stdout/stderr will be closed before calling exec() + * 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 @@ -31096,25 +31314,25 @@ * @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 + * 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. + * 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 + * `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 + * 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 WaitFor*() functions, or examine its exit code with - * GetExitCodeProcess(). You should close the handle with CloseHandle() + * 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 @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out @@ -31138,7 +31356,7 @@ * @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 - * @argv[0] is not found). Typically the `message` field of returned + * `@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. * @@ -31149,7 +31367,7 @@ * process reference must be closed using g_spawn_close_pid(). * * On modern UNIX platforms, GLib can use an efficient process launching - * codepath driven internally by posix_spawn(). This has the advantage of + * codepath driven internally by `posix_spawn()`. This has the advantage of * avoiding the fork-time performance costs of cloning the parent process * address space, and avoiding associated memory overcommit checks that are * not relevant in the context of immediately executing a distinct process. @@ -31161,9 +31379,11 @@ * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set * 4. @working_directory is %NULL * 5. @child_setup is %NULL - * 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. + * 6. The program is of a recognised binary format, or has a shebang. + * Otherwise, GLib will have to execute the program through the + * shell, which is not done using the optimized codepath. * - * If you are writing a GTK+ application, and the program you are spawning is a + * If you are writing a GTK application, and the program you are spawning is a * graphical application too, then to ensure that the spawned program opens its * windows on the right screen, you may want to use #GdkAppLaunchContext, * #GAppLaunchContext, or set the `DISPLAY` environment variable. @@ -31175,49 +31395,73 @@ /** * g_spawn_check_exit_status: - * @exit_status: An exit code as returned from g_spawn_sync() + * @wait_status: A status as returned from g_spawn_sync() + * @error: a #GError + * + * An old name for g_spawn_check_wait_status(), deprecated because its + * name is misleading. + * + * Despite the name of the function, @wait_status must be the wait status + * as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`, + * etc. On Unix platforms, it is incorrect for it to be the exit status + * as passed to `exit()` or returned by g_subprocess_get_exit_status() or + * `WEXITSTATUS()`. + * + * Returns: %TRUE if child exited successfully, %FALSE otherwise (and + * @error will be set) + * Since: 2.34 + * Deprecated: 2.70: Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses. + */ + + +/** + * g_spawn_check_wait_status: + * @wait_status: A platform-specific wait status as returned from g_spawn_sync() * @error: a #GError * - * Set @error if @exit_status indicates the child exited abnormally + * Set @error if @wait_status indicates the child exited abnormally * (e.g. with a nonzero exit code, or via a fatal signal). * - * The g_spawn_sync() and g_child_watch_add() family of APIs return an - * exit status for subprocesses encoded in a platform-specific way. + * The g_spawn_sync() and g_child_watch_add() family of APIs return the + * status of subprocesses encoded in a platform-specific way. * 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 + * @wait_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. + * human-readable information about the wait status. * * 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. + * @wait_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. * This allows you to differentiate between different exit codes. * * If the process was terminated by some means other than an exit - * status, the domain will be %G_SPAWN_ERROR, and the code will be - * %G_SPAWN_ERROR_FAILED. + * status (for example if it was killed by a signal), the domain will be + * %G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED. * * This function just offers convenience; you can of course also check * the available platform via a macro such as %G_OS_UNIX, and use - * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt + * WIFEXITED() and WEXITSTATUS() on @wait_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. * + * Prior to version 2.70, g_spawn_check_exit_status() provides the same + * functionality, although under a misleading name. + * * Returns: %TRUE if child exited successfully, %FALSE otherwise (and - * @error will be set) - * Since: 2.34 + * @error will be set) + * Since: 2.70 */ @@ -31238,8 +31482,9 @@ * @error: return location for errors * * A simple version of g_spawn_async() that parses a command line with - * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a - * command line in the background. Unlike g_spawn_async(), the + * g_shell_parse_argv() and passes it to g_spawn_async(). + * + * Runs a command line in the background. Unlike g_spawn_async(), the * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note * that %G_SPAWN_SEARCH_PATH can have security implications, so * consider using g_spawn_async() directly if appropriate. Possible @@ -31256,21 +31501,28 @@ * @command_line: (type filename): a command line * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors - * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid() + * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid() * @error: return location for errors * * A simple version of g_spawn_sync() with little-used parameters - * removed, taking a command line instead of an argument vector. See - * g_spawn_sync() for full details. @command_line will be parsed by - * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag - * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security - * implications, so consider using g_spawn_sync() directly if - * appropriate. Possible errors are those from g_spawn_sync() and those + * removed, taking a command line instead of an argument vector. + * + * See g_spawn_sync() for full details. + * + * The @command_line argument will be parsed by g_shell_parse_argv(). + * + * Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled. + * Note that %G_SPAWN_SEARCH_PATH can have security implications, so + * consider using g_spawn_sync() directly if appropriate. + * + * Possible errors are those from g_spawn_sync() and those * from g_shell_parse_argv(). * - * If @exit_status is non-%NULL, the platform-specific exit status of + * If @wait_status is non-%NULL, the platform-specific status of * the child is stored there; see the documentation of - * g_spawn_check_exit_status() for how to use and interpret this. + * g_spawn_check_wait_status() for how to use and interpret this. + * On Unix platforms, note that it is usually not equal + * to the integer passed to `exit()` or returned from `main()`. * * On Windows, please note the implications of g_shell_parse_argv() * parsing @command_line. Parsing is done according to Unix shell rules, not @@ -31299,24 +31551,28 @@ * @user_data: (closure): user data for @child_setup * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output, or %NULL * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child error messages, or %NULL - * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid(), or %NULL + * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid(), or %NULL * @error: return location for error, or %NULL * * Executes a child synchronously (waits for the child to exit before returning). + * * All output from the child is stored in @standard_output and @standard_error, * if those parameters are non-%NULL. Note that you must set the * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when * passing %NULL for @standard_output and @standard_error. * - * If @exit_status is non-%NULL, the platform-specific exit status of + * If @wait_status is non-%NULL, the platform-specific status of * the child is stored there; see the documentation of - * g_spawn_check_exit_status() for how to use and interpret this. + * g_spawn_check_wait_status() for how to use and interpret this. + * On Unix platforms, note that it is usually not equal + * to the integer passed to `exit()` or returned from `main()`. + * * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in * @flags, and on POSIX platforms, the same restrictions as for * g_child_watch_source_new() apply. * * If an error occurs, no data is returned in @standard_output, - * @standard_error, or @exit_status. + * @standard_error, or @wait_status. * * This function calls g_spawn_async_with_pipes() internally; see that * function for full details on the other parameters and details on @@ -31385,6 +31641,27 @@ /** + * g_steal_fd: + * @fd_ptr: (not optional) (inout): A pointer to a file descriptor + * + * Sets @fd_ptr to `-1`, returning the value that was there before. + * + * Conceptually, this transfers the ownership of the file descriptor + * from the referenced variable to the caller of the function (i.e. + * ‘steals’ the reference). This is very similar to g_steal_pointer(), + * but for file descriptors. + * + * On POSIX platforms, this function is async-signal safe + * (see [`signal(7)`](man:signal(7)) and + * [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a + * signal handler or a #GSpawnChildSetupFunc. + * + * Returns: the value that @fd_ptr previously had + * Since: 2.70 + */ + + +/** * g_stpcpy: * @dest: destination buffer. * @src: source string. @@ -31574,21 +31851,24 @@ * @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 + * 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", '?')) * ]| * - * In order to modify a copy, you may use `g_strdup()`: + * In order to modify a copy, you may use g_strdup(): + * * |[<!-- language="C" --> * reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); * ... * g_free (reformatted); * ]| * - * Returns: @string + * Returns: the modified @string */ @@ -31698,22 +31978,26 @@ * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. + * * Any characters in @string which are found in @delimiters are * changed to the @new_delimiter character. Modifies @string in place, - * and returns @string itself, not a copy. The return value is to - * allow nesting such as + * 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", '?')) * ]| * - * In order to modify a copy, you may use `g_strdup()`: + * In order to modify a copy, you may use g_strdup(): + * * |[<!-- language="C" --> * reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); * ... * g_free (reformatted); * ]| * - * Returns: @string + * Returns: the modified @string */ @@ -32377,8 +32661,13 @@ * * Replaces the string @find with the string @replace in a #GString up to * @limit times. If the number of instances of @find in the #GString is - * less than @limit, all instances are replaced. If the number of - * instances is `0`, all instances of @find are replaced. + * less than @limit, all instances are replaced. If @limit is `0`, + * all instances of @find are replaced. + * + * If @find is the empty string, since versions 2.69.1 and 2.68.4 the + * replacement will be inserted no more than once per possible position + * (beginning of string, end of string and between characters). This did + * not work correctly in earlier versions. * * Returns: the number of find and replace operations performed. * Since: 2.68 @@ -32841,6 +33130,28 @@ /** + * g_strv_builder_add_many: + * @builder: a #GStrvBuilder + * @...: one or more strings followed by %NULL + * + * Appends all the given strings to the builder. + * + * Since 2.70 + */ + + +/** + * g_strv_builder_addv: + * @builder: a #GStrvBuilder + * @value: (array zero-terminated=1): the vector of strings to add + * + * Appends all the strings in the given vector to the builder. + * + * Since 2.70 + */ + + +/** * g_strv_builder_end: * @builder: a #GStrvBuilder * @@ -33010,15 +33321,19 @@ /** * g_test_bug: - * @bug_uri_snippet: Bug specific bug tracker URI portion. + * @bug_uri_snippet: Bug specific bug tracker URI or URI portion. * * This function adds a message to test reports that * associates a bug URI with a test case. + * * Bug URIs are constructed from a base URI set with g_test_bug_base() * and @bug_uri_snippet. If g_test_bug_base() has not been called, it is * assumed to be the empty string, so a full URI can be provided to * g_test_bug() instead. * + * Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it + * is already a valid URI. + * * Since: 2.16: * See also: g_test_summary() */ @@ -33038,7 +33353,7 @@ * case only. * Bug URIs are constructed by appending a bug specific URI * portion to @uri_pattern, or by replacing the special string - * '\%s' within @uri_pattern if that is present. + * `%s` within @uri_pattern if that is present. * * If g_test_bug_base() is not called, bug URIs are formed solely * from the value provided by g_test_bug(). @@ -33082,6 +33397,16 @@ /** + * g_test_case_free: + * @test_case: a #GTestCase + * + * Free the @test_case. + * + * Since: 2.70 + */ + + +/** * g_test_create_case: * @test_name: the name for the test case * @data_size: the size of the fixture data structure @@ -33761,6 +34086,16 @@ /** + * g_test_suite_free: + * @suite: a #GTestSuite + * + * Free the @suite and all nested #GTestSuites. + * + * Since: 2.70 + */ + + +/** * g_test_summary: * @summary: One or two sentences summarising what the test checks, and how it * checks it. @@ -34296,6 +34631,28 @@ /** + * g_thread_pool_new_full: + * @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 + * @item_free_func: (nullable): used to pass as a free function to + * g_async_queue_new_full() + * @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 + * + * This function creates a new thread pool similar to g_thread_pool_new() + * but allowing @item_free_func to be specified to free the data passed + * to g_thread_pool_push() in the case that the #GThreadPool is stopped + * and freed before all tasks have been executed. + * + * Returns: (transfer full): the new #GThreadPool + * Since: 2.70 + */ + + +/** * g_thread_pool_push: * @pool: a #GThreadPool * @data: a new task for @pool @@ -34892,15 +35249,17 @@ /** * g_timeout_add: * @interval: the time between calls to the function, in milliseconds - * (1/1000ths of a second) + * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * * Sets a function to be called at regular intervals, with the default - * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly - * until it returns %FALSE, at which point the timeout is automatically - * destroyed and the function will not be called again. The first call - * to the function will be at the end of the first @interval. + * priority, %G_PRIORITY_DEFAULT. + * + * The given @function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed and the + * function will not be called again. The first call to the function will be + * at the end of the first @interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. @@ -34934,9 +35293,9 @@ /** * 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. + * 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) + * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * @notify: (nullable): function to call when the timeout is removed, or %NULL @@ -34977,8 +35336,10 @@ * @data: data to pass to @function * * Sets a function to be called at regular intervals with the default - * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until - * it returns %FALSE, at which point the timeout is automatically destroyed + * priority, %G_PRIORITY_DEFAULT. + * + * The function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed * and the function will not be called again. * * This internally creates a main loop source using @@ -35006,24 +35367,25 @@ /** * 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. + * 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 * @notify: (nullable): function to call when the timeout is removed, or %NULL * * Sets a function to be called at regular intervals, with @priority. - * The function is called repeatedly until it returns %FALSE, at which - * point the timeout is automatically destroyed and the function will - * not be called again. + * + * The function is called repeatedly until it returns %G_SOURCE_REMOVE + * or %FALSE, at which point the timeout is automatically destroyed and + * the function will not be called again. * * Unlike g_timeout_add(), this function operates at whole second granularity. * The initial starting point of the timer is determined by the implementation * and the implementation is expected to group multiple timers together so that - * they fire all at the same time. - * To allow this grouping, the @interval to the first timer is rounded - * and can deviate up to one second from the specified interval. - * Subsequent timer iterations will generally run at the specified interval. + * they fire all at the same time. To allow this grouping, the @interval to the + * first timer is rounded and can deviate up to one second from the specified + * interval. Subsequent timer iterations will generally run at the specified + * interval. * * Note that timeout functions may be delayed, due to the processing of other * event sources. Thus they should not be relied on for precise timing. @@ -35559,6 +35921,17 @@ /** + * g_tree_remove_all: + * @tree: a #GTree + * + * Removes all nodes from a #GTree and destroys their keys and values, + * then resets the #GTree’s root to %NULL. + * + * Since: 2.70 + */ + + +/** * g_tree_replace: * @tree: a #GTree * @key: the key to insert @@ -35783,10 +36156,10 @@ * @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: (out caller-allocates) (optional): location to store number of + * @items_read: (out) (optional): 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: (out caller-allocates) (optional): location to store number + * @items_written: (out) (optional): 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 @@ -35807,9 +36180,9 @@ * @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: (out caller-allocates) (optional): location to store number of + * @items_read: (out) (optional): location to store number of * characters read, or %NULL. - * @items_written: (out caller-allocates) (optional): location to store number + * @items_written: (out) (optional): 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 @@ -37498,11 +37871,11 @@ * @str: a UTF-16 encoded string * @len: the maximum length (number of #gunichar2) of @str to use. * If @len < 0, then the string is nul-terminated. - * @items_read: (out caller-allocates) (optional): location to store number of + * @items_read: (out) (optional): 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: (out caller-allocates) (optional): location to store number + * @items_written: (out) (optional): 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 @@ -37523,11 +37896,11 @@ * @str: a UTF-16 encoded string * @len: the maximum length (number of #gunichar2) of @str to use. * If @len < 0, then the string is nul-terminated. - * @items_read: (out caller-allocates) (optional): location to store number of + * @items_read: (out) (optional): 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: (out caller-allocates) (optional): location to store number + * @items_written: (out) (optional): 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 @@ -37967,13 +38340,13 @@ * @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: (out caller-allocates) (optional): location to store number of + * @items_read: (out) (optional): 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: (out caller-allocates) (optional): location to store number + * @items_written: (out) (optional): 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 @@ -37995,7 +38368,7 @@ * @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: (out caller-allocates) (optional): location to store the + * @items_written: (out) (optional): location to store the * number of characters in the result, or %NULL. * * Convert a string from UTF-8 to a 32-bit fixed width @@ -38014,11 +38387,11 @@ * @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: (out caller-allocates) (optional): location to store number of + * @items_read: (out) (optional): 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: (out caller-allocates) (optional): location to store number + * @items_written: (out) (optional): 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 @@ -38983,7 +39356,7 @@ * * Note that values borrowed from the returned child are not guaranteed to * still be valid after the child is freed even if you still hold a reference - * to @value, if @value has not been serialised at the time this function is + * to @value, if @value has not been serialized at the time this function is * called. To avoid this, you can serialize @value by calling * g_variant_get_data() and optionally ignoring the return value. * @@ -39003,33 +39376,33 @@ * g_variant_get_data: * @value: a #GVariant instance * - * Returns a pointer to the serialised form of a #GVariant instance. + * Returns a pointer to the serialized form of a #GVariant instance. * The returned data may not be in fully-normalised form if read from an * untrusted source. The returned data must not be freed; it remains * valid for as long as @value exists. * - * If @value is a fixed-sized value that was deserialised from a - * corrupted serialised container then %NULL may be returned. In this + * If @value is a fixed-sized value that was deserialized from a + * corrupted serialized container then %NULL may be returned. In this * case, the proper thing to do is typically to use the appropriate * number of nul bytes in place of @value. If @value is not fixed-sized * then %NULL is never returned. * - * In the case that @value is already in serialised form, this function - * is O(1). If the value is not already in serialised form, - * serialisation occurs implicitly and is approximately O(n) in the size + * In the case that @value is already in serialized form, this function + * is O(1). If the value is not already in serialized form, + * serialization occurs implicitly and is approximately O(n) in the size * of the result. * - * To deserialise the data returned by this function, in addition to the - * serialised data, you must know the type of the #GVariant, and (if the + * To deserialize the data returned by this function, in addition to the + * serialized data, you must know the type of the #GVariant, and (if the * machine might be different) the endianness of the machine that stored * it. As a result, file formats or network messages that incorporate - * serialised #GVariants must include this information either + * serialized #GVariants must include this information either * implicitly (for instance "the file always contains a * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or * explicitly (by storing the type and/or endianness in addition to the - * serialised data). + * serialized data). * - * Returns: (transfer none): the serialised form of @value, or %NULL + * Returns: (transfer none): the serialized form of @value, or %NULL * Since: 2.24 */ @@ -39038,7 +39411,7 @@ * g_variant_get_data_as_bytes: * @value: a #GVariant * - * Returns a pointer to the serialised form of a #GVariant instance. + * Returns a pointer to the serialized 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. @@ -39068,7 +39441,7 @@ * @n_elements: (out): a pointer to the location to store the number of items * @element_size: the size of each element * - * Provides access to the serialised data for an array of fixed-sized + * Provides access to the serialized data for an array of fixed-sized * items. * * @value must be an array with fixed-sized elements. Numeric types are @@ -39076,7 +39449,7 @@ * * @element_size must be the size of a single element in the array, * as given by the section on - * [serialized data memory][gvariant-serialised-data-memory]. + * [serialized data memory][gvariant-serialized-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 the size @@ -39089,7 +39462,7 @@ * * 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 + * of a double-check that the form of the serialized data matches the caller's * expectation. * * @n_elements, which must be non-%NULL, is set equal to the number of @@ -39191,7 +39564,7 @@ * #GVariant is created with the same value as @value. * * It makes sense to call this function if you've received #GVariant - * data from untrusted sources and you want to ensure your serialised + * data from untrusted sources and you want to ensure your serialized * output is definitely in normal form. * * If @value is already in normal form, a new reference will be returned @@ -39237,13 +39610,13 @@ * If @value has a fixed-sized type then this function always returned * that fixed size. * - * In the case that @value is already in serialised form or the size has + * In the case that @value is already in serialized form or the size has * already been calculated (ie: this function has been called before) * then this function is O(1). Otherwise, the size is calculated, an * operation which is approximately O(n) in the number of values * involved. * - * Returns: the serialised size of @value + * Returns: the serialized size of @value * Since: 2.24 */ @@ -39473,7 +39846,7 @@ * Checks if @value is in normal form. * * The main reason to do this is to detect if a given chunk of - * serialised data is in normal form: load the data into a #GVariant + * serialized data is in normal form: load the data into a #GVariant * using g_variant_new_from_data() and then use this function to * check. * @@ -40027,7 +40400,7 @@ * @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 + * of a double-check that the form of the serialized data matches the caller's * expectation. * * @n_elements must be the length of the @elements array. @@ -40043,8 +40416,8 @@ * @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 + * Constructs a new serialized-mode #GVariant instance. This is the + * inner interface for creation of new serialized values that gets * called from various functions in gvariant.c. * * A reference is taken on @bytes. @@ -40061,13 +40434,13 @@ /** * g_variant_new_from_data: * @type: a definite #GVariantType - * @data: (array length=size) (element-type guint8): the serialised data + * @data: (array length=size) (element-type guint8): the serialized data * @size: the size of @data * @trusted: %TRUE if @data is definitely in normal form * @notify: (scope async): function to call when @data is no longer needed * @user_data: data for @notify * - * Creates a new #GVariant instance from serialised data. + * Creates a new #GVariant instance from serialized data. * * @type is the type of #GVariant instance that will be constructed. * The interpretation of @data depends on knowing the type. @@ -40077,8 +40450,8 @@ * @user_data. If the contents of @data change before that time then * the result is undefined. * - * If @data is trusted to be serialised data in normal form then - * @trusted should be %TRUE. This applies to serialised data created + * If @data is trusted to be serialized data in normal form then + * @trusted should be %TRUE. This applies to serialized data created * within this process or read from a trusted location on the disk (such * as a file installed in /usr/lib alongside your application). You * should set trusted to %FALSE if @data is read from the network, a @@ -40651,17 +41024,17 @@ /** * g_variant_store: * @value: the #GVariant to store - * @data: (not nullable): the location to store the serialised data at + * @data: (not nullable): the location to store the serialized data at * - * Stores the serialised form of @value at @data. @data should be + * Stores the serialized form of @value at @data. @data should be * large enough. See g_variant_get_size(). * * The stored data is in machine native byte order but may not be in * fully-normalised form if read from an untrusted source. See * g_variant_get_normal_form() for a solution. * - * As with g_variant_get_data(), to be able to deserialise the - * serialised variant successfully, its type and (if the destination + * As with g_variant_get_data(), to be able to deserialize the + * serialized variant successfully, its type and (if the destination * machine might be different) its endianness must also be available. * * This function is approximately O(n) in the size of @data. @@ -41918,24 +42291,25 @@ * @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 - * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION - * as the three arguments to this function; that produces - * a check that the library in use is compatible with - * the version of GLib the application or module was compiled - * against. + * given version. + * + * Generally you would pass in the constants %GLIB_MAJOR_VERSION, + * %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments + * to this function; that produces a check that the library in use + * is compatible with the version of GLib the application or module + * was compiled against. * * Compatibility is defined by two things: first the version * of the running library is newer than the version - * @required_major.required_minor.@required_micro. Second + * `@required_major.required_minor.@required_micro`. Second * the running library must be binary compatible with the - * version @required_major.required_minor.@required_micro + * 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: (transfer none) (nullable): %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 */ diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c index dbacb484..988a8b0f 100644 --- a/gir/gmodule-2.0.c +++ b/gir/gmodule-2.0.c @@ -37,6 +37,15 @@ /** + * G_MODULE_ERROR: + * + * The error domain of the #GModule API. + * + * Since: 2.70 + */ + + +/** * G_MODULE_EXPORT: * * Used to declare functions exported by libraries or modules. @@ -218,22 +227,37 @@ * @file_name: (nullable): 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. + * + * A thin wrapper function around g_module_open_full() + * + * Returns: a #GModule on success, or %NULL on failure + */ + + +/** + * g_module_open_full: + * @file_name: (nullable): 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 + * @error: #GError. * * 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. + * First of all g_module_open_full() 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 opened. If that fails and @file_name doesn't have the - * ".la"-suffix, this suffix is appended and g_module_open() tries to open + * ".la"-suffix, this suffix is appended and g_module_open_full() tries to open * the corresponding module. If eventually that fails as well, %NULL is * returned. * * Returns: a #GModule on success, or %NULL on failure + * Since: 2.70 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index eaecc72d..93a4c7d3 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -75,11 +75,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 * [canonical parameter names][canonical-parameter-names] as * detail strings for the notify signal. @@ -90,20 +92,22 @@ * GParamSpecPool: * * 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. + * 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. */ /** * GWeakRef: * - * A structure containing a weak reference to a #GObject. It can either - * be empty (i.e. point to %NULL), or point to an object for as long as - * at least one "strong" reference to that object exists. Before the - * object's #GObjectClass.dispose method is called, every #GWeakRef - * associated with becomes empty (i.e. points to %NULL). + * A structure containing a weak reference to a #GObject. + * + * A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an + * object for as long as at least one "strong" reference to that object + * exists. Before the object's #GObjectClass.dispose method is called, + * every #GWeakRef associated with becomes empty (i.e. points to %NULL). * * Like #GValue, #GWeakRef can be statically allocated, stack- or * heap-allocated, or embedded in larger structures. @@ -166,9 +170,10 @@ * * #GBinding is the representation of a binding between a property on a * #GObject instance (or source) and another property on another #GObject - * instance (or target). Whenever the source property changes, the same - * value is applied to the target property; for instance, the following - * binding: + * instance (or target). + * + * Whenever the source property changes, the same value is applied to the + * target property; for instance, the following binding: * * |[<!-- language="C" --> * g_object_bind_property (object1, "property-a", @@ -251,10 +256,11 @@ * @see_also: #GParamSpecBoxed, g_param_spec_boxed() * @title: Boxed Types * - * #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only - * thing the type system needs to know about the structures is how to copy them - * (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that - * they are treated as opaque chunks of memory. + * #GBoxed is a generic wrapper mechanism for arbitrary C structures. + * + * The only thing the type system needs to know about the structures is how to + * copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc); + * beyond that, they are treated as opaque chunks of memory. * * Boxed types are useful for simple value-holder structures like rectangles or * points. They can also be used for wrapping structures defined in non-#GObject @@ -277,8 +283,9 @@ * @short_description: Functions as first-class objects * @title: Closures * - * A #GClosure represents a callback supplied by the programmer. It - * will generally comprise a function of some kind and a marshaller + * 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 responsibility of the marshaller to * convert the arguments for the invocation from #GValues into * a suitable form, perform the callback on the converted arguments, @@ -336,11 +343,16 @@ * * The #GValue structure is basically a variable container that consists * of a type identifier and a specific value of that type. + * * The type identifier within a #GValue structure always determines the * type of the associated value. + * * To create an undefined #GValue structure, simply create a zero-filled * #GValue structure. To initialize the #GValue, use the g_value_init() - * function. A #GValue cannot be used until it is initialized. + * function. A #GValue cannot be used until it is initialized. Before + * destruction you must always use g_value_unset() to make sure allocated + * memory is freed. + * * The basic type operations (such as freeing and copying) are determined * by the #GTypeValueTable associated with the type ID stored in the #GValue. * Other #GValue operations (such as converting values between types) are @@ -403,6 +415,34 @@ * return 0; * } * ]| + * + * See also [gobject-Standard-Parameter-and-Value-Types] for more information on + * validation of #GValue. + * + * For letting a #GValue own (and memory manage) arbitrary types or pointers, + * they need to become a [boxed type][gboxed]. The example below shows how + * the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed]. + * + * |[<!-- language="C" --> + * typedef struct { ... } MyStruct; + * G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) + * + * // These two lines normally go in a public header. By GObject convention, + * // the naming scheme is NAMESPACE_TYPE_NAME: + * #define MY_TYPE_STRUCT (my_struct_get_type ()) + * GType my_struct_get_type (void); + * + * void + * foo () + * { + * GValue *value = g_new0 (GValue, 1); + * g_value_init (value, MY_TYPE_STRUCT); + * g_value_set_boxed (value, mystruct); + * // [... your code ....] + * g_value_unset (value); + * g_value_free (value); + * } + * ]| */ @@ -436,7 +476,7 @@ * management system * @title: Type Information * - * The GType API is the foundation of the GObject system. It provides the + * 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. * @@ -483,16 +523,20 @@ * @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. + * 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. + * reference cannot be released from within the 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 @@ -517,9 +561,10 @@ * @see_also: #GTypeModule and g_type_register_dynamic(). * @title: GTypePlugin * + * An interface that handles the lifecycle of dynamically loaded types. + * * 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: + * 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 @@ -600,15 +645,18 @@ * 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 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 (); @@ -616,6 +664,7 @@ * 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 @@ -680,6 +729,8 @@ * 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. + * + * See also #GValue for more information. */ @@ -969,8 +1020,14 @@ * @boxed_free: Boxed structure free function. * * This function creates a new %G_TYPE_BOXED derived type id for a new - * boxed type with name @name. Boxed type handling functions have to be - * provided to copy and free opaque boxed structures of this type. + * boxed type with name @name. + * + * Boxed type handling functions have to be provided to copy and free + * opaque boxed structures of this type. + * + * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE + * instead of calling g_boxed_type_register_static() directly. The macro + * will create the appropriate `*_get_type()` function for the boxed type. * * Returns: New %G_TYPE_BOXED derived type id for @name. */ @@ -1909,11 +1966,12 @@ * @notify_func: the callback function to register * * Registers a finalization notifier which will be called when the - * reference count of @closure goes down to 0. Multiple finalization - * notifiers on a single closure are invoked in unspecified order. If - * a single call to g_closure_unref() results in the closure being - * both invalidated and finalized, then the invalidate notifiers will - * be run before the finalize notifiers. + * reference count of @closure goes down to 0. + * + * Multiple finalization notifiers on a single closure are invoked in + * unspecified order. If a single call to g_closure_unref() results in + * the closure being both invalidated and finalized, then the invalidate + * notifiers will be run before the finalize notifiers. */ @@ -1924,9 +1982,10 @@ * @notify_func: the callback function to register * * Registers an invalidation notifier which will be called when the - * @closure is invalidated with g_closure_invalidate(). Invalidation - * notifiers are invoked before finalization notifiers, in an - * unspecified order. + * @closure is invalidated with g_closure_invalidate(). + * + * Invalidation notifiers are invoked before finalization notifiers, + * in an unspecified order. */ @@ -1941,9 +2000,11 @@ * @post_marshal_notify: a function to call after the closure callback * * Adds a pair of notifiers which get invoked before and after the - * closure callback, respectively. This is typically used to protect - * the extra arguments for the duration of the callback. See - * g_object_watch_closure() for an example of marshal guards. + * closure callback, respectively. + * + * This is typically used to protect the extra arguments for the + * duration of the callback. See g_object_watch_closure() for an + * example of marshal guards. */ @@ -1954,7 +2015,9 @@ * Sets a flag on the closure to indicate that its calling * environment has become invalid, and thus causes any future * invocations of g_closure_invoke() on this @closure to be - * ignored. Also, invalidation notifiers installed on the closure will + * ignored. + * + * Also, invalidation notifiers installed on the closure will * be called at this point. Note that unless you are holding a * reference to the closure yourself, the invalidation notifiers may * unref the closure and cause it to be destroyed, so if you need to @@ -1970,7 +2033,7 @@ /** * g_closure_invoke: * @closure: a #GClosure - * @return_value: (optional) (out): a #GValue to store the return + * @return_value: (optional) (inout): 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 @@ -2006,8 +2069,9 @@ * @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. + * part as a #GClosure. + * + * This function is mainly useful when implementing new types of closures: * * |[<!-- language="C" --> * typedef struct _MyClosure MyClosure; @@ -2088,12 +2152,16 @@ * @closure: a #GClosure * @marshal: a #GClosureMarshal function * - * 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_*() + * Sets the marshaller of @closure. + * + * The `marshal_data` of @marshal provides a way for a meta marshaller to + * provide additional information to the marshaller. + * + * For GObject's C predefined marshallers (the `g_cclosure_marshal_*()` * functions), what it provides is a callback function to use instead of * @closure->callback. + * + * See also: g_closure_set_meta_marshal() */ @@ -2104,12 +2172,15 @@ * to @meta_marshal * @meta_marshal: a #GClosureMarshal function * - * 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. + * Sets the meta marshaller of @closure. + * + * A meta marshaller wraps the @closure's 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 [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 + * differs. In most cases we want to use the @closure's callback, but in * other cases we want to use some different technique to retrieve the * callback function. * @@ -2126,27 +2197,34 @@ * @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 "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: + * Takes over the initial ownership of a closure. + * + * Each closure is initially created in a "floating" state, which means + * that the initial reference count is not owned by any caller. + * + * This function 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); // 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(). An example * of storing a closure for later notification looks like: + * * |[<!-- language="C" --> * static GClosure *notify_closure = NULL; * void @@ -2174,8 +2252,10 @@ * @closure: #GClosure to decrement the reference count on * * Decrements the reference count of a closure after it was previously - * incremented by the same caller. If no other callers are using the - * closure, then the closure will be destroyed and freed. + * incremented by the same caller. + * + * If no other callers are using the closure, then the closure will be + * destroyed and freed. */ @@ -2432,10 +2512,12 @@ * @flags: flags to pass to #GBinding * * Creates a binding between @source_property on @source and @target_property - * on @target. Whenever the @source_property is changed the @target_property is + * on @target. + * + * Whenever the @source_property is changed the @target_property is * updated using the same value. For instance: * - * |[ + * |[<!-- language="C" --> * g_object_bind_property (action, "active", widget, "sensitive", 0); * ]| * @@ -3221,7 +3303,8 @@ * @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 + * @data: (nullable): data to pass to @notify, or %NULL to + * match any toggle refs with the @notify argument. * * Removes a reference added with g_object_add_toggle_ref(). The * reference count of the object is decreased by one. @@ -3497,6 +3580,51 @@ /** + * g_object_take_ref: (skip) + * @object: (type GObject.Object): a #GObject + * + * If @object is floating, sink it. Otherwise, do nothing. + * + * In other words, this function will convert a floating reference (if + * present) into a full reference. + * + * Typically you want to use g_object_ref_sink() in order to + * automatically do the correct thing with respect to floating or + * non-floating references, but there is one specific scenario where + * this function is helpful. + * + * The situation where this function is helpful is when creating an API + * that allows the user to provide a callback function that returns a + * GObject. We certainly want to allow the user the flexibility to + * return a non-floating reference from this callback (for the case + * where the object that is being returned already exists). + * + * At the same time, the API style of some popular GObject-based + * libraries (such as Gtk) make it likely that for newly-created GObject + * instances, the user can be saved some typing if they are allowed to + * return a floating reference. + * + * Using this function on the return value of the user's callback allows + * the user to do whichever is more convenient for them. The caller will + * alway receives exactly one full reference to the value: either the + * one that was returned in the first place, or a floating reference + * that has been converted to a full reference. + * + * This function has an odd interaction when combined with + * g_object_ref_sink() running at the same time in another thread on + * the same #GObject instance. If g_object_ref_sink() runs first then + * the result will be that the floating reference is converted to a hard + * reference. If g_object_take_ref() runs first then the result will be + * that the floating reference is converted to a hard reference and an + * additional reference on top of that one is added. It is best to avoid + * this situation. + * + * Since: 2.70 + * Returns: (type GObject.Object) (transfer full): @object + */ + + +/** * g_object_thaw_notify: * @object: a #GObject * @@ -4282,10 +4410,12 @@ * @name: 0-terminated string used as the name of the new #GParamSpec type. * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. * - * Registers @name as the name of a new static type derived from - * #G_TYPE_PARAM. The type system uses the information contained in - * the #GParamSpecTypeInfo structure pointed to by @info to manage the - * #GParamSpec type and its instances. + * Registers @name as the name of a new static type derived + * from #G_TYPE_PARAM. + * + * The type system uses the information contained in the #GParamSpecTypeInfo + * structure pointed to by @info to manage the #GParamSpec type and its + * instances. * * Returns: The new type identifier. */ @@ -6910,6 +7040,7 @@ * @v_boxed: (nullable): static boxed value to be set * * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + * * The boxed value is assumed to be static, and is thus not duplicated * when setting the #GValue. */ @@ -6934,7 +7065,7 @@ * @value: a valid #GValue of type %G_TYPE_STRING * @v_string: (nullable): caller-owned string to be duplicated for the #GValue * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + * Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string. */ |