From b317c230fbd525760ad56d7435c7f9dc8bdf448d Mon Sep 17 00:00:00 2001 From: Christoph Reiter Date: Sat, 15 Jun 2019 20:08:53 +0200 Subject: 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: + * + * |[ + * 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: * * |[ * 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 `` 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. * + * |[ + * 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 + * + * |[ + * + * // 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 + * ]| + * + * |[ - * 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. - * - * |[ - * 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. - * - * |[ - * 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()`: + * |[ + * 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()`: + * |[ + * 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: + * + * |[ + * 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 */ -- cgit v1.2.1