summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--gir/gio-2.0.c50
-rw-r--r--gir/glib-2.0.c207
2 files changed, 217 insertions, 40 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 3da779ca..6eb6265c 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -7329,8 +7329,11 @@
* @include: gio/gio.h
*
* #GNetworkMonitor provides an easy-to-use cross-platform API
- * for monitoring network connectivity. On Linux, the implementation
- * is based on the kernel's netlink interface.
+ * for monitoring network connectivity. On Linux, the available
+ * implementations are based on the kernel's netlink interface and
+ * on NetworkManager.
+ *
+ * There is also an implementation for use inside Flatpak sandboxes.
*/
@@ -7573,6 +7576,10 @@
* #GProxyResolver provides synchronous and asynchronous network proxy
* resolution. #GProxyResolver is used within #GSocketClient through
* the method g_socket_connectable_proxy_enumerate().
+ *
+ * Implementations of #GProxyResolver based on libproxy and GNOME settings can
+ * be found in glib-networking. GIO comes with an implementation for use inside
+ * Flatpak portals.
*/
@@ -26996,8 +27003,8 @@
/**
* g_input_stream_read:
* @stream: a #GInputStream.
- * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
- * a buffer to read data into (which should be at least count bytes long).
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into (which should be at least count bytes long).
* @count: the number of bytes that will be read from the stream
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
@@ -27031,8 +27038,8 @@
/**
* g_input_stream_read_all:
* @stream: a #GInputStream.
- * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
- * a buffer to read data into (which should be at least count bytes long).
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into (which should be at least count bytes long).
* @count: the number of bytes that will be read from the stream
* @bytes_read: (out): location to store the number of bytes that was read from the stream
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
@@ -27065,8 +27072,8 @@
/**
* g_input_stream_read_all_async:
* @stream: A #GInputStream
- * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
- * a buffer to read data into (which should be at least count bytes long)
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into (which should be at least count bytes long)
* @count: the number of bytes that will be read from the stream
* @io_priority: the [I/O priority][io-priority] of the request
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
@@ -27113,8 +27120,8 @@
/**
* g_input_stream_read_async:
* @stream: A #GInputStream.
- * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
- * a buffer to read data into (which should be at least count bytes long).
+ * @buffer: (array length=count) (element-type guint8): a buffer to
+ * read data into (which should be at least count bytes long).
* @count: the number of bytes that will be read from the stream
* @io_priority: the [I/O priority][io-priority]
* of the request.
@@ -34150,8 +34157,7 @@
/**
* g_settings_sync:
*
- * Ensures that all pending operations for the given are complete for
- * the default backend.
+ * Ensures that all pending operations are complete for the default backend.
*
* Writes made to a #GSettings are handled asynchronously. For this
* reason, it is very unlikely that the changes have it to disk by the
@@ -36370,7 +36376,7 @@
/**
* g_socket_listener_accept:
* @listener: a #GSocketListener
- * @source_object: (out) (transfer none) (optional): location where #GObject pointer will be stored, or %NULL
+ * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: #GError for error reporting, or %NULL to ignore.
*
@@ -36412,7 +36418,7 @@
* g_socket_listener_accept_finish:
* @listener: a #GSocketListener
* @result: a #GAsyncResult.
- * @source_object: (out) (transfer none) (optional): Optional #GObject identifying this source
+ * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
*
@@ -36426,7 +36432,7 @@
/**
* g_socket_listener_accept_socket:
* @listener: a #GSocketListener
- * @source_object: (out) (transfer none) (optional): location where #GObject pointer will be stored, or %NULL.
+ * @source_object: (out) (transfer none) (optional) (nullable): location where #GObject pointer will be stored, or %NULL.
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: #GError for error reporting, or %NULL to ignore.
*
@@ -36471,7 +36477,7 @@
* g_socket_listener_accept_socket_finish:
* @listener: a #GSocketListener
* @result: a #GAsyncResult.
- * @source_object: (out) (transfer none) (optional): Optional #GObject identifying this source
+ * @source_object: (out) (transfer none) (optional) (nullable): Optional #GObject identifying this source
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
*
@@ -36745,8 +36751,8 @@
* pointer, or %NULL
* @vectors: (array length=num_vectors): an array of #GInputVector structs
* @num_vectors: the number of elements in @vectors, or -1
- * @messages: (array length=num_messages) (out) (optional): a pointer which
- * may be filled with an array of #GSocketControlMessages, or %NULL
+ * @messages: (array length=num_messages) (out) (optional) (nullable): a pointer
+ * 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: (inout): a pointer to an int containing #GSocketMsgFlags flags
@@ -42267,7 +42273,7 @@
* g_win32_registry_key_get_child:
* @key: (in) (transfer none): a parent #GWin32RegistryKey
* @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key
- * @error: (inout) (optional): a pointer to a %NULL #GError, or %NULL
+ * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL
*
* Opens a @subkey of the @key.
*
@@ -42280,7 +42286,7 @@
* g_win32_registry_key_get_child_w:
* @key: (in) (transfer none): a parent #GWin32RegistryKey
* @subkey: (in) (transfer none): name of a child key to open (in UTF-8), relative to @key
- * @error: (inout) (optional): a pointer to a %NULL #GError, or %NULL
+ * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL
*
* Opens a @subkey of the @key.
*
@@ -42400,7 +42406,7 @@
/**
* g_win32_registry_key_new_w:
* @path: (in) (transfer none): absolute full name of a key to open (in UTF-16)
- * @error: (inout) (optional): a pointer to a %NULL #GError, or %NULL
+ * @error: (inout) (optional) (nullable): a pointer to a %NULL #GError, or %NULL
*
* Creates an object that represents a registry key specified by @path.
* @path must start with one of the following pre-defined names:
@@ -42543,7 +42549,7 @@
* g_win32_registry_subkey_iter_init:
* @iter: (in) (transfer none): a pointer to a #GWin32RegistrySubkeyIter
* @key: (in) (transfer none): a #GWin32RegistryKey to iterate over
- * @error: (inout) (optional): a pointer to %NULL #GError, or %NULL
+ * @error: (inout) (optional) (nullable): a pointer to %NULL #GError, or %NULL
*
* Initialises (without allocating) a #GWin32RegistrySubkeyIter. @iter may be
* completely uninitialised prior to this call; its old value is
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 43b29206..59b2331d 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -6189,10 +6189,10 @@
* can use:
*
* |[<!-- language="C" -->
- * GVariant *v = g_variant_new ('u', 40);
+ * GVariant *v = g_variant_new ("u", 40);
* ]|
*
- * The string 'u' in the first argument tells #GVariant that the data passed to
+ * The string "u" in the first argument tells #GVariant that the data passed to
* the constructor (40) is going to be an unsigned integer.
*
* More advanced examples of #GVariant in use can be found in documentation for
@@ -6521,7 +6521,7 @@
* - `s`: the type string of %G_VARIANT_TYPE_STRING; a string.
* - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form
* of a D-Bus object path.
- * - `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of
+ * - `g`: the type string of %G_VARIANT_TYPE_SIGNATURE; a string in the form of
* a D-Bus type signature.
* - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that
* is a supertype of any of the basic types.
@@ -6619,6 +6619,10 @@
* space saving, if your set is large. The functions
* g_hash_table_add() and g_hash_table_contains() are designed to be
* used when using #GHashTable this way.
+ *
+ * #GHashTable is not designed to be statically initialised with keys and
+ * values known at compile time. To build a static hash table, use a tool such
+ * as [gperf](https://www.gnu.org/software/gperf/).
*/
@@ -7787,6 +7791,49 @@
*
* See #GSubprocess in GIO for a higher-level API that provides
* stream interfaces for communication with child processes.
+ *
+ * An example of using g_spawn_async_with_pipes():
+ * |[<!-- language="C" -->
+ * const gchar * const argv[] = { "my-favourite-program", "--args", NULL };
+ * gint child_stdout, child_stderr;
+ * GPid child_pid;
+ * g_autoptr(GError) error = NULL;
+ *
+ * // Spawn child process.
+ * g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL,
+ * NULL, &child_pid, NULL, &child_stdout,
+ * &child_stderr, &error);
+ * if (error != NULL)
+ * {
+ * g_error ("Spawning child failed: %s", error->message);
+ * return;
+ * }
+ *
+ * // Add a child watch function which will be called when the child process
+ * // exits.
+ * g_child_watch_add (child_pid, child_watch_cb, NULL);
+ *
+ * // You could watch for output on @child_stdout and @child_stderr using
+ * // #GUnixInputStream or #GIOChannel here.
+ *
+ * static void
+ * child_watch_cb (GPid pid,
+ * gint status,
+ * gpointer user_data)
+ * {
+ * g_message ("Child %" G_PID_FORMAT " exited %s", pid,
+ * g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally");
+ *
+ * // Free any resources associated with the child here, such as I/O channels
+ * // on its stdout and stderr FDs. If you have no code to put in the
+ * // child_watch_cb() callback, you can remove it and the g_child_watch_add()
+ * // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag,
+ * // otherwise the child process will stay around as a zombie until this
+ * // process exits.
+ *
+ * g_spawn_close_pid (pid);
+ * }
+ * ]|
*/
@@ -9054,6 +9101,78 @@
/**
+ * g_ascii_string_to_signed:
+ * @str: a string
+ * @base: base of a parsed number
+ * @min: a lower bound (inclusive)
+ * @max: an upper bound (inclusive)
+ * @out_num: (out) (optional): a return location for a number
+ * @error: a return location for #GError
+ *
+ * A convenience function for converting a string to a signed number.
+ *
+ * This function assumes that @str contains only a number of the given
+ * @base that is within inclusive bounds limited by @min and @max. If
+ * this is true, then the converted number is stored in @out_num. An
+ * empty string is not a valid input. A string with leading or
+ * trailing whitespace is also an invalid input.
+ *
+ * @base can be between 2 and 36 inclusive. Hexadecimal numbers must
+ * not be prefixed with "0x" or "0X". Such a problem does not exist
+ * for octal numbers, since they were usually prefixed with a zero
+ * which does not change the value of the parsed number.
+ *
+ * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR
+ * domain. If the input is invalid, the error code will be
+ * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of
+ * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
+ *
+ * See g_ascii_strtoll() if you have more complex needs such as
+ * parsing a string which starts with a number, but then has other
+ * characters.
+ *
+ * Returns: %TRUE if @str was a number, otherwise %FALSE.
+ * Since: 2.54
+ */
+
+
+/**
+ * g_ascii_string_to_unsigned:
+ * @str: a string
+ * @base: base of a parsed number
+ * @min: a lower bound (inclusive)
+ * @max: an upper bound (inclusive)
+ * @out_num: (out) (optional): a return location for a number
+ * @error: a return location for #GError
+ *
+ * A convenience function for converting a string to an unsigned number.
+ *
+ * This function assumes that @str contains only a number of the given
+ * @base that is within inclusive bounds limited by @min and @max. If
+ * this is true, then the converted number is stored in @out_num. An
+ * empty string is not a valid input. A string with leading or
+ * trailing whitespace is also an invalid input.
+ *
+ * @base can be between 2 and 36 inclusive. Hexadecimal numbers must
+ * not be prefixed with "0x" or "0X". Such a problem does not exist
+ * for octal numbers, since they were usually prefixed with a zero
+ * which does not change the value of the parsed number.
+ *
+ * Parsing failures result in an error with the %G_NUMBER_PARSER_ERROR
+ * domain. If the input is invalid, the error code will be
+ * %G_NUMBER_PARSER_ERROR_INVALID. If the parsed number is out of
+ * bounds - %G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS.
+ *
+ * See g_ascii_strtoull() if you have more complex needs such as
+ * parsing a string which starts with a number, but then has other
+ * characters.
+ *
+ * Returns: %TRUE if @str was a number, otherwise %FALSE.
+ * Since: 2.54
+ */
+
+
+/**
* g_ascii_strncasecmp:
* @s1: string to compare with @s2
* @s2: string to compare with @s1
@@ -15186,7 +15305,7 @@
/**
* g_filename_from_uri:
* @uri: a uri describing a filename (escaped, encoded in ASCII).
- * @hostname: (out) (optional): Location to store hostname for the URI.
+ * @hostname: (out) (optional) (nullable): Location to store hostname for the URI.
* If there is no hostname in the URI, %NULL will be
* stored in this location.
* @error: location to store the error occurring, or %NULL to ignore
@@ -16222,7 +16341,7 @@
* g_hash_table_iter_next:
* @iter: an initialized #GHashTableIter
* @key: (out) (optional): a location to store the key
- * @value: (out) (optional): a location to store the value
+ * @value: (out) (optional) (nullable): a location to store the value
*
* Advances @iter and retrieves the key and/or value that are now
* pointed to as a result of this advancement. If %FALSE is returned,
@@ -16309,7 +16428,7 @@
* @hash_table: a #GHashTable
* @lookup_key: the key to look up
* @orig_key: (out) (optional): return location for the original key
- * @value: (out) (optional): return location for the value associated
+ * @value: (out) (optional) (nullable): return location for the value associated
* with the key
*
* Looks up a key in the #GHashTable, returning the original key and the
@@ -23095,7 +23214,7 @@
/**
* g_prefix_error:
- * @err: (inout) (optional): a return location for a #GError
+ * @err: (inout) (optional) (nullable): a return location for a #GError
* @format: printf()-style format string
* @...: arguments to @format
*
@@ -23260,6 +23379,51 @@
/**
+ * g_ptr_array_find: (skip)
+ * @haystack: pointer array to be searched
+ * @needle: pointer to look for
+ * @index_: (optional) (out caller-allocates): return location for the index of
+ * the element, if found
+ *
+ * Checks whether @needle exists in @haystack. If the element is found, %TRUE is
+ * returned and the element’s index is returned in @index_ (if non-%NULL).
+ * Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists
+ * multiple times in @haystack, the index of the first instance is returned.
+ *
+ * This does pointer comparisons only. If you want to use more complex equality
+ * checks, such as string comparisons, use g_ptr_array_find_with_equal_func().
+ *
+ * Returns: %TRUE if @needle is one of the elements of @haystack
+ * Since: 2.54
+ */
+
+
+/**
+ * g_ptr_array_find_with_equal_func: (skip)
+ * @haystack: pointer array to be searched
+ * @needle: pointer to look for
+ * @equal_func: (nullable): the function to call for each element, which should
+ * return %TRUE when the desired element is found; or %NULL to use pointer
+ * equality
+ * @index_: (optional) (out caller-allocates): return location for the index of
+ * the element, if found
+ *
+ * Checks whether @needle exists in @haystack, using the given @equal_func.
+ * If the element is found, %TRUE is returned and the element’s index is
+ * returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_
+ * is undefined. If @needle exists multiple times in @haystack, the index of
+ * the first instance is returned.
+ *
+ * @equal_func is called with the element from the array as its first parameter,
+ * and @needle as its second parameter. If @equal_func is %NULL, pointer
+ * equality is used.
+ *
+ * Returns: %TRUE if @needle is one of the elements of @haystack
+ * Since: 2.54
+ */
+
+
+/**
* g_ptr_array_foreach:
* @array: a #GPtrArray
* @func: the function to call for each array element
@@ -27892,10 +28056,11 @@
*
* @flags should be the bitwise OR of any flags you want to affect the
* function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
- * child will not automatically be reaped; you must use a child watch to
- * be notified about the death of the child process. Eventually you must
- * call g_spawn_close_pid() on the @child_pid, in order to free
- * resources which may be associated with the child process. (On Unix,
+ * child will not automatically be reaped; you must use a child watch
+ * (g_child_watch_add()) to be notified about the death of the child process,
+ * otherwise it will stay around as a zombie process until this process exits.
+ * Eventually you must call g_spawn_close_pid() on the @child_pid, in order to
+ * free resources which may be associated with the child process. (On Unix,
* using a child watch is equivalent to calling waitpid() or handling
* the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
* is equivalent to calling CloseHandle() on the process handle returned
@@ -31147,7 +31312,14 @@
* Use g_date_time_format() or g_strdup_printf() if a different
* variation of ISO 8601 format is required.
*
- * Returns: a newly allocated string containing an ISO 8601 date
+ * If @time_ represents a date which is too large to fit into a `struct tm`,
+ * %NULL will be returned. This is platform dependent, but it is safe to assume
+ * years up to 3000 are supported. The return value of g_time_val_to_iso8601()
+ * has been nullable since GLib 2.54; before then, GLib would crash under the
+ * same conditions.
+ *
+ * Returns: (nullable): a newly allocated string containing an ISO 8601 date,
+ * or %NULL if @time_ was too large
* Since: 2.12
*/
@@ -35513,10 +35685,10 @@
* @n_elements: the number of elements
* @element_size: the size of each element
*
- * Provides access to the serialised data for an array of fixed-sized
- * items.
+ * Constructs a new array #GVariant instance, where the elements are
+ * of @element_type type.
*
- * @value must be an array with fixed-sized elements. Numeric types are
+ * @elements must be an array with fixed-sized elements. Numeric types are
* fixed-size as are tuples containing only other fixed-sized types.
*
* @element_size must be the size of a single element in the array.
@@ -35525,8 +35697,7 @@
* of a double-check that the form of the serialised data matches the caller's
* expectation.
*
- * @n_elements, which must be non-%NULL is set equal to the number of
- * items in the array.
+ * @n_elements must be the length of the @elements array.
*
* Returns: (transfer none): a floating reference to a new array #GVariant instance
* Since: 2.32
@@ -35921,7 +36092,7 @@
*
* Note that the arguments in @app must be of the correct width for their
* types specified in @format_string when collected into the #va_list.
- * See the [GVariant varargs documentation][gvariant-varargs.
+ * See the [GVariant varargs documentation][gvariant-varargs].
*
* These two generalisations allow mixing of multiple calls to
* g_variant_new_va() and g_variant_get_va() within a single actual