diff options
| -rw-r--r-- | gir/gio-2.0.c | 50 | ||||
| -rw-r--r-- | gir/glib-2.0.c | 207 |
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 |