[gobject-introspection] gir: Update annotations from GLib git master
- From: Rico Tzschichholz <ricotz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] gir: Update annotations from GLib git master
- Date: Mon, 12 Feb 2018 15:02:35 +0000 (UTC)
commit 6f677e77413b628756a9dbb8082f783757b099f3
Author: Rico Tzschichholz <ricotz ubuntu com>
Date: Mon Feb 12 15:34:30 2018 +0100
gir: Update annotations from GLib git master
gir/gio-2.0.c | 131 +++++++++++++++++++---------
gir/glib-2.0.c | 251 +++++++++++++++++++++++++++++++++++++-----------------
gir/gobject-2.0.c | 4 +-
3 files changed, 263 insertions(+), 123 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index ecdb2cf2..365cd2a2 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2366,13 +2366,9 @@
/**
* GNetworkMonitor::network-changed:
* @monitor: a #GNetworkMonitor
- * @available: the current value of #GNetworkMonitor:network-available
+ * @network_available: the current value of #GNetworkMonitor:network-available
*
- * Emitted when the network configuration changes. If @available is
- * %TRUE, then some hosts may be reachable that were not reachable
- * before, while others that were reachable before may no longer be
- * reachable. If @available is %FALSE, then no remote hosts are
- * reachable.
+ * Emitted when the network configuration changes.
*
* Since: 2.32
*/
@@ -3567,18 +3563,20 @@
/**
* GTlsClientConnection:use-ssl3:
*
- * If %TRUE, tells the connection to use a fallback version of TLS
+ * If %TRUE, forces the connection to use a fallback version of TLS
* or SSL, rather than trying to negotiate the best version of TLS
* to use. This can be used when talking to servers that don't
* implement version negotiation correctly and therefore refuse to
- * handshake at all with a "modern" TLS handshake.
+ * handshake at all with a modern TLS handshake.
*
- * Despite the property name, the fallback version is not
- * necessarily SSL 3.0; if SSL 3.0 has been disabled, the
- * #GTlsClientConnection will use the next highest available version
- * (normally TLS 1.0) as the fallback version.
+ * Despite the property name, the fallback version is usually not
+ * SSL 3.0, because SSL 3.0 is generally disabled by the #GTlsBackend.
+ * #GTlsClientConnection will use the next-highest available version
+ * as the fallback version.
*
* Since: 2.28
+ * Deprecated: 2.56: SSL 3.0 is insecure, and this property does not
+ * generally enable or disable it, despite its name.
*/
@@ -5819,6 +5817,9 @@
* like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses
* is explained in detail in the
* [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+ *
+ * TCP D-Bus connections are supported, but accessing them via a proxy is
+ * currently not supported.
*/
@@ -6274,7 +6275,7 @@
* both well-known and unique names.
*
* By default, #GDBusProxy will cache all properties (and listen to
- * changes) of the remote object, and proxy all signals that gets
+ * changes) of the remote object, and proxy all signals that get
* emitted. This behaviour can be changed by passing suitable
* #GDBusProxyFlags when the proxy is created. If the proxy is for a
* well-known name, the property cache is flushed when the name owner
@@ -16044,6 +16045,8 @@
* before encountering any of the stop characters. Set @length to
* a #gsize to get the length of the string. This function will
* return %NULL on an error.
+ * Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more
+ * consistent behaviour regarding the stop character.
*/
@@ -16073,6 +16076,8 @@
* g_data_input_stream_read_upto_async() instead.
*
* Since: 2.20
+ * Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which
+ * has more consistent behaviour regarding the stop character.
*/
@@ -16091,6 +16096,8 @@
* before encountering any of the stop characters. Set @length to
* a #gsize to get the length of the string. This function will
* return %NULL on an error.
+ * Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which
+ * has more consistent behaviour regarding the stop character.
*/
@@ -16826,7 +16833,8 @@
* @method_name: the name of the method to invoke
* @parameters: (nullable): a #GVariant tuple with parameters for the method
* or %NULL if not passing parameters
- * @reply_type: (nullable): the expected type of the reply, or %NULL
+ * @reply_type: (nullable): the expected type of the reply (which will be a
+ * tuple), or %NULL
* @flags: flags from the #GDBusCallFlags enumeration
* @timeout_msec: the timeout in milliseconds, -1 to use the default
* timeout or %G_MAXINT for no timeout
@@ -16848,7 +16856,9 @@
*
* If @reply_type is non-%NULL then the reply will be checked for having this type and an
* error will be raised if it does not match. Said another way, if you give a @reply_type
- * then any non-%NULL return value will be of this type.
+ * then any non-%NULL return value will be of this type. Unless it’s
+ * %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more
+ * values.
*
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
@@ -18417,7 +18427,7 @@
*
* For example, an exported D-Bus interface may queue up property
* changes and emit the
- * `org.freedesktop.DBus.Properties::PropertiesChanged`
+ * `org.freedesktop.DBus.Properties.PropertiesChanged`
* signal later (e.g. in an idle handler). This technique is useful
* for collapsing multiple property changes into one.
*
@@ -19602,7 +19612,7 @@
* g_dbus_method_invocation_return_value (invocation,
* g_variant_new ("(s)", result_string));
*
- * /<!-- -->* Do not free @invocation here; returning a value does that *<!-- -->/
+ * // Do not free @invocation here; returning a value does that
* ]|
*
* This method will take ownership of @invocation. See
@@ -20427,9 +20437,9 @@
* #GDBusProxy:g-interface-info) and @property_name is referenced by
* it, then @value is checked against the type of the property.
*
- * Returns: A reference to the #GVariant instance that holds the value
- * for @property_name or %NULL if the value is not in the cache. The
- * returned reference must be freed with g_variant_unref().
+ * Returns: (transfer full) (nullable): A reference to the #GVariant instance
+ * that holds the value for @property_name or %NULL if the value is not in
+ * the cache. The returned reference must be freed with g_variant_unref().
* Since: 2.26
*/
@@ -20440,7 +20450,8 @@
*
* Gets the names of all cached properties on @proxy.
*
- * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
+ * Returns: (transfer full) (nullable) (array zero-terminated=1): A
+ * %NULL-terminated array of strings or %NULL if
* @proxy has no cached properties. Free the returned array with
* g_strfreev().
* Since: 2.26
@@ -20492,8 +20503,8 @@
* that @proxy conforms to. See the #GDBusProxy:g-interface-info
* property for more details.
*
- * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
- * object, it is owned by @proxy.
+ * Returns: (transfer none) (nullable): A #GDBusInterfaceInfo or %NULL.
+ * Do not unref the returned object, it is owned by @proxy.
* Since: 2.26
*/
@@ -20529,7 +20540,8 @@
* #GObject::notify signal to track changes to the
* #GDBusProxy:g-name-owner property.
*
- * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
+ * Returns: (transfer full) (nullable): The name owner or %NULL if no name
+ * owner exists. Free with g_free().
* Since: 2.26
*/
@@ -20592,7 +20604,8 @@
*
* Finishes creating a #GDBusProxy.
*
- * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set.
+ * Free with g_object_unref().
* Since: 2.26
*/
@@ -20624,7 +20637,8 @@
*
* Finishes creating a #GDBusProxy.
*
- * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set.
+ * Free with g_object_unref().
* Since: 2.26
*/
@@ -20645,7 +20659,8 @@
*
* #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
*
- * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if error is set.
+ * Free with g_object_unref().
* Since: 2.26
*/
@@ -20680,7 +20695,8 @@
*
* #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
*
- * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if error is set.
+ * Free with g_object_unref().
* Since: 2.26
*/
@@ -20747,7 +20763,8 @@
/**
* g_dbus_proxy_set_interface_info:
* @proxy: A #GDBusProxy
- * @info: (nullable): Minimum interface this proxy conforms to or %NULL to unset.
+ * @info: (transfer none) (nullable): Minimum interface this proxy conforms to
+ * or %NULL to unset.
*
* Ensure that interactions with @proxy conform to the given
* interface. See the #GDBusProxy:g-interface-info property for more
@@ -25344,6 +25361,24 @@
*/
+/**
+ * g_file_peek_path:
+ * @file: input #GFile
+ *
+ * Exactly like g_file_get_path(), but caches the result via
+ * g_object_set_qdata_full(). This is useful for example in C
+ * applications which mix `g_file_*` APIs with native ones. It
+ * also avoids an extra duplicated string when possible, so will be
+ * generally more efficient.
+ *
+ * This call does no blocking I/O.
+ *
+ * Returns: (type filename) (nullable): string containing the #GFile's path,
+ * or %NULL if no such path exists. The returned string is owned by @file.
+ * Since: 2.56
+ */
+
+
/**
* g_file_poll_mountable:
* @file: input #GFile
@@ -25411,7 +25446,7 @@
* Utility function to check if a particular file exists. This is
* implemented using g_file_query_info() and as such does blocking I/O.
*
- * Note that in many cases it is racy to first check for file existence
+ * Note that in many cases it is [racy to first check for file
existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
* and then execute something based on the outcome of that, because the
* file might have been created or removed in between the operations. The
* general approach to handling that is to not check, but just do the
@@ -30911,6 +30946,8 @@
* Deprecated in favor of g_notification_set_priority().
*
* Since: 2.40
+ * Deprecated: 2.42: Since 2.42, this has been deprecated in favour of
+ * g_notification_set_priority().
*/
@@ -31798,6 +31835,9 @@
* may happen if you call this method after a source triggers due
* to having been cancelled.
*
+ * Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
+ * transports like D/TLS require that you send the same @buffer and @count.
+ *
* Returns: the number of bytes written, or -1 on error (including
* %G_IO_ERROR_WOULD_BLOCK).
*/
@@ -33688,7 +33728,7 @@
/**
* g_settings_list_relocatable_schemas:
*
- * <!-- -->
+ * Deprecated.
*
* Returns: (element-type utf8) (transfer none): a list of relocatable
* #GSettings schemas that are available. The list must not be
@@ -33701,7 +33741,7 @@
/**
* g_settings_list_schemas:
*
- * <!-- -->
+ * Deprecated.
*
* Returns: (element-type utf8) (transfer none): a list of #GSettings
* schemas that are available. The list must not be modified or
@@ -39853,12 +39893,14 @@
* g_tls_client_connection_get_use_ssl3:
* @conn: the #GTlsClientConnection
*
- * Gets whether @conn will use SSL 3.0 rather than the
- * highest-supported version of TLS; see
- * g_tls_client_connection_set_use_ssl3().
+ * Gets whether @conn will force the lowest-supported TLS protocol
+ * version rather than attempt to negotiate the highest mutually-
+ * supported version of TLS; see g_tls_client_connection_set_use_ssl3().
*
- * Returns: whether @conn will use SSL 3.0
+ * Returns: whether @conn will use the lowest-supported TLS protocol version
* Since: 2.28
+ * Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+ * actually indicate whether it is enabled.
*/
@@ -39910,15 +39952,20 @@
/**
* g_tls_client_connection_set_use_ssl3:
* @conn: the #GTlsClientConnection
- * @use_ssl3: whether to use SSL 3.0
+ * @use_ssl3: whether to use the lowest-supported protocol version
+ *
+ * If @use_ssl3 is %TRUE, this forces @conn to use the lowest-supported
+ * TLS protocol version rather than trying to properly negotiate the
+ * highest mutually-supported protocol version with the peer. This can
+ * be used when talking to broken TLS servers that exhibit protocol
+ * version intolerance.
*
- * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
- * trying to properly negotiate the right version of TLS or SSL to use.
- * This can be used when talking to servers that do not implement the
- * fallbacks correctly and which will therefore fail to handshake with
- * a "modern" TLS handshake attempt.
+ * Be aware that SSL 3.0 is generally disabled by the #GTlsBackend, so
+ * the lowest-supported protocol version is probably not SSL 3.0.
*
* Since: 2.28
+ * Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+ * generally enable or disable it, despite its name.
*/
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 854cee12..01f1c051 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -593,7 +593,7 @@
* g_direct_hash() is also the appropriate hash function for keys
* of the form `GINT_TO_POINTER (n)` (or similar macros).
*
- * <!-- FIXME: Need more here. --> A good hash functions should produce
+ * A good hash functions should produce
* hash values that are evenly distributed over a fairly large range.
* The modulus is taken with the hash table size (a prime number) to
* find the 'bucket' to place each key into. The function should also
@@ -5443,7 +5443,7 @@
* in it ("/"). However, displaying file names may require conversion:
* from the character set in which they were created, to the character
* set in which the application operates. Consider the Spanish file name
- * "Presentación.sxi". If the application which created it uses
+ * "Presentación.sxi". If the application which created it uses
* ISO-8859-1 for its encoding,
* |[
* Character: P r e s e n t a c i ó n . s x i
@@ -5456,31 +5456,31 @@
* Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
* ]|
* Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
- * Glib do the same thing. If you get a file name from the file system,
+ * GLib do the same thing. If you get a file name from the file system,
* for example, from readdir() or from g_dir_read_name(), and you wish
* to display the file name to the user, you will need to convert it
* into UTF-8. The opposite case is when the user types the name of a
- * file he wishes to save: the toolkit will give you that string in
+ * file they wish to save: the toolkit will give you that string in
* UTF-8 encoding, and you will need to convert it to the character
* set used for file names before you can create the file with open()
* or fopen().
*
- * By default, Glib assumes that file names on disk are in UTF-8
+ * By default, GLib assumes that file names on disk are in UTF-8
* encoding. This is a valid assumption for file systems which
* were created relatively recently: most applications use UTF-8
* encoding for their strings, and that is also what they use for
* the file names they create. However, older file systems may
* still contain file names created in "older" encodings, such as
* ISO-8859-1. In this case, for compatibility reasons, you may want
- * to instruct Glib to use that particular encoding for file names
+ * to instruct GLib to use that particular encoding for file names
* rather than UTF-8. You can do this by specifying the encoding for
* file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING]
* environment variable. For example, if your installation uses
- * ISO-8859-1 for file names, you can put this in your `~/.profile`
+ * ISO-8859-1 for file names, you can put this in your `~/.profile`:
* |[
* export G_FILENAME_ENCODING=ISO-8859-1
* ]|
- * Glib provides the functions g_filename_to_utf8() and
+ * GLib provides the functions g_filename_to_utf8() and
* g_filename_from_utf8() to perform the necessary conversions.
* These functions convert file names from the encoding specified
* in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This
@@ -7235,8 +7235,13 @@
*
* These functions provide support for allocating and freeing memory.
*
- * If any call to allocate memory fails, the application is terminated.
- * This also means that there is no need to check if the call succeeded.
+ * If any call to allocate memory using functions g_new(), g_new0(), g_renew(),
+ * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n()
+ * fails, the application is terminated. This also means that there is no
+ * need to check if the call succeeded. On the other hand, g_try_...() family
+ * of functions returns %NULL on failure that can be used as a check
+ * for unsuccessful memory allocation. The application is not terminated
+ * in this case.
*
* It's important to match g_malloc() (and wrappers such as g_new()) with
* g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
@@ -7836,6 +7841,12 @@
* g_sequence_move_range() will not invalidate the iterators pointing
* to it. The only operation that will invalidate an iterator is when
* the element it points to is removed from any sequence.
+ *
+ * To sort the data, either use g_sequence_insert_sorted() or
+ * g_sequence_insert_sorted_iter() to add data to the #GSequence or, if
+ * you want to add a large amount of data, it is more efficient to call
+ * g_sequence_sort() or g_sequence_sort_iter() after doing unsorted
+ * insertions.
*/
@@ -10606,9 +10617,9 @@
*
* membuf = g_malloc (8192);
*
- * /<!-- -->* Some computation on membuf *<!-- -->/
+ * // Some computation on membuf
*
- * /<!-- -->* membuf will be automatically freed here *<!-- -->/
+ * // membuf will be automatically freed here
* return TRUE;
* }
* ]|
@@ -12096,6 +12107,12 @@
* A reference to @bytes will be held by the newly created #GBytes until
* the byte data is no longer needed.
*
+ * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
+ * @bytes will be returned with the reference count incremented by 1. If @bytes
+ * is a slice of another #GBytes, then the resulting #GBytes will reference
+ * the same #GBytes instead of @bytes. This allows consumers to simplify the
+ * usage of #GBytes when asynchronously writing to streams.
+ *
* Returns: (transfer full): a new #GBytes
* Since: 2.32
*/
@@ -12813,30 +12830,31 @@
/**
* g_convert:
- * @str: the string to convert
+ * @str: (array length=len) (element-type guint8):
+ * the string to convert.
* @len: the length of the string in bytes, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
* for the @len parameter is unsafe)
* @to_codeset: name of character set into which to convert @str
* @from_codeset: character set of @str.
- * @bytes_read: (out): location to store the number of bytes in the
- * input string that were successfully converted, or %NULL.
+ * @bytes_read: (out) (optional): location to store the number of bytes in
+ * the input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
- * @bytes_written: (out): the number of bytes stored in the output buffer (not
- * including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ * the output buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
* Converts a string from one character set to another.
*
* Note that you should use g_iconv() for streaming conversions.
- * Despite the fact that @byes_read can return information about partial
+ * Despite the fact that @bytes_read can return information about partial
* characters, the g_convert_... functions are not generally suitable
* for streaming. If the underlying converter maintains internal state,
* then this won't be preserved across successive calls to g_convert(),
@@ -12848,33 +12866,35 @@
* Using extensions such as "//TRANSLIT" may not work (or may not work
* well) on many platforms. Consider using g_str_to_ascii() instead.
*
- * Returns: If the conversion was successful, a newly allocated
- * nul-terminated string, which must be freed with
- * g_free(). Otherwise %NULL and @error will be set.
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ * If the conversion was successful, a newly allocated buffer
+ * containing the converted string, which must be freed with g_free().
+ * Otherwise %NULL and @error will be set.
*/
/**
* g_convert_with_fallback:
- * @str: the string to convert
+ * @str: (array length=len) (element-type guint8):
+ * the string to convert.
* @len: the length of the string in bytes, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
* for the @len parameter is unsafe)
* @to_codeset: name of character set into which to convert @str
* @from_codeset: character set of @str.
- * @fallback: UTF-8 string to use in place of character not
+ * @fallback: UTF-8 string to use in place of characters not
* present in the target encoding. (The string must be
* representable in the target encoding).
* If %NULL, characters not in the target encoding will
* be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
- * @bytes_read: location to store the number of bytes in the
- * input string that were successfully converted, or %NULL.
+ * @bytes_read: (out) (optional): location to store the number of bytes in
+ * the input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input.
- * @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ * the output buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
@@ -12887,7 +12907,7 @@
* in which case GLib will simply return that approximate conversion.
*
* Note that you should use g_iconv() for streaming conversions.
- * Despite the fact that @byes_read can return information about partial
+ * Despite the fact that @bytes_read can return information about partial
* characters, the g_convert_... functions are not generally suitable
* for streaming. If the underlying converter maintains internal state,
* then this won't be preserved across successive calls to g_convert(),
@@ -12896,37 +12916,39 @@
* character until it knows that the next character is not a mark that
* could combine with the base character.)
*
- * Returns: If the conversion was successful, a newly allocated
- * nul-terminated string, which must be freed with
- * g_free(). Otherwise %NULL and @error will be set.
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ * If the conversion was successful, a newly allocated buffer
+ * containing the converted string, which must be freed with g_free().
+ * Otherwise %NULL and @error will be set.
*/
/**
* g_convert_with_iconv: (skip)
- * @str: the string to convert
+ * @str: (array length=len) (element-type guint8):
+ * the string to convert.
* @len: the length of the string in bytes, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
* for the @len parameter is unsafe)
* @converter: conversion descriptor from g_iconv_open()
- * @bytes_read: location to store the number of bytes in the
- * input string that were successfully converted, or %NULL.
+ * @bytes_read: (out) (optional): location to store the number of bytes in
+ * the input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
- * @bytes_written: the number of bytes stored in the output buffer (not
- * including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ * the output buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
* Converts a string from one character set to another.
*
* Note that you should use g_iconv() for streaming conversions.
- * Despite the fact that @byes_read can return information about partial
+ * Despite the fact that @bytes_read can return information about partial
* characters, the g_convert_... functions are not generally suitable
* for streaming. If the underlying converter maintains internal state,
* then this won't be preserved across successive calls to g_convert(),
@@ -12935,8 +12957,17 @@
* character until it knows that the next character is not a mark that
* could combine with the base character.)
*
- * Returns: If the conversion was successful, a newly allocated
- * nul-terminated string, which must be freed with
+ * Characters which are valid in the input character set, but which have no
+ * representation in the output character set will result in a
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv()
+ * specification, which leaves this behaviour implementation defined. Note that
+ * this is the same error code as is returned for an invalid byte sequence in
+ * the input character set. To get defined behaviour for conversion of
+ * unrepresentable characters, use g_convert_with_fallback().
+ *
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ * If the conversion was successful, a newly allocated buffer
+ * containing the converted string, which must be freed with
* g_free(). Otherwise %NULL and @error will be set.
*/
@@ -13144,7 +13175,7 @@
*
* If the previous value was replaced then ownership of the
* old value (@oldval) is passed to the caller, including
- * the registred destroy notify for it (passed out in @old_destroy).
+ * the registered destroy notify for it (passed out in @old_destroy).
* Its up to the caller to free this as he wishes, which may
* or may not include using @old_destroy as sometimes replacement
* should not destroy the object in the normal way.
@@ -15668,7 +15699,7 @@
/**
* g_filename_from_utf8:
- * @utf8string: a UTF-8 encoded string.
+ * @utf8string: (type utf8): a UTF-8 encoded string.
* @len: the length of the string, or -1 if the string is
* nul-terminated.
* @bytes_read: (out) (optional): location to store the number of bytes in
@@ -15676,11 +15707,11 @@
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
- * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
- * @bytes_written: (out): the number of bytes stored in the output buffer (not
- * including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ * the output buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
@@ -15689,7 +15720,13 @@
* on other platforms, this function indirectly depends on the
* [current locale][setlocale].
*
- * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ * The input string shall not contain nul characters even if the @len
+ * argument is positive. A nul character found inside the string will result
+ * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
+ * not UTF-8 and the conversion output contains a nul character, the error
+ * %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL.
+ *
+ * Returns: (type filename):
* The converted string, or %NULL on an error.
*/
@@ -15723,7 +15760,7 @@
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
- * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: (out) (optional): the number of bytes stored in the output
@@ -15736,7 +15773,15 @@
* for filenames; on other platforms, this function indirectly depends on
* the [current locale][setlocale].
*
- * Returns: The converted string, or %NULL on an error.
+ * The input string shall not contain nul characters even if the @len
+ * argument is positive. A nul character found inside the string will result
+ * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+ * If the source encoding is not UTF-8 and the conversion output contains a
+ * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+ * function returns %NULL. Use g_convert() to produce output that
+ * may contain embedded nul characters.
+ *
+ * Returns: (type utf8): The converted string, or %NULL on an error.
*/
@@ -15929,6 +15974,10 @@
* handle file names. It might be different from the character set
* used by the C library's current locale.
*
+ * On Linux, the character set is found by consulting nl_langinfo() if
+ * available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG`
+ * and `CHARSET` are queried in order.
+ *
* The return value is %TRUE if the locale's encoding is UTF-8, in that
* case you can perhaps avoid calling g_convert().
*
@@ -15999,7 +16048,8 @@
/**
* g_get_filename_charsets:
- * @charsets: return location for the %NULL-terminated list of encoding names
+ * @filename_charsets: (out) (transfer none) (array zero-terminated=1):
+ * return location for the %NULL-terminated list of encoding names
*
* Determines the preferred character sets used for filenames.
* The first character set from the @charsets is the filename encoding, the
@@ -17492,6 +17542,13 @@
* GLib provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
+ * Note that the behaviour of iconv() for characters which are valid in the
+ * input character set, but which have no representation in the output character
+ * set, is implementation defined. This function may return success (with a
+ * positive number of non-reversible conversions as replacement characters were
+ * used), or it may return -1 and set an error such as %EILSEQ, in such a
+ * situation.
+ *
* Returns: count of non-reversible conversions, or -1 on error
*/
@@ -18602,6 +18659,29 @@
*/
+/**
+ * g_key_file_get_locale_for_key:
+ * @key_file: a #GKeyFile
+ * @group_name: a group name
+ * @key: a key
+ * @locale: (nullable): a locale identifier or %NULL
+ *
+ * Returns the actual locale which the result of
+ * g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
+ * came from.
+ *
+ * If calling g_key_file_get_locale_string() or
+ * g_key_file_get_locale_string_list() with exactly the same @key_file,
+ * @group_name, @key and @locale, the result of those functions will
+ * have originally been tagged with the locale that is the result of
+ * this function.
+ *
+ * Returns: (nullable): the locale from the file, or %NULL if the key was not
+ * found or the entry in the file was was untranslated
+ * Since: 2.56
+ */
+
+
/**
* g_key_file_get_locale_string:
* @key_file: a #GKeyFile
@@ -19788,15 +19868,13 @@
* g_locale_from_utf8:
* @utf8string: a UTF-8 encoded string
* @len: the length of the string, or -1 if the string is
- * nul-terminated (Note that some encodings may allow nul
- * bytes to occur inside strings. In that case, using -1
- * for the @len parameter is unsafe)
+ * nul-terminated.
* @bytes_read: (out) (optional): location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
- * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: (out) (optional): the number of bytes stored in the output
@@ -19809,14 +19887,21 @@
* system) in the [current locale][setlocale]. On Windows this means
* the system codepage.
*
- * Returns: A newly-allocated buffer containing the converted string,
- * or %NULL on an error, and error will be set.
+ * The input string shall not contain nul characters even if the @len
+ * argument is positive. A nul character found inside the string will result
+ * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert
+ * input that may contain embedded nul characters.
+ *
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ * A newly-allocated buffer containing the converted string,
+ * or %NULL on an error, and error will be set.
*/
/**
* g_locale_to_utf8:
- * @opsysstring: a string in the encoding of the current locale. On Windows
+ * @opsysstring: (array length=len) (element-type guint8): a string in the
+ * encoding of the current locale. On Windows
* this means the system codepage.
* @len: the length of the string, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
@@ -19827,7 +19912,7 @@
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
* at the end of the input. If the error
- * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: (out) (optional): the number of bytes stored in the output
@@ -19839,8 +19924,15 @@
* the C runtime (usually the same as that used by the operating
* system) in the [current locale][setlocale] into a UTF-8 string.
*
- * Returns: A newly-allocated buffer containing the converted string,
- * or %NULL on an error, and error will be set.
+ * If the source encoding is not UTF-8 and the conversion output contains a
+ * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+ * function returns %NULL.
+ * If the source encoding is UTF-8, an embedded nul character is treated with
+ * the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with
+ * earlier versions of this library. Use g_convert() to produce output that
+ * may contain embedded nul characters.
+ *
+ * Returns: (type utf8): The converted string, or %NULL on an error.
*/
@@ -26324,6 +26416,10 @@
* if the first item comes before the second, and a positive value
* if the second item comes before the first.
*
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then call
+ * g_sequence_sort() or g_sequence_sort_iter().
+ *
* Returns: (transfer none): a #GSequenceIter pointing to the new item.
* Since: 2.14
*/
@@ -26350,6 +26446,10 @@
* first iterator comes before the second, and a positive value
* if the second iterator comes before the first.
*
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then call
+ * g_sequence_sort() or g_sequence_sort_iter().
+ *
* Returns: (transfer none): a #GSequenceIter pointing to the new item
* Since: 2.14
*/
@@ -26490,10 +26590,7 @@
* the second item comes before the first.
*
* This function will fail if the data contained in the sequence is
- * unsorted. Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
*
* Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of the
* first item found equal to @data according to @cmp_func and
@@ -26518,10 +26615,7 @@
* value if the second iterator comes before the first.
*
* This function will fail if the data contained in the sequence is
- * unsorted. Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
*
* Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of
* the first item found equal to @data according to @cmp_func
@@ -26654,10 +26748,7 @@
* consider using g_sequence_lookup().
*
* This function will fail if the data contained in the sequence is
- * unsorted. Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
*
* Returns: (transfer none): an #GSequenceIter pointing to the position where @data
* would have been inserted according to @cmp_func and @cmp_data
@@ -26684,10 +26775,7 @@
* consider using g_sequence_lookup_iter().
*
* This function will fail if the data contained in the sequence is
- * unsorted. Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
*
* Returns: (transfer none): a #GSequenceIter pointing to the position in @seq
* where @data would have been inserted according to @iter_cmp
@@ -28506,7 +28594,7 @@
* standard error. If you use this flag, @standard_error must be %NULL.
* %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
* standard input (by default, the child's standard input is attached to
- * /dev/null). If you use this flag, @standard_input must be %NULL.
+ * `/dev/null`). If you use this flag, @standard_input must be %NULL.
* %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
* the file to execute, while the remaining elements are the actual
* argument vector to pass to the file. Normally g_spawn_async_with_pipes()
@@ -28543,8 +28631,8 @@
* when they are no longer in use. If these parameters are %NULL, the
* corresponding pipe won't be created.
*
- * If @standard_input is NULL, the child's standard input is attached to
- * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
+ * If @standard_input is %NULL, the child's standard input is attached to
+ * `/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
*
* If @standard_error is NULL, the child's standard error goes to the same
* location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
@@ -34069,6 +34157,9 @@
* must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
* text before trying to use UTF-8 utility functions with it.)
*
+ * Note you must ensure @dest is at least 4 * @n to fit the
+ * largest possible UTF-8 characters
+ *
* Returns: @dest
*/
@@ -36039,7 +36130,7 @@
* GVariant *new_variant;
*
* new_variant = g_variant_new ("(t^as)",
- * /<!-- -->* This cast is required. *<!-- -->/
+ * // This cast is required.
* (guint64) some_flags,
* some_strings);
* ]|
@@ -38090,7 +38181,9 @@
* goffset:
*
* A signed integer type that is used for file offsets,
- * corresponding to the C99 type off64_t.
+ * corresponding to the POSIX type `off_t` as if compiling with
+ * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on
+ * 32-bit architectures.
* Values of this type can range from #G_MINOFFSET to
* #G_MAXOFFSET.
*
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index f52cc7ca..b0688076 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -3202,7 +3202,7 @@
* If the previous value was replaced then ownership of the
* old value (@oldval) is passed to the caller, including
* the registered destroy notify for it (passed out in @old_destroy).
- * Its up to the caller to free this as he wishes, which may
+ * It’s up to the caller to free this as needed, which may
* or may not include using @old_destroy as sometimes replacement
* should not destroy the object in the normal way.
*
@@ -3231,7 +3231,7 @@
* If the previous value was replaced then ownership of the
* old value (@oldval) is passed to the caller, including
* the registered destroy notify for it (passed out in @old_destroy).
- * Its up to the caller to free this as he wishes, which may
+ * It’s up to the caller to free this as needed, which may
* or may not include using @old_destroy as sometimes replacement
* should not destroy the object in the normal way.
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
