[gobject-introspection] Update glib annotations
- From: Christoph Reiter <creiter src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Update glib annotations
- Date: Sat, 15 Jun 2019 18:09:44 +0000 (UTC)
commit b317c230fbd525760ad56d7435c7f9dc8bdf448d
Author: Christoph Reiter <reiter christoph gmail com>
Date: Sat Jun 15 20:08:53 2019 +0200
Update glib annotations
gir/gio-2.0.c | 224 +++++++++++-----
gir/glib-2.0.c | 775 ++++++++++++++++++++----------------------------------
gir/gobject-2.0.c | 105 ++++++--
3 files changed, 539 insertions(+), 565 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 99fa7a81..807d29f8 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -1486,6 +1486,9 @@
*
* #GDesktopAppInfoLookup is an opaque data structure and can only be accessed
* using the following functions.
+ *
+ * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and
+ * unused by GIO.
*/
@@ -5457,11 +5460,37 @@
* signals you are interested in. Note that new signals may be added
* in the future
*
- * ## Controlling Authentication # {#auth-observer}
+ * ## Controlling Authentication Mechanisms
+ *
+ * By default, a #GDBusServer or server-side #GDBusConnection will allow
+ * any authentication mechanism to be used. If you only
+ * want to allow D-Bus connections with the `EXTERNAL` mechanism,
+ * which makes use of credentials passing and is the recommended
+ * mechanism for modern Unix platforms such as Linux and the BSD family,
+ * you would use a signal handler like this:
+ *
+ * |[<!-- language="C" -->
+ * static gboolean
+ * on_allow_mechanism (GDBusAuthObserver *observer,
+ * const gchar *mechanism,
+ * gpointer user_data)
+ * {
+ * if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
+ * {
+ * return TRUE;
+ * }
+ *
+ * return FALSE;
+ * }
+ * ]|
+ *
+ * ## Controlling Authorization # {#auth-observer}
*
- * For example, if you only want to allow D-Bus connections from
- * processes owned by the same uid as the server, you would use a
- * signal handler like the following:
+ * By default, a #GDBusServer or server-side #GDBusConnection will accept
+ * connections from any successfully authenticated user (but not from
+ * anonymous connections using the `ANONYMOUS` mechanism). If you only
+ * want to allow D-Bus connections from processes owned by the same uid
+ * as the server, you would use a signal handler like the following:
*
* |[<!-- language="C" -->
* static gboolean
@@ -5949,6 +5978,11 @@
*
* An example of peer-to-peer communication with G-DBus can be found
* in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
+ *
+ * Note that a minimal #GDBusServer will accept connections from any
+ * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
+ * that only accepts connections that have successfully authenticated
+ * as the same user that is running the #GDBusServer.
*/
@@ -7075,6 +7109,10 @@
* then attempt to connect to that host, handling the possibility of
* multiple IP addresses and multiple address families.
*
+ * The enumeration results of resolved addresses *may* be cached as long
+ * as this object is kept alive which may have unexpected results if
+ * alive for too long.
+ *
* See #GSocketConnectable for an example of using the connectable
* interface.
*/
@@ -8341,7 +8379,7 @@
* #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
* instances. It is returned by enumeration functions such as
* g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
- * to list all the #GSocketAddresses which could be used to connect to that
+ * to list each #GSocketAddress which could be used to connect to that
* #GSocketConnectable.
*
* Enumeration is typically a blocking operation, so the asynchronous methods
@@ -9429,7 +9467,7 @@
* @short_description: TLS database type
* @include: gio/gio.h
*
- * #GTlsDatabase is used to lookup certificates and other information
+ * #GTlsDatabase is used to look up certificates and other information
* from a certificate or key store. It is an abstract base class which
* TLS library specific subtypes override.
*
@@ -9559,7 +9597,7 @@
* descriptors that it contains, closing them when finalized.
*
* It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in
- * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
+ * the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message()
* and received using g_socket_receive_message().
*
* Note that `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
@@ -9578,7 +9616,7 @@
* This #GSocketControlMessage contains a #GUnixFDList.
* It may be sent using g_socket_send_message() and received using
* g_socket_receive_message() over UNIX sockets (ie: sockets in the
- * %G_SOCKET_ADDRESS_UNIX family). The file descriptors are copied
+ * %G_SOCKET_FAMILY_UNIX family). The file descriptors are copied
* between processes by the kernel.
*
* For an easier way to send and receive file descriptors over
@@ -11049,7 +11087,7 @@
*
* The D-Bus–activated applications don't have to be started if your application
* terminates too soon after this function. To prevent this, use
- * g_app_info_launch_default_for_uri() instead.
+ * g_app_info_launch_default_for_uri_async() instead.
*
* Returns: %TRUE on success, %FALSE on error.
*/
@@ -18330,8 +18368,8 @@
/**
* g_dbus_object_manager_get_interface:
* @manager: A #GDBusObjectManager.
- * @object_path: Object path to lookup.
- * @interface_name: D-Bus interface name to lookup.
+ * @object_path: Object path to look up.
+ * @interface_name: D-Bus interface name to look up.
*
* Gets the interface proxy for @interface_name at @object_path, if
* any.
@@ -18345,7 +18383,7 @@
/**
* g_dbus_object_manager_get_object:
* @manager: A #GDBusObjectManager.
- * @object_path: Object path to lookup.
+ * @object_path: Object path to look up.
*
* Gets the #GDBusObjectProxy at @object_path, if any.
*
@@ -19214,6 +19252,10 @@
* Once constructed, you can use g_dbus_server_get_client_address() to
* get a D-Bus address string that clients can use to connect.
*
+ * To have control over the available authentication mechanisms and
+ * the users that are authorized to connect, it is strongly recommended
+ * to provide a non-%NULL #GDBusAuthObserver.
+ *
* Connect to the #GDBusServer::new-connection signal to handle
* incoming connections.
*
@@ -19222,8 +19264,8 @@
*
* #GDBusServer is used in this [example][gdbus-peer-to-peer].
*
- * This is a synchronous failable constructor. See
- * g_dbus_server_new() for the asynchronous version.
+ * This is a synchronous failable constructor. There is currently no
+ * asynchronous version.
*
* Returns: A #GDBusServer or %NULL if @error is set. Free with
* g_object_unref().
@@ -19474,7 +19516,7 @@
* Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full):
* a %NULL-terminated string array or %NULL if the specified
* key cannot be found. The array should be freed with g_strfreev().
- * Since: 2.60.0
+ * Since: 2.60
*/
@@ -19600,16 +19642,17 @@
* @uri_scheme: a string containing a URI scheme.
*
* Gets the default application for launching applications
- * using this URI scheme for a particular GDesktopAppInfoLookup
+ * using this URI scheme for a particular #GDesktopAppInfoLookup
* implementation.
*
- * The GDesktopAppInfoLookup interface and this function is used
+ * The #GDesktopAppInfoLookup interface and this function is used
* to implement g_app_info_get_default_for_uri_scheme() backends
* in a GIO module. There is no reason for applications to use it
* directly. Applications should use g_app_info_get_default_for_uri_scheme().
*
* Returns: (transfer full): #GAppInfo for given @uri_scheme or %NULL on error.
- * Deprecated: The #GDesktopAppInfoLookup interface is deprecated and unused by gio.
+ * Deprecated: 2.28: The #GDesktopAppInfoLookup interface is deprecated and
+ * unused by GIO.
*/
@@ -20819,7 +20862,7 @@
/**
* g_file_attribute_info_list_lookup:
* @list: a #GFileAttributeInfoList.
- * @name: the name of the attribute to lookup.
+ * @name: the name of the attribute to look up.
*
* Gets the file attribute with the name @name from @list.
*
@@ -22125,9 +22168,10 @@
*
* Gets the value of a attribute, formated as a string.
* This escapes things as needed to make the string valid
- * utf8.
+ * UTF-8.
*
- * Returns: a UTF-8 string associated with the given @attribute.
+ * Returns: (nullable): a UTF-8 string associated with the given @attribute, or
+ * %NULL if the attribute wasn’t set.
* When you're done with the string it must be freed with g_free().
*/
@@ -23258,7 +23302,7 @@
*
* By default, errors are only reported against the toplevel file
* itself. Errors found while recursing are silently ignored, unless
- * %G_FILE_DISK_USAGE_REPORT_ALL_ERRORS is given in @flags.
+ * %G_FILE_MEASURE_REPORT_ANY_ERROR is given in @flags.
*
* The returned size, @disk_usage, is in bytes and should be formatted
* with g_format_size() in order to get something reasonable for showing
@@ -23921,6 +23965,7 @@
/**
* g_file_query_default_handler_async:
* @file: a #GFile to open
+ * @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: optional #GCancellable object, %NULL to ignore
* @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
* @user_data: (nullable): data to pass to @callback
@@ -25894,8 +25939,8 @@
/**
* g_input_stream_read:
* @stream: a #GInputStream.
- * @buffer: (array length=count) (element-type guint8): a buffer to
- * read data into (which should be at least count bytes long).
+ * @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
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
@@ -25929,8 +25974,8 @@
/**
* g_input_stream_read_all:
* @stream: a #GInputStream.
- * @buffer: (array length=count) (element-type guint8): a buffer to
- * read data into (which should be at least count bytes long).
+ * @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
* @bytes_read: (out): location to store the number of bytes that was read from the stream
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
@@ -25963,8 +26008,8 @@
/**
* g_input_stream_read_all_async:
* @stream: A #GInputStream
- * @buffer: (array length=count) (element-type guint8): a buffer to
- * read data into (which should be at least count bytes long)
+ * @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
* @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
@@ -26011,8 +26056,8 @@
/**
* g_input_stream_read_async:
* @stream: A #GInputStream.
- * @buffer: (array length=count) (element-type guint8): a buffer to
- * read data into (which should be at least count bytes long).
+ * @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
* @io_priority: the [I/O priority][io-priority]
* of the request.
@@ -26228,7 +26273,7 @@
*
* Finishes a stream skip operation.
*
- * Returns: the size of the bytes skipped, or %-1 on error.
+ * Returns: the size of the bytes skipped, or `-1` on error.
*/
@@ -28647,7 +28692,7 @@
* Gets a choice from the mount operation.
*
* Returns: an integer containing an index of the user's choice from
- * the choice's list, or %0.
+ * the choice's list, or `0`.
*/
@@ -29037,7 +29082,7 @@
* resolving `localhost`, and an IPv6 address for `localhost6`.
*
* g_network_address_get_hostname() will always return `localhost` for
- * #GNetworkAddresses created with this constructor.
+ * a #GNetworkAddress created with this constructor.
*
* Returns: (transfer full) (type GNetworkAddress): the new #GNetworkAddress
* Since: 2.44
@@ -30953,8 +30998,8 @@
* g_proxy_get_default_for_protocol:
* @protocol: the proxy protocol name (e.g. http, socks, etc)
*
- * Lookup "gio-proxy" extension point for a proxy implementation that supports
- * specified protocol.
+ * Find the `gio-proxy` extension point for a proxy implementation that supports
+ * the specified protocol.
*
* Returns: (transfer full): return a #GProxy or NULL if protocol
* is not supported.
@@ -31349,8 +31394,8 @@
/**
* g_resolver_lookup_records:
* @resolver: a #GResolver
- * @rrname: the DNS name to lookup the record for
- * @record_type: the type of DNS record to lookup
+ * @rrname: the DNS name to look up the record for
+ * @record_type: the type of DNS record to look up
* @cancellable: (nullable): a #GCancellable, or %NULL
* @error: return location for a #GError, or %NULL
*
@@ -31376,8 +31421,8 @@
/**
* g_resolver_lookup_records_async:
* @resolver: a #GResolver
- * @rrname: the DNS name to lookup the record for
- * @record_type: the type of DNS record to lookup
+ * @rrname: the DNS name to look up the record for
+ * @record_type: the type of DNS record to look up
* @cancellable: (nullable): a #GCancellable, or %NULL
* @callback: (scope async): callback to call after resolution completes
* @user_data: (closure): data for @callback
@@ -32573,7 +32618,8 @@
* You should free the return value with g_strfreev() when you are done
* with it.
*
- * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Returns: (transfer full) (element-type utf8): a list of the children on
+ * @settings, in no defined order
*/
@@ -32590,7 +32636,9 @@
* You should free the return value with g_strfreev() when you are done
* with it.
*
- * Returns: (transfer full) (element-type utf8): a list of the keys on @settings
+ * Returns: (transfer full) (element-type utf8): a list of the keys on
+ * @settings, in no defined order
+ * Deprecated: 2.46: Use g_settings_schema_list_keys instead().
*/
@@ -32600,8 +32648,8 @@
* Deprecated.
*
* Returns: (element-type utf8) (transfer none): a list of relocatable
- * #GSettings schemas that are available. The list must not be
- * modified or freed.
+ * #GSettings schemas that are available, in no defined order. The list must
+ * not be modified or freed.
* Since: 2.28
* Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
*/
@@ -32613,8 +32661,8 @@
* Deprecated.
*
* Returns: (element-type utf8) (transfer none): a list of #GSettings
- * schemas that are available. The list must not be modified or
- * freed.
+ * schemas that are available, in no defined order. The list must not be
+ * modified or freed.
* Since: 2.26
* Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
* If you used g_settings_list_schemas() to check for the presence of
@@ -33007,7 +33055,8 @@
* You should free the return value with g_strfreev() when you are done
* with it.
*
- * Returns: (transfer full) (element-type utf8): a list of the children on @settings
+ * Returns: (transfer full) (element-type utf8): a list of the children on
+ * @settings, in no defined order
* Since: 2.44
*/
@@ -33023,7 +33072,7 @@
* function is intended for introspection reasons.
*
* Returns: (transfer full) (element-type utf8): a list of the keys on
- * @schema
+ * @schema, in no defined order
* Since: 2.46
*/
@@ -33066,9 +33115,9 @@
* @source: a #GSettingsSchemaSource
* @recursive: if we should recurse
* @non_relocatable: (out) (transfer full) (array zero-terminated=1): the
- * list of non-relocatable schemas
+ * list of non-relocatable schemas, in no defined order
* @relocatable: (out) (transfer full) (array zero-terminated=1): the list
- * of relocatable schemas
+ * of relocatable schemas, in no defined order
*
* Lists the schemas in a given source.
*
@@ -34759,7 +34808,7 @@
* The sockets created by this object will use of the specified
* protocol.
*
- * If @protocol is %0 that means to use the default
+ * If @protocol is %G_SOCKET_PROTOCOL_DEFAULT that means to use the default
* protocol for the socket family and type.
*
* Since: 2.22
@@ -35022,7 +35071,7 @@
* @connectable: a #GSocketConnectable
*
* Creates a #GSocketAddressEnumerator for @connectable that will
- * return #GProxyAddresses for addresses that you must connect
+ * return a #GProxyAddress for each of its addresses that you must connect
* to via a proxy.
*
* If @connectable does not implement
@@ -35364,6 +35413,13 @@
* the %G_IO_ERROR_NOT_SUPPORTED error. On Linux this is implemented
* by reading the %SO_PEERCRED option on the underlying socket.
*
+ * This method can be expected to be available on the following platforms:
+ *
+ * - Linux since GLib 2.26
+ * - OpenBSD since GLib 2.30
+ * - Solaris, Illumos and OpenSolaris since GLib 2.40
+ * - NetBSD since GLib 2.42
+ *
* Other ways to obtain credentials from a foreign peer includes the
* #GUnixCredentialsMessage type and
* g_unix_connection_send_credentials() /
@@ -36094,7 +36150,9 @@
* which may be filled with an array of #GSocketControlMessages, or %NULL
* @num_messages: (out): a pointer which will be filled with the number of
* elements in @messages, or %NULL
- * @flags: (type GSocketMsgFlags) (inout): a pointer to an int containing #GSocketMsgFlags flags
+ * @flags: (inout): a pointer to an int containing #GSocketMsgFlags flags,
+ * which may additionally contain
+ * [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
* @cancellable: a %GCancellable or %NULL
* @error: a #GError pointer, or %NULL
*
@@ -36169,7 +36227,9 @@
* @socket: a #GSocket
* @messages: (array length=num_messages): an array of #GInputMessage structs
* @num_messages: the number of elements in @messages
- * @flags: (type GSocketMsgFlags): an int containing #GSocketMsgFlags flags for the overall operation
+ * @flags: an int containing #GSocketMsgFlags flags for the overall operation,
+ * which may additionally contain
+ * [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
* @cancellable: (nullable): a %GCancellable or %NULL
* @error: #GError for error reporting, or %NULL to ignore
*
@@ -36290,7 +36350,8 @@
* @messages: (array length=num_messages) (nullable): a pointer to an
* array of #GSocketControlMessages, or %NULL.
* @num_messages: number of elements in @messages, or -1.
- * @flags: (type GSocketMsgFlags): an int containing #GSocketMsgFlags flags
+ * @flags: an int containing #GSocketMsgFlags flags, which may additionally
+ * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
* @cancellable: (nullable): a %GCancellable or %NULL
* @error: #GError for error reporting, or %NULL to ignore.
*
@@ -36347,7 +36408,8 @@
* @messages: (array length=num_messages) (nullable): a pointer to an
* array of #GSocketControlMessages, or %NULL.
* @num_messages: number of elements in @messages, or -1.
- * @flags: (type GSocketMsgFlags): an int containing #GSocketMsgFlags flags
+ * @flags: an int containing #GSocketMsgFlags flags, which may additionally
+ * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
* @timeout_us: the maximum time (in microseconds) to wait, or -1
* @bytes_written: (out) (optional): location to store the number of bytes that were written to the socket
* @cancellable: (nullable): a %GCancellable or %NULL
@@ -36373,7 +36435,8 @@
* @socket: a #GSocket
* @messages: (array length=num_messages): an array of #GOutputMessage structs
* @num_messages: the number of elements in @messages
- * @flags: (type GSocketMsgFlags): an int containing #GSocketMsgFlags flags
+ * @flags: an int containing #GSocketMsgFlags flags, which may additionally
+ * contain [other platform specific flags](http://man7.org/linux/man-pages/man2/recv.2.html)
* @cancellable: (nullable): a %GCancellable or %NULL
* @error: #GError for error reporting, or %NULL to ignore.
*
@@ -37053,6 +37116,11 @@
*
* On UNIX, returns the process ID as a decimal string.
* On Windows, returns the result of GetProcessId() also as a string.
+ * If the subprocess has terminated, this will return %NULL.
+ *
+ * Returns: (nullable): the subprocess identifier, or %NULL if the subprocess
+ * has terminated
+ * Since: 2.40
*/
@@ -39391,7 +39459,7 @@
* @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a #GError, or %NULL
*
- * Lookup a certificate by its handle.
+ * Look up a certificate by its handle.
*
* The handle should have been created by calling
* g_tls_database_create_certificate_handle() on a #GTlsDatabase object of
@@ -39420,7 +39488,7 @@
* @callback: callback to call when the operation completes
* @user_data: the data to pass to the callback function
*
- * Asynchronously lookup a certificate by its handle in the database. See
+ * Asynchronously look up a certificate by its handle in the database. See
* g_tls_database_lookup_certificate_for_handle() for more information.
*
* Since: 2.30
@@ -39434,7 +39502,7 @@
* @error: a #GError pointer, or %NULL
*
* Finish an asynchronous lookup of a certificate by its handle. See
- * g_tls_database_lookup_certificate_by_handle() for more information.
+ * g_tls_database_lookup_certificate_for_handle() for more information.
*
* If the handle is no longer valid, or does not point to a certificate in
* this database, then %NULL will be returned.
@@ -39454,7 +39522,7 @@
* @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a #GError, or %NULL
*
- * Lookup the issuer of @certificate in the database.
+ * 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
@@ -39479,7 +39547,7 @@
* @callback: callback to call when the operation completes
* @user_data: the data to pass to the callback function
*
- * Asynchronously lookup the issuer of @certificate in the database. See
+ * Asynchronously look up the issuer of @certificate in the database. See
* g_tls_database_lookup_certificate_issuer() for more information.
*
* Since: 2.30
@@ -39510,7 +39578,7 @@
* @cancellable: (nullable): a #GCancellable, or %NULL
* @error: (nullable): a #GError, or %NULL
*
- * Lookup certificates issued by this issuer in the database.
+ * Look up certificates issued by this issuer in the database.
*
* This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
* the lookup operation asynchronously.
@@ -39531,7 +39599,7 @@
* @callback: callback to call when the operation completes
* @user_data: the data to pass to the callback function
*
- * Asynchronously lookup certificates issued by this issuer in the database. See
+ * Asynchronously look up certificates issued by this issuer in the database. See
* g_tls_database_lookup_certificates_issued_by() for more information.
*
* The database may choose to hold a reference to the issuer byte array for the duration
@@ -40062,6 +40130,14 @@
* single byte from the stream, as this is required for credentials
* passing to work on some implementations.
*
+ * This method can be expected to be available on the following platforms:
+ *
+ * - Linux since GLib 2.26
+ * - FreeBSD since GLib 2.26
+ * - GNU/kFreeBSD since GLib 2.36
+ * - Solaris, Illumos and OpenSolaris since GLib 2.40
+ * - GNU/Hurd since GLib 2.40
+ *
* Other ways to exchange credentials with a foreign peer includes the
* #GUnixCredentialsMessage type and g_socket_get_credentials() function.
*
@@ -40139,6 +40215,14 @@
* byte to the stream, as this is required for credentials passing to
* work on some implementations.
*
+ * This method can be expected to be available on the following platforms:
+ *
+ * - Linux since GLib 2.26
+ * - FreeBSD since GLib 2.26
+ * - GNU/kFreeBSD since GLib 2.36
+ * - Solaris, Illumos and OpenSolaris since GLib 2.40
+ * - GNU/Hurd since GLib 2.40
+ *
* Other ways to exchange credentials with a foreign peer includes the
* #GUnixCredentialsMessage type and g_socket_get_credentials() function.
*
@@ -40581,6 +40665,9 @@
* is set, it will be filled with a unix timestamp for checking
* if the mounts have changed since with g_unix_mounts_changed_since().
*
+ * If more mounts have the same mount path, the last matching mount
+ * is returned.
+ *
* Returns: (transfer full): a #GUnixMountEntry.
*/
@@ -40617,6 +40704,9 @@
* is set, it will be filled with a unix timestamp for checking
* if the mounts have changed since with g_unix_mounts_changed_since().
*
+ * If more mounts have the same mount path, the last matching mount
+ * is returned.
+ *
* Returns: (transfer full): a #GUnixMountEntry.
* Since: 2.52
*/
@@ -42521,6 +42611,14 @@
*/
+/**
+ * inet_addresses_to_inet_socket_addresses:
+ * @addresses: (transfer full): #GList of #GInetAddress
+ *
+ * Returns: (transfer full): #GList of #GInetSocketAddress
+ */
+
+
/************************************************************/
/* THIS FILE IS GENERATED DO NOT EDIT */
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index efdeeaa0..22e375f8 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -2003,29 +2003,6 @@
*/
-/**
- * GTestTrapFlags:
- * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
- * `/dev/null` so it cannot be observed on the console during test
- * runs. The actual output is still captured though to allow later
- * tests with g_test_trap_assert_stdout().
- * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
- * `/dev/null` so it cannot be observed on the console during test
- * runs. The actual output is still captured though to allow later
- * tests with g_test_trap_assert_stderr().
- * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
- * child process is shared with stdin of its parent process.
- * It is redirected to `/dev/null` otherwise.
- *
- * Test traps are guards around forked tests.
- * These flags determine what traps to set.
- *
- * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
- * which is deprecated. g_test_trap_subprocess() uses
- * #GTestSubprocessFlags.
- */
-
-
/**
* GThread:
*
@@ -2098,6 +2075,9 @@
* time (&ttime);
* gtime = (GTime)ttime;
* ]|
+ *
+ * Deprecated: 2.62: This is not [Y2038-safe](https://en.wikipedia.org/wiki/Year_2038_problem).
+ * Use #GDateTime or #time_t instead.
*/
@@ -2736,24 +2716,6 @@
*/
-/**
- * G_ALIGNOF:
- * @a: a type-name
- *
- * Return the minimal alignment required by the platform ABI for values of the given
- * type. The address of a variable or struct member of the given type must always be
- * a multiple of this alignment. For example, most platforms require int variables
- * to be aligned at a 4-byte boundary, so `G_ALIGNOF (int)` is 4 on most platforms.
- *
- * Note this is not necessarily the same as the value returned by GCC’s
- * `__alignof__` operator, which returns the preferred alignment for a type.
- * The preferred alignment may be a stricter alignment than the minimal
- * alignment.
- *
- * Since: 2.60
- */
-
-
/**
* G_APPROX_VALUE:
* @a: a numeric value
@@ -2830,23 +2792,6 @@
*/
-/**
- * G_CONST_RETURN:
- *
- * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
- * to nothing. By default, the macro expands to const. The macro
- * can be used in place of const for functions that return a value
- * that should not be modified. The purpose of this macro is to allow
- * us to turn on const for returned constant strings by default, while
- * allowing programmers who find that annoying to turn it off. This macro
- * should only be used for return values and for "out" parameters, it
- * doesn't make sense for "in" parameters.
- *
- * Deprecated: 2.30: API providers should replace all existing uses with
- * const and API consumers should adjust their code accordingly
- */
-
-
/**
* G_CSET_A_2_Z:
*
@@ -2925,7 +2870,7 @@
* The function will not be called if the variable to be cleaned up
* contains %NULL.
*
- * This will typically be the _free() or _unref() function for the given
+ * This will typically be the `_free()` or `_unref()` function for the given
* type.
*
* With this definition, it will be possible to use g_autoptr() with
@@ -2949,7 +2894,7 @@
*
* Defines the appropriate cleanup function for a type.
*
- * This will typically be the _clear() function for the given type.
+ * This will typically be the `_clear()` function for the given type.
*
* With this definition, it will be possible to use g_auto() with
* @TypeName.
@@ -2982,7 +2927,7 @@
* and file descriptors.
*
* @none specifies the "none" value for the type in question. It is
- * probably something like %NULL or -1. If the variable is found to
+ * probably something like %NULL or `-1`. If the variable is found to
* contain this value then the free function will not be called.
*
* |[
@@ -3020,6 +2965,11 @@
* meant to be portable across different compilers and must be placed
* before the function declaration.
*
+ * |[<!-- language="C" --
+ * G_DEPRECATED
+ * int my_mistake (void);
+ * ]|
+ *
* Since: 2.32
*/
@@ -3033,6 +2983,11 @@
* is meant to be portable across different compilers and must be placed
* before the function declaration.
*
+ * |[<!-- language="C" --
+ * G_DEPRECATED_FOR(my_replacement)
+ * int my_mistake (void);
+ * ]|
+ *
* Since: 2.32
*/
@@ -3194,43 +3149,6 @@
*/
-/**
- * G_GNUC_ALLOC_SIZE:
- * @x: the index of the argument specifying the allocation size
- *
- * Expands to the GNU C alloc_size function attribute if the compiler
- * is a new enough gcc. This attribute tells the compiler that the
- * function returns a pointer to memory of a size that is specified
- * by the @xth function parameter.
- *
- * Place the attribute after the function declaration, just before the
- * semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * Since: 2.18
- */
-
-
-/**
- * G_GNUC_ALLOC_SIZE2:
- * @x: the index of the argument specifying one factor of the allocation size
- * @y: the index of the argument specifying the second factor of the allocation size
- *
- * Expands to the GNU C alloc_size function attribute if the compiler is a
- * new enough gcc. This attribute tells the compiler that the function returns
- * a pointer to memory of a size that is specified by the product of two
- * function parameters.
- *
- * Place the attribute after the function declaration, just before the
- * semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * Since: 2.18
- */
-
-
/**
* G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
*
@@ -3245,7 +3163,54 @@
* has any effect.)
*
* This macro can be used either inside or outside of a function body,
- * but must appear on a line by itself.
+ * but must appear on a line by itself. Both this macro and the corresponding
+ * %G_GNUC_END_IGNORE_DEPRECATIONS are considered statements, so they
+ * should not be used around branching or loop conditions; for instance,
+ * this use is invalid:
+ *
+ * |[<!-- language="C" -->
+ * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ * if (check == some_deprecated_function ())
+ * G_GNUC_END_IGNORE_DEPRECATIONS
+ * {
+ * do_something ();
+ * }
+ * ]|
+ *
+ * and you should move the deprecated section outside the condition
+ *
+ * |[<!-- language="C" -->
+ *
+ * // Solution A
+ * some_data_t *res;
+ *
+ * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ * res = some_deprecated_function ();
+ * G_GNUC_END_IGNORE_DEPRECATIONS
+ *
+ * if (check == res)
+ * {
+ * do_something ();
+ * }
+ *
+ * // Solution B
+ * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ * if (check == some_deprecated_function ())
+ * {
+ * do_something ();
+ * }
+ * G_GNUC_END_IGNORE_DEPRECATIONS
+ * ]|
+ *
+ * |[<!-- language="C" --
+ * static void
+ * test_deprecated_function (void)
+ * {
+ * G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+ * g_assert_cmpint (my_mistake (), ==, 42);
+ * G_GNUC_END_IGNORE_DEPRECATIONS
+ * }
+ * ]|
*
* Since: 2.32
*/
@@ -3269,62 +3234,6 @@
*/
-/**
- * G_GNUC_CONST:
- *
- * Expands to the GNU C const function attribute if the compiler is gcc.
- * Declaring a function as const enables better optimization of calls to
- * the function. A const function doesn't examine any values except its
- * parameters, and has no effects except its return value.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * A function that has pointer arguments and examines the data pointed to
- * must not be declared const. Likewise, a function that calls a non-const
- * function usually must not be const. It doesn't make sense for a const
- * function to return void.
- */
-
-
-/**
- * G_GNUC_DEPRECATED:
- *
- * Expands to the GNU C deprecated attribute if the compiler is gcc.
- * It can be used to mark typedefs, variables and functions as deprecated.
- * When called with the `-Wdeprecated-declarations` option,
- * gcc will generate warnings when deprecated interfaces are used.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * Since: 2.2
- */
-
-
-/**
- * G_GNUC_DEPRECATED_FOR:
- * @f: the intended replacement for the deprecated symbol,
- * such as the name of a function
- *
- * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
- * deprecated symbol if the version of gcc in use is new enough to support
- * custom deprecation messages.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * Note that if @f is a macro, it will be expanded in the warning message.
- * You can enclose it in quotes to prevent this. (The quotes will show up
- * in the warning, but it's better than showing the macro expansion.)
- *
- * Since: 2.26
- */
-
-
/**
* G_GNUC_END_IGNORE_DEPRECATIONS:
*
@@ -3348,56 +3257,6 @@
*/
-/**
- * G_GNUC_FALLTHROUGH:
- *
- * Expands to the GNU C fallthrough statement attribute if the compiler is gcc.
- * This allows declaring case statement to explicitly fall through in switch
- * statements. To enable this feature, use -Wimplicit-fallthrough during
- * compilation.
- *
- * Put the attribute right before the case statement you want to fall through
- * to.
- *
- * See the GNU C documentation for more details.
- *
- * Since: 2.60
- */
-
-
-/**
- * G_GNUC_FORMAT:
- * @arg_idx: the index of the argument
- *
- * Expands to the GNU C format_arg function attribute if the compiler
- * is gcc. This function attribute specifies that a function takes a
- * format string for a printf(), scanf(), strftime() or strfmon() style
- * function and modifies it, so that the result can be passed to a printf(),
- * scanf(), strftime() or strfmon() style function (with the remaining
- * arguments to the format function the same as they would have been
- * for the unmodified string).
- *
- * Place the attribute after the function declaration, just before the
- * semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * |[<!-- language="C" -->
- * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
- * ]|
- */
-
-
-/**
- * G_GNUC_FUNCTION:
- *
- * Expands to "" on all modern compilers, and to __FUNCTION__ on gcc
- * version 2.x. Don't use it.
- *
- * Deprecated: 2.16: Use G_STRFUNC() instead
- */
-
-
/**
* G_GNUC_INTERNAL:
*
@@ -3427,237 +3286,6 @@
*/
-/**
- * G_GNUC_MALLOC:
- *
- * Expands to the
- * [GNU C `malloc` function
attribute](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
- * if the compiler is gcc.
- * Declaring a function as `malloc` enables better optimization of the function,
- * but must only be done if the allocation behaviour of the function is fully
- * understood, otherwise miscompilation can result.
- *
- * A function can have the `malloc` attribute if it returns a pointer which is
- * guaranteed to not alias with any other pointer valid when the function
- * returns, and moreover no pointers to valid objects occur in any storage
- * addressed by the returned pointer.
- *
- * In practice, this means that `G_GNUC_MALLOC` can be used with any function
- * which returns unallocated or zeroed-out memory, but not with functions which
- * return initialised structures containing other pointers, or with functions
- * that reallocate memory. This definition changed in GLib 2.58 to match the
- * stricter definition introduced around GCC 5.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the
- * [GNU C
documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-functions-that-behave-like-malloc)
- * for more details.
- *
- * Since: 2.6
- */
-
-
-/**
- * G_GNUC_MAY_ALIAS:
- *
- * Expands to the GNU C may_alias type attribute if the compiler is gcc.
- * Types with this attribute will not be subjected to type-based alias
- * analysis, but are assumed to alias with any other type, just like char.
- *
- * See the GNU C documentation for details.
- *
- * Since: 2.14
- */
-
-
-/**
- * G_GNUC_NORETURN:
- *
- * Expands to the GNU C noreturn function attribute if the compiler is gcc.
- * It is used for declaring functions which never return. It enables
- * optimization of the function, and avoids possible compiler warnings.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- */
-
-
-/**
- * G_GNUC_NO_INLINE:
- *
- * Expands to the GNU C `noinline` function attribute if the compiler is gcc.
- * If the compiler is not gcc, this macro expands to nothing.
- *
- * Declaring a function as `noinline` prevents the function from being
- * considered for inlining.
- *
- * The attribute may be placed before the declaration, right before the
- * `static` keyword.
- *
- * See the
- * [GNU C
documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-noinline-function-attribute)
- * for more details.
- *
- * Since: 2.58
- */
-
-
-/**
- * G_GNUC_NO_INSTRUMENT:
- *
- * Expands to the GNU C no_instrument_function function attribute if the
- * compiler is gcc. Functions with this attribute will not be instrumented
- * for profiling, when the compiler is called with the
- * `-finstrument-functions` option.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- */
-
-
-/**
- * G_GNUC_NULL_TERMINATED:
- *
- * Expands to the GNU C sentinel function attribute if the compiler is gcc.
- * This function attribute only applies to variadic functions and instructs
- * the compiler to check that the argument list is terminated with an
- * explicit %NULL.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * Since: 2.8
- */
-
-
-/**
- * G_GNUC_PRETTY_FUNCTION:
- *
- * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
- * on gcc version 2.x. Don't use it.
- *
- * Deprecated: 2.16: Use G_STRFUNC() instead
- */
-
-
-/**
- * G_GNUC_PRINTF:
- * @format_idx: the index of the argument corresponding to the
- * format string (the arguments are numbered from 1)
- * @arg_idx: the index of the first of the format arguments, or 0 if
- * there are no format arguments
- *
- * Expands to the GNU C format function attribute if the compiler is gcc.
- * This is used for declaring functions which take a variable number of
- * arguments, with the same syntax as printf(). It allows the compiler
- * to type-check the arguments passed to the function.
- *
- * Place the attribute after the function declaration, just before the
- * semicolon.
- *
- * See the
- * [GNU C
documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
- * for more details.
- *
- * |[<!-- language="C" -->
- * gint g_snprintf (gchar *string,
- * gulong n,
- * gchar const *format,
- * ...) G_GNUC_PRINTF (3, 4);
- * ]|
- */
-
-
-/**
- * G_GNUC_PURE:
- *
- * Expands to the GNU C pure function attribute if the compiler is gcc.
- * Declaring a function as pure enables better optimization of calls to
- * the function. A pure function has no effects except its return value
- * and the return value depends only on the parameters and/or global
- * variables.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- */
-
-
-/**
- * G_GNUC_SCANF:
- * @format_idx: the index of the argument corresponding to
- * the format string (the arguments are numbered from 1)
- * @arg_idx: the index of the first of the format arguments, or 0 if
- * there are no format arguments
- *
- * Expands to the GNU C format function attribute if the compiler is gcc.
- * This is used for declaring functions which take a variable number of
- * arguments, with the same syntax as scanf(). It allows the compiler
- * to type-check the arguments passed to the function.
- *
- * See the
- * [GNU C
documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
- * for details.
- */
-
-
-/**
- * G_GNUC_STRFTIME:
- * @format_idx: the index of the argument corresponding to
- * the format string (the arguments are numbered from 1)
- *
- * Expands to the GNU C strftime format function attribute if the compiler
- * is gcc. This is used for declaring functions which take a format argument
- * which is passed to strftime() or an API implementing its formats. It allows
- * the compiler check the format passed to the function.
- *
- * See the
- * [GNU C
documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
- * for details.
- *
- * Since: 2.60
- */
-
-
-/**
- * G_GNUC_UNUSED:
- *
- * Expands to the GNU C unused function attribute if the compiler is gcc.
- * It is used for declaring functions and arguments which may never be used.
- * It avoids possible compiler warnings.
- *
- * For functions, place the attribute after the declaration, just before the
- * semicolon. For arguments, place the attribute at the beginning of the
- * argument declaration.
- *
- * |[<!-- language="C" -->
- * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
- * gint other_argument) G_GNUC_UNUSED;
- * ]|
- *
- * See the GNU C documentation for more details.
- */
-
-
-/**
- * G_GNUC_WARN_UNUSED_RESULT:
- *
- * Expands to the GNU C warn_unused_result function attribute if the compiler
- * is gcc. This function attribute makes the compiler emit a warning if the
- * result of a function call is ignored.
- *
- * Place the attribute after the declaration, just before the semicolon.
- *
- * See the GNU C documentation for more details.
- *
- * Since: 2.10
- */
-
-
/**
* G_GOFFSET_CONSTANT:
* @val: a literal integer value, e.g. 0x1d636b02300a7aa7
@@ -3875,21 +3503,6 @@
*/
-/**
- * G_INLINE_FUNC:
- *
- * This macro used to be used to conditionally define inline functions
- * in a compatible way before this feature was supported in all
- * compilers. These days, GLib requires inlining support from the
- * compiler, so your GLib-using programs can safely assume that the
- * "inline" keywork works properly.
- *
- * Never use this macro anymore. Just say "static inline".
- *
- * Deprecated: 2.48: Use "static inline" instead
- */
-
-
/**
* G_IO_CHANNEL_ERROR:
*
@@ -5247,7 +4860,7 @@
* g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
* }
*
- * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_clear)
+ * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
* ]|
*
* Since: 2.58.
@@ -6590,7 +6203,7 @@
* type information would be allocated.
*
* The type information cache, additionally, uses a #GHashTable to
- * store and lookup the cached items and stores a pointer to this
+ * store and look up the cached items and stores a pointer to this
* hash table in static storage. The hash table is freed when there
* are zero items in the type cache.
*
@@ -6833,7 +6446,7 @@
* To insert a key and value into a #GHashTable, use
* g_hash_table_insert().
*
- * To lookup a value corresponding to a given key, use
+ * To look up a value corresponding to a given key, use
* g_hash_table_lookup() and g_hash_table_lookup_extended().
*
* g_hash_table_lookup_extended() can also be used to simply
@@ -8131,7 +7744,7 @@
* g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear);
* }
*
- * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_clear)
+ * G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release)
* ]|
*
* Since: 2.58.
@@ -8457,7 +8070,6 @@
* SECTION:testing
* @title: Testing
* @short_description: a test framework
- * @see_also: [gtester][gtester], [gtester-report][gtester-report]
*
* GLib provides a framework for writing and maintaining unit tests
* in parallel to the code they are testing. The API is designed according
@@ -8632,7 +8244,10 @@
* If you don't have access to the Autotools TAP harness, you can use the
* [gtester][gtester] and [gtester-report][gtester-report] tools, and use
* the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk)
- * Automake template provided by GLib.
+ * Automake template provided by GLib. Note, however, that since GLib 2.62,
+ * [gtester][gtester] and [gtester-report][gtester-report] have been deprecated
+ * in favour of using TAP. The `--tap` argument to tests is enabled by default
+ * as of GLib 2.62.
*/
@@ -8855,7 +8470,7 @@
*
* To insert a key/value pair into a #GTree use g_tree_insert().
*
- * To lookup the value corresponding to a given key, use
+ * To look up the value corresponding to a given key, use
* g_tree_lookup() and g_tree_lookup_extended().
*
* To find out the number of nodes in a #GTree, use g_tree_nnodes(). To
@@ -11174,7 +10789,7 @@
* @block_size: the number of bytes to copy, must be greater than 0
* @mem_block: (not nullable): the memory to copy
*
- * Allocates a new block of data with atomit reference counting
+ * Allocates a new block of data with atomic reference counting
* semantics, and copies @block_size bytes of @mem_block
* into it.
*
@@ -11322,7 +10937,7 @@
* This macro can be used to avoid having to do explicit cleanups of
* local variables when exiting functions. It often vastly simplifies
* handling of error conditions, removing the need for various tricks
- * such as 'goto out' or repeating of cleanup code. It is also helpful
+ * such as `goto out` or repeating of cleanup code. It is also helpful
* for non-error cases.
*
* Consider the following example:
@@ -11349,8 +10964,8 @@
* }
* ]|
*
- * You must initialize the variable in some way -- either by use of an
- * initialiser or by ensuring that an _init function will be called on
+ * You must initialize the variable in some way — either by use of an
+ * initialiser or by ensuring that an `_init` function will be called on
* it unconditionally before it goes out of scope.
*
* Since: 2.44
@@ -11370,7 +10985,7 @@
* This means it's useful for any type that is returned from
* g_malloc().
*
- * Otherwise, this macro has similar constraints as g_autoptr() - only
+ * Otherwise, this macro has similar constraints as g_autoptr(): only
* supported on GCC and clang, the variable must be initialized, etc.
*
* |[
@@ -11406,13 +11021,13 @@
* are intended to be portable to those compilers.
*
* This is meant to be used to declare lists of a type with a cleanup
- * function. The type of the variable is a GList *. You
- * must not add your own '*'.
+ * function. The type of the variable is a `GList *`. You
+ * must not add your own `*`.
*
* This macro can be used to avoid having to do explicit cleanups of
* local variables when exiting functions. It often vastly simplifies
* handling of error conditions, removing the need for various tricks
- * such as 'goto out' or repeating of cleanup code. It is also helpful
+ * such as `goto out` or repeating of cleanup code. It is also helpful
* for non-error cases.
*
* See also g_autoslist(), g_autoptr() and g_steal_pointer().
@@ -11436,12 +11051,12 @@
*
* This is meant to be used to declare pointers to types with cleanup
* functions. The type of the variable is a pointer to @TypeName. You
- * must not add your own '*'.
+ * must not add your own `*`.
*
* This macro can be used to avoid having to do explicit cleanups of
* local variables when exiting functions. It often vastly simplifies
* handling of error conditions, removing the need for various tricks
- * such as 'goto out' or repeating of cleanup code. It is also helpful
+ * such as `goto out` or repeating of cleanup code. It is also helpful
* for non-error cases.
*
* Consider the following example:
@@ -11471,7 +11086,7 @@
* }
* ]|
*
- * You must initialise the variable in some way -- either by use of an
+ * You must initialise the variable in some way — either by use of an
* initialiser or by ensuring that it is assigned to unconditionally
* before it goes out of scope.
*
@@ -11481,6 +11096,35 @@
*/
+/**
+ * g_autoqueue:
+ * @TypeName: a supported variable type
+ *
+ * Helper to declare a double-ended queue variable with automatic deep cleanup.
+ *
+ * The queue is deeply freed, in a way appropriate to the specified type, when the
+ * variable goes out of scope. The type must support this.
+ *
+ * This feature is only supported on GCC and clang. This macro is not
+ * defined on other compilers and should not be used in programs that
+ * are intended to be portable to those compilers.
+ *
+ * This is meant to be used to declare queues of a type with a cleanup
+ * function. The type of the variable is a `GQueue *`. You
+ * must not add your own `*`.
+ *
+ * This macro can be used to avoid having to do explicit cleanups of
+ * local variables when exiting functions. It often vastly simplifies
+ * handling of error conditions, removing the need for various tricks
+ * such as `goto out` or repeating of cleanup code. It is also helpful
+ * for non-error cases.
+ *
+ * See also g_autolist(), g_autoptr() and g_steal_pointer().
+ *
+ * Since: 2.62
+ */
+
+
/**
* g_autoslist:
* @TypeName: a supported variable type
@@ -11495,13 +11139,13 @@
* are intended to be portable to those compilers.
*
* This is meant to be used to declare lists of a type with a cleanup
- * function. The type of the variable is a GSList *. You
- * must not add your own '*'.
+ * function. The type of the variable is a `GSList *`. You
+ * must not add your own `*`.
*
* This macro can be used to avoid having to do explicit cleanups of
* local variables when exiting functions. It often vastly simplifies
* handling of error conditions, removing the need for various tricks
- * such as 'goto out' or repeating of cleanup code. It is also helpful
+ * such as `goto out` or repeating of cleanup code. It is also helpful
* for non-error cases.
*
* See also g_autolist(), g_autoptr() and g_steal_pointer().
@@ -16848,6 +16492,34 @@
*/
+/**
+ * g_get_console_charset:
+ * @charset: (out) (optional) (transfer none): return location for character set
+ * name, or %NULL.
+ *
+ * Obtains the character set used by the console attached to the process,
+ * which is suitable for printing output to the terminal.
+ *
+ * Usually this matches the result returned by g_get_charset(), but in
+ * environments where the locale's character set does not match the encoding
+ * of the console this function tries to guess a more suitable value instead.
+ *
+ * On Windows the character set returned by this function is the
+ * output code page used by the console associated with the calling process.
+ * If the codepage can't be determined (for example because there is no
+ * console attached) UTF-8 is assumed.
+ *
+ * The return value is %TRUE if the locale's encoding is UTF-8, in that
+ * case you can perhaps avoid calling g_convert().
+ *
+ * The string returned in @charset is not allocated, and should not be
+ * freed.
+ *
+ * Returns: %TRUE if the returned charset is UTF-8
+ * Since: 2.62
+ */
+
+
/**
* g_get_current_dir:
*
@@ -17091,7 +16763,8 @@
* #GtkApplication::startup handler. The program name is found by
* taking the last component of @argv[0].
*
- * Returns: the name of the program. The returned string belongs
+ * Returns: (nullable): the name of the program, or %NULL if it has not been
+ * set yet. The returned string belongs
* to GLib and must not be modified or freed.
*/
@@ -18668,6 +18341,10 @@
* using strcmp(). g_intern_static_string() does not copy the string,
* therefore @string must not be freed or modified.
*
+ * This function must not be used before library constructors have finished
+ * running. In particular, this means it cannot be used to initialize global
+ * variables in C++.
+ *
* Returns: a canonical representation for the string
* Since: 2.10
*/
@@ -18681,6 +18358,10 @@
* can be compared for equality by comparing the pointers, instead of
* using strcmp().
*
+ * This function must not be used before library constructors have finished
+ * running. In particular, this means it cannot be used to initialize global
+ * variables in C++.
+ *
* Returns: a canonical representation for the string
* Since: 2.10
*/
@@ -20491,6 +20172,21 @@
*/
+/**
+ * g_list_insert_before_link:
+ * @list: a pointer to a #GList, this must point to the top of the list
+ * @sibling: (nullable): the list element before which the new element
+ * is inserted or %NULL to insert at the end of the list
+ * @link_: the list element to be added, which must not be part of
+ * any other list
+ *
+ * Inserts @link_ into the list before the given position.
+ *
+ * Returns: the (possibly changed) start of the #GList
+ * Since: 2.62
+ */
+
+
/**
* g_list_insert_sorted:
* @list: a pointer to a #GList, this must point to the top of the
@@ -21498,7 +21194,7 @@
*
* Finds a #GSource given a pair of context and ID.
*
- * It is a programmer error to attempt to lookup a non-existent source.
+ * It is a programmer error to attempt to look up a non-existent source.
*
* More specifically: source IDs can be reissued after a source has been
* destroyed and therefore it is never valid to use this function with a
@@ -25192,6 +24888,10 @@
* expect to ever unload the module again (e.g. do not use this
* function in GTK+ theme engines).
*
+ * This function must not be used before library constructors have finished
+ * running. In particular, this means it cannot be used to initialize global
+ * variables in C++.
+ *
* Returns: the #GQuark identifying the string, or 0 if @string is %NULL
*/
@@ -25204,6 +24904,10 @@
* not currently have an associated #GQuark, a new #GQuark is created,
* using a copy of the string.
*
+ * This function must not be used before library constructors have finished
+ * running. In particular, this means it cannot be used to initialize global
+ * variables in C++.
+ *
* Returns: the #GQuark identifying the string, or 0 if @string is %NULL
*/
@@ -25228,6 +24932,9 @@
* If you want the GQuark to be created if it doesn't already exist,
* use g_quark_from_string() or g_quark_from_static_string().
*
+ * This function must not be used before library constructors have finished
+ * running.
+ *
* Returns: the #GQuark associated with the string, or 0 if @string is
* %NULL or there is no #GQuark associated with it
*/
@@ -25409,6 +25116,21 @@
*/
+/**
+ * g_queue_insert_after_link:
+ * @queue: a #GQueue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the head of the queue.
+ * @link_: a #GList link to insert which must not be part of any other list.
+ *
+ * Inserts @link_ into @queue after @sibling.
+ *
+ * @sibling must be part of @queue.
+ *
+ * Since: 2.62
+ */
+
+
/**
* g_queue_insert_before:
* @queue: a #GQueue
@@ -25425,6 +25147,21 @@
*/
+/**
+ * g_queue_insert_before_link:
+ * @queue: a #GQueue
+ * @sibling: (nullable): a #GList link that must be part of @queue, or %NULL to
+ * push at the tail of the queue.
+ * @link_: a #GList link to insert which must not be part of any other list.
+ *
+ * Inserts @link_ into @queue before @sibling.
+ *
+ * @sibling must be part of @queue.
+ *
+ * Since: 2.62
+ */
+
+
/**
* g_queue_insert_sorted:
* @queue: a #GQueue
@@ -27129,8 +26866,10 @@
* @rw_lock: a #GRWLock
*
* Obtain a read lock on @rw_lock. If another thread currently holds
- * the write lock on @rw_lock or blocks waiting for it, the current
- * thread will block. Read locks can be taken recursively.
+ * the write lock on @rw_lock, the current thread will block. If another thread
+ * does not hold the write lock, but is waiting for it, it is implementation
+ * defined whether the reader or writer will block. Read locks can be taken
+ * recursively.
*
* It is implementation-defined how many threads are allowed to
* hold read locks on the same lock simultaneously. If the limit is hit,
@@ -27818,7 +27557,7 @@
/**
* g_sequence_lookup:
* @seq: a #GSequence
- * @data: data to lookup
+ * @data: data to look up
* @cmp_func: the function used to compare items in the sequence
* @cmp_data: user data passed to @cmp_func
*
@@ -27846,7 +27585,7 @@
/**
* g_sequence_lookup_iter:
* @seq: a #GSequence
- * @data: data to lookup
+ * @data: data to look up
* @iter_cmp: the function used to compare iterators in the sequence
* @cmp_data: user data passed to @iter_cmp
*
@@ -29157,6 +28896,9 @@
* destroyed. The source cannot be subsequently added to another
* context. It is safe to call this on sources which have already been
* removed from their context.
+ *
+ * This does not unref the #GSource: if you still hold a reference, use
+ * g_source_unref() to drop it.
*/
@@ -30388,6 +30130,13 @@
* g_ascii_strup (g_strcanon (str, "abc", '?'))
* ]|
*
+ * 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
*/
@@ -30506,6 +30255,13 @@
* g_ascii_strup (g_strdelimit (str, "abc", '?'))
* ]|
*
+ * 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
*/
@@ -31722,7 +31478,8 @@
* Bug URIs are constructed from a base URI set with g_test_bug_base()
* and @bug_uri_snippet.
*
- * Since: 2.16
+ * Since: 2.16:
+ * See also: g_test_summary()
*/
@@ -32443,6 +32200,23 @@
*/
+/**
+ * g_test_summary:
+ * @summary: One or two sentences summarising what the test checks, and how it
+ * checks it.
+ *
+ * Set the summary for a test, which describes what the test checks, and how it
+ * goes about checking it. This may be included in test report output, and is
+ * useful documentation for anyone reading the source code or modifying a test
+ * in future. It must be a single line.
+ *
+ * This should be called at the top of a test function.
+ *
+ * Since: 2.62:
+ * See also: g_test_bug()
+ */
+
+
/**
* g_test_thorough:
*
@@ -36185,7 +35959,7 @@
/**
* g_variant_dict_contains:
* @dict: a #GVariantDict
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
*
* Checks if @key exists in @dict.
*
@@ -36270,7 +36044,7 @@
/**
* g_variant_dict_lookup:
* @dict: a #GVariantDict
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
* @format_string: a GVariant format string
* @...: the arguments to unpack the value into
*
@@ -36293,7 +36067,7 @@
/**
* g_variant_dict_lookup_value:
* @dict: a #GVariantDict
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
* @expected_type: (nullable): a #GVariantType, or %NULL
*
* Looks up a value in a #GVariantDict.
@@ -37424,7 +37198,7 @@
/**
* g_variant_lookup: (skip)
* @dictionary: a dictionary #GVariant
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
* @format_string: a GVariant format string
* @...: the arguments to unpack the value into
*
@@ -37451,7 +37225,7 @@
/**
* g_variant_lookup_value:
* @dictionary: a dictionary #GVariant
- * @key: the key to lookup in the dictionary
+ * @key: the key to look up in the dictionary
* @expected_type: (nullable): a #GVariantType, or %NULL
*
* Looks up a value in a dictionary #GVariant.
@@ -39353,6 +39127,39 @@
*/
+/**
+ * g_win32_readlink_utf8:
+ * @filename: (type filename): a pathname in UTF-8
+ * @buf: (array length=buf_size): a buffer to receive the reparse point
+ * target path. Mutually-exclusive
+ * with @alloc_buf.
+ * @buf_size: size of the @buf, in bytes
+ * @alloc_buf: points to a location where internally-allocated buffer
+ * pointer will be written. That buffer receives the
+ * link data. Mutually-exclusive with @buf.
+ * @terminate: ensures that the buffer is NUL-terminated if
+ * it isn't already. If %FALSE, the returned string
+ * might not be NUL-terminated (depends entirely on
+ * what the contents of the filesystem are).
+ *
+ * Tries to read the reparse point indicated by @filename, filling
+ * @buf or @alloc_buf with the path that the reparse point redirects to.
+ * The path will be UTF-8-encoded, and an extended path prefix
+ * or a NT object manager prefix will be removed from it, if
+ * possible, but otherwise the path is returned as-is. Specifically,
+ * it could be a "\\\\Volume{GUID}\\" path. It also might use
+ * backslashes as path separators.
+ *
+ * Returns: -1 on error (sets errno), 0 if there's no (recognizable)
+ * path in the reparse point (@alloc_buf will not be allocated in that case,
+ * and @buf will be left unmodified),
+ * or the number of bytes placed into @buf otherwise,
+ * including NUL-terminator (if present or if @terminate is TRUE).
+ * The buffer returned via @alloc_buf should be freed with g_free().
+ * Since: 2.60
+ */
+
+
/**
* gatomicrefcount:
*
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index d5d50385..eafb1eb4 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -245,13 +245,24 @@
* @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 and
- * free them, 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
- * based libraries.
+ * points. They can also be used for wrapping structures defined in non-#GObject
+ * based libraries. They allow arbitrary structures to be handled in a uniform
+ * way, allowing uniform copying (or referencing) and freeing (or unreferencing)
+ * of them, and uniform representation of the type of the contained structure.
+ * In turn, this allows any type which can be boxed to be set as the data in a
+ * #GValue, which allows for polymorphic handling of a much wider range of data
+ * types, and hence usage of such types as #GObject property values.
+ *
+ * #GBoxed is designed so that reference counted types can be boxed. Use the
+ * type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the
+ * #GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is
+ * g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref().
*/
@@ -567,6 +578,13 @@
*
* ## Floating references # {#floating-ref}
*
+ * **Note**: Floating references are a C convenience API and should not be
+ * used in modern GObject code. Language bindings in particular find the
+ * concept highly problematic, as floating references are not identifiable
+ * through annotations, and neither are deviations from the floating reference
+ * behavior, like types that inherit from #GInitiallyUnowned and still return
+ * a full reference from g_object_new().
+ *
* GInitiallyUnowned is derived from GObject. The only difference between
* the two is that the initial reference of a GInitiallyUnowned is flagged
* as a "floating" reference. This means that it is not specifically
@@ -597,7 +615,23 @@
* Since floating references are useful almost exclusively for C convenience,
* language bindings that provide automated reference and memory ownership
* maintenance (such as smart pointers or garbage collection) should not
- * expose floating references in their API.
+ * expose floating references in their API. The best practice for handling
+ * types that have initially floating references is to immediately sink those
+ * references after g_object_new() returns, by checking if the #GType
+ * inherits from #GInitiallyUnowned. For instance:
+ *
+ * |[<!-- language="C" -->
+ * GObject *res = g_object_new_with_properties (gtype,
+ * n_props,
+ * prop_names,
+ * prop_values);
+ *
+ * // or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED))
+ * if (G_IS_INITIALLY_UNOWNED (res))
+ * g_object_ref_sink (res);
+ *
+ * return res;
+ * ]|
*
* Some object implementations may need to save an objects floating state
* across certain code portions (an example is #GtkMenu), to achieve this,
@@ -757,6 +791,9 @@
* GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
* g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
* ]|
+ *
+ * Deprecated: 2.32: Use #GArray instead, if possible for the given use case,
+ * as described above.
*/
@@ -1775,6 +1812,24 @@
*/
+/**
+ * g_clear_signal_handler:
+ * @handler_id_ptr: A pointer to a handler ID (of type #gulong) of the handler to be disconnected.
+ * @instance: (type GObject.Object): The instance to remove the signal handler from.
+ *
+ * Disconnects a handler from @instance so it will not be called during
+ * any future or currently ongoing emissions of the signal it has been
+ * connected to. The @handler_id_ptr is then set to zero, which is never a valid handler ID value (see
g_signal_connect()).
+ *
+ * If the handler ID is 0 then this function does nothing.
+ *
+ * A macro is also included that allows this function to be used without
+ * pointer casts.
+ *
+ * Since: 2.62
+ */
+
+
/**
* g_closure_add_finalize_notifier: (skip)
* @closure: a #GClosure
@@ -2748,9 +2803,15 @@
* @property_name: the name of the property to get
* @value: return location for the property value
*
- * Gets a property of an object. @value must have been initialized to the
- * expected type of the property (or a type to which the expected type can be
- * transformed) using g_value_init().
+ * Gets a property of an object.
+ *
+ * The @value can be:
+ *
+ * - an empty #GValue initialized by %G_VALUE_INIT, which will be
+ * automatically initialized with the expected type of the property
+ * - a #GValue initialized with the expected type of the property
+ * - a #GValue initialized with a type to which the expected type
+ * of the property can be transformed
*
* In general, a copy is made of the property contents and the caller is
* responsible for freeing the memory by calling g_value_unset().
@@ -2809,7 +2870,7 @@
* g_object_interface_find_property:
* @g_iface: (type GObject.TypeInterface): any interface vtable for the
* interface, or the default vtable for the interface
- * @property_name: name of a property to lookup.
+ * @property_name: name of a property to look up.
*
* Find the #GParamSpec with the given name for an
* interface. Generally, the interface vtable passed in as @g_iface
@@ -3106,6 +3167,9 @@
* or may not include using @old_destroy as sometimes replacement
* should not destroy the object in the normal way.
*
+ * See g_object_set_data() for guidance on using a small, bounded set of values
+ * for @key.
+ *
* Returns: %TRUE if the existing value for @key was replaced
* by @newval, %FALSE otherwise.
* Since: 2.34
@@ -3178,6 +3242,11 @@
*
* If the object already had an association with that name,
* the old association will be destroyed.
+ *
+ * Internally, the @key is converted to a #GQuark using g_quark_from_string().
+ * This means a copy of @key is kept permanently (even after @object has been
+ * finalized) — so it is recommended to only use a small, bounded set of values
+ * for @key in your program, to avoid the #GQuark storage growing unbounded.
*/
@@ -5387,9 +5456,9 @@
/**
* g_type_from_name:
- * @name: type name to lookup
+ * @name: type name to look up
*
- * Lookup the type ID from a given type name, returning 0 if no type
+ * Look up the type ID from a given type name, returning 0 if no type
* has been registered under this name (this is the preferred method
* to find out by name whether a specific type has been registered
* yet).
@@ -6758,8 +6827,8 @@
* @v_boxed: (nullable): duplicated unowned boxed value to be set
*
* Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed
- * and takes over the ownership of the callers reference to @v_boxed;
- * the caller doesn't have to unref it any more.
+ * and takes over the ownership of the caller’s reference to @v_boxed;
+ * the caller doesn’t have to unref it any more.
*
* Since: 2.4
*/
@@ -6771,8 +6840,8 @@
* @v_object: (nullable): object value to be set
*
* Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object
- * and takes over the ownership of the callers reference to @v_object;
- * the caller doesn't have to unref it any more (i.e. the reference
+ * and takes over the ownership of the caller’s reference to @v_object;
+ * the caller doesn’t have to unref it any more (i.e. the reference
* count of the object is not increased).
*
* If you want the #GValue to hold its own reference to @v_object, use
@@ -6788,8 +6857,8 @@
* @param: (nullable): the #GParamSpec to be set
*
* Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes
- * over the ownership of the callers reference to @param; the caller
- * doesn't have to unref it any more.
+ * over the ownership of the caller’s reference to @param; the caller
+ * doesn’t have to unref it any more.
*
* Since: 2.4
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
