diff --git a/Atk-1.0.gir b/Atk-1.0.gir index c235b382..fff57ac4 100644 --- a/Atk-1.0.gir +++ b/Atk-1.0.gir @@ -553,7 +553,7 @@ A string name/value pair representing a generic attribute. - + Like atk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -4564,7 +4564,7 @@ application compile time, rather than from the library linked against at application run time. - + Like atk_get_minor_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -5317,7 +5317,7 @@ a empty value you can use "". - + Gets the accessible id of the accessible. a character string representing the accessible id of the object, or @@ -5365,6 +5365,20 @@ of the accessible. + + Gets the help text associated with the accessible. + + a character string representing the help text or the object, or +NULL if no such string was set. + + + + + an #AtkObject + + + + Gets the 0-based index of this accessible in its parent; returns -1 if the accessible does not have an accessible parent. @@ -5635,7 +5649,7 @@ set of the accessible - + Sets the accessible ID of the accessible. This is not meant to be presented to the user, but to be an ID which is stable over application development. Typically, this is the gtkbuilder ID. Such an ID will be available for @@ -5649,7 +5663,7 @@ reading, or for automatic regression testing. an #AtkObject - + a character string to be set as the accessible id @@ -5674,6 +5688,24 @@ the name to a empty value you can use "". + + Sets the help text associated with the accessible. This can be used to +expose context-sensitive information to help a user understand how to +interact with the object. + + + + + + an #AtkObject + + + + a character string to be set as the accessible's help text + + + + Sets the accessible name of the accessible. You can't set the name to NULL. This is reserved for the initial value. In this aspect @@ -5734,9 +5766,15 @@ a empty value you can use "". + + + + + + diff --git a/GLib-2.0.gir b/GLib-2.0.gir index 428bbaa7..cc3608d8 100644 --- a/GLib-2.0.gir +++ b/GLib-2.0.gir @@ -5,7 +5,7 @@ and/or use gtk-doc annotations. --> - + Integer representing a day of the month; between 1 and 31. @@ -42,7 +42,31 @@ the g_spawn functions. A GQuark is a non-zero integer which uniquely identifies a -particular string. A GQuark value of zero is associated to %NULL. +particular string. + +A GQuark value of zero is associated to `NULL`. + +Given either the string or the `GQuark` identifier it is possible to +retrieve the other. + +Quarks are used for both +[datasets and keyed data lists](datalist-and-dataset.html). + +To create a new quark from a string, use [func@GLib.quark_from_string] +or [func@GLib.quark_from_static_string]. + +To find the string corresponding to a given `GQuark`, use +[func@GLib.quark_to_string]. + +To find the `GQuark` corresponding to a given string, use +[func@GLib.quark_try_string]. + +Another use for the string pool maintained for the quark functions +is string interning, using [func@GLib.intern_string] or +[func@GLib.intern_static_string]. An interned string is a canonical +representation for a string. One important advantage of interned +strings is that they can be compared for equality by a simple +pointer comparison, rather than using `strcmp()`. @@ -102,9 +126,6 @@ gtime = (GTime)ttime; A value representing an interval of time, in microseconds. - - - 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 @@ -121,27 +142,31 @@ alignment. + + + + + + + + + + + + + + + - - Evaluates to a truth value if the absolute difference between @a and @b is -smaller than @epsilon, and to a false value otherwise. - -For example, -- `G_APPROX_VALUE (5, 6, 2)` evaluates to true -- `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false -- `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within - the single precision floating point epsilon from zero + - a numeric value - a numeric value - a numeric value that expresses the tolerance between @a and @b @@ -185,6 +210,31 @@ static const Person default_person = { ]| + + + + + + + + + + + + + + + + + + + + + + + + + Contains the public fields of a GArray. @@ -1007,7 +1057,7 @@ This function must be called while holding the @queue's lock. - + Inserts @data into @queue using @func to determine the new position. @@ -1030,7 +1080,7 @@ For an example of @func see g_async_queue_sort(). the @data to push into the @queue - + the #GCompareDataFunc is used to sort @queue @@ -1040,7 +1090,7 @@ For an example of @func see g_async_queue_sort(). - + Inserts @data into @queue using @func to determine the new position. @@ -1068,7 +1118,7 @@ For an example of @func see g_async_queue_sort(). the data to push into the @queue - + the #GCompareDataFunc is used to sort @queue @@ -1101,7 +1151,7 @@ This function must be called while holding the @queue's lock. Increases the reference count of the asynchronous @queue by 1. You do not need to hold the lock to call this function. - + the @queue that was passed in (since 2.6) @@ -1163,7 +1213,7 @@ This function must be called while holding the @queue's lock. - + Sorts @queue using @func. The sort function @func is passed two elements of the @queue. @@ -1194,7 +1244,7 @@ lowest priority would be at the top of the queue, you could use: a #GAsyncQueue - + the #GCompareDataFunc is used to sort @queue @@ -1204,7 +1254,7 @@ lowest priority would be at the top of the queue, you could use: - + Sorts @queue using @func. The sort function @func is passed two elements of the @queue. @@ -1222,7 +1272,7 @@ This function must be called while holding the @queue's lock. a #GAsyncQueue - + the #GCompareDataFunc is used to sort @queue @@ -1387,7 +1437,7 @@ You do not need to hold the lock to call this function. - + a #GAsyncQueue. @@ -1413,7 +1463,7 @@ lock. Creates a new asynchronous queue. - + a new #GAsyncQueue. Free with g_async_queue_unref() @@ -1422,7 +1472,7 @@ lock. Creates a new asynchronous queue and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref. - + a new #GAsyncQueue. Free with g_async_queue_unref() @@ -1435,8 +1485,6 @@ the queue is destroyed after the final unref. - Specifies one of the possible types of byte order. -See %G_BYTE_ORDER. @@ -1448,23 +1496,24 @@ and on other architectures it raises a `SIGTRAP` signal. `SIGTRAP` is used rather than abort() to allow breakpoints to be skipped past in a debugger if they are not the desired target of debugging. - - GBookmarkFile lets you parse, edit or create files containing bookmarks -to URI, along with some meta-data about the resource pointed by the URI -like its MIME type, the application that is registering the bookmark and -the icon that should be used to represent the bookmark. The data is stored -using the + + `GBookmarkFile` lets you parse, edit or create files containing bookmarks. + +Bookmarks refer to a URI, along with some meta-data about the resource +pointed by the URI like its MIME type, the application that is registering +the bookmark and the icon that should be used to represent the bookmark. +The data is stored using the [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). The syntax of the bookmark files is described in detail inside the Desktop Bookmark Specification, here is a quick summary: bookmark files use a sub-class of the XML Bookmark Exchange Language specification, consisting of valid UTF-8 encoded XML, under the -<xbel> root element; each bookmark is stored inside a -<bookmark> element, using its URI: no relative paths can +`<xbel>` root element; each bookmark is stored inside a +`<bookmark>` element, using its URI: no relative paths can be used inside a bookmark file. The bookmark may have a user defined title and description, to be used instead of the URI. Under the -<metadata> element, with its owner attribute set to +`<metadata>` element, with its owner attribute set to `http://freedesktop.org`, is stored the meta-data about a resource pointed by its URI. The meta-data consists of the resource's MIME type; the applications that have registered a bookmark; the groups @@ -1481,12 +1530,10 @@ is accessed through its URI. The important caveat of bookmark files is that when you add a new bookmark you must also add the application that is registering it, using -g_bookmark_file_add_application() or g_bookmark_file_set_application_info(). +[method@GLib.BookmarkFile.add_application] or [method@GLib.BookmarkFile.set_application_info]. If a bookmark has no applications then it won't be dumped when creating -the on disk representation, using g_bookmark_file_to_data() or -g_bookmark_file_to_file(). - -The #GBookmarkFile parser was added in GLib 2.12. +the on disk representation, using [method@GLib.BookmarkFile.to_data] or +[method@GLib.BookmarkFile.to_file]. Creates a new empty #GBookmarkFile object. @@ -2778,10 +2825,10 @@ guaranteed to be atomic by using g_file_set_contents() internally. the number of elements in the #GByteArray - + Adds the given bytes to the end of the #GByteArray. The array will grow in size automatically if necessary. - + the #GByteArray @@ -2887,10 +2934,10 @@ stores the length of its data in #guint, which may be shorter than - + Adds the given data to the start of the #GByteArray. The array will grow in size automatically if necessary. - + the #GByteArray @@ -2913,10 +2960,10 @@ The array will grow in size automatically if necessary. - + Atomically increments the reference count of @array by one. This function is thread-safe and may be called from any thread. - + The passed in #GByteArray @@ -2931,10 +2978,10 @@ This function is thread-safe and may be called from any thread. - + Removes the byte at the given index from a #GByteArray. The following bytes are moved down one place. - + the #GByteArray @@ -2953,12 +3000,12 @@ The following bytes are moved down one place. - + Removes the byte at the given index from a #GByteArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the #GByteArray. But it is faster than g_byte_array_remove_index(). - + the #GByteArray @@ -2977,10 +3024,10 @@ than g_byte_array_remove_index(). - + Removes the given number of bytes starting at the given index from a #GByteArray. The following elements are moved to close the gap. - + the #GByteArray @@ -3003,9 +3050,9 @@ than g_byte_array_remove_index(). - + Sets the size of the #GByteArray, expanding it if necessary. - + the #GByteArray @@ -3024,12 +3071,12 @@ than g_byte_array_remove_index(). - + Creates a new #GByteArray with @reserved_size bytes preallocated. This avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0. - + the new #GByteArray @@ -3042,7 +3089,7 @@ bytes to the array. Note however that the size of the array is still - + Sorts a byte array, using @compare_func which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater than zero if @@ -3063,13 +3110,13 @@ their addresses. - + comparison function - + Like g_byte_array_sort(), but the comparison function takes an extra user data argument. @@ -3082,7 +3129,7 @@ user data argument. - + comparison function @@ -3561,67 +3608,255 @@ Used for specifying valid identifier characters in #GScannerConfig. - - Macro to check if the current compiler supports a specified @version -of the C++ standard. Such value must be numeric and can be provided both -in the short form for the well-known versions (e.g. `11`, `17`...) or in -the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...). - -When a C compiler is used, the macro is defined and returns always %FALSE. - -This value is compared against %G_CXX_STD_VERSION. - -|[<!-- language="C" --> -#if G_CXX_STD_CHECK_VERSION(20) -#endif -]| - -See also: %G_C_STD_CHECK_VERSION + - The C++ version to be checked for compatibility - - Macro to check if the current compiler supports a specified @version -of the C standard. Such value must be numeric and can be provided both -in the short form for the well-known versions (e.g. `90`, `99`...) or in -the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...). - -When a C++ compiler is used, the macro is defined and returns always %FALSE. - -This value is compared against %G_C_STD_VERSION. - -|[<!-- language="C" --> -#if G_C_STD_CHECK_VERSION(17) -#endif -]| - -See also: %G_CXX_STD_CHECK_VERSION + - The C version to be checked for compatibility - - The C standard version the code is compiling against, it's normally -defined with the same value of `__STDC_VERSION__` for C standard -compatible compilers, while it uses the lowest standard version -in pure MSVC, given that in such compiler the definition depends on -a compilation flag. - -This is granted to be undefined when compiling with a C++ compiler. - -See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION + + + A `GCache` allows sharing of complex data structures, in order to +save system resources. + +`GCache` uses keys and values. A `GCache` key describes the properties +of a particular resource. A `GCache` value is the actual resource. + +`GCache` has been marked as deprecated, since this API is rarely +used and not very actively maintained. + Use a #GHashTable instead + + Frees the memory allocated for the #GCache. + +Note that it does not destroy the keys and values which were +contained in the #GCache. + Use a #GHashTable instead + + + + + + a #GCache + + + + + + Gets the value corresponding to the given key, creating it if +necessary. It first checks if the value already exists in the +#GCache, by using the @key_equal_func function passed to +g_cache_new(). If it does already exist it is returned, and its +reference count is increased by one. If the value does not currently +exist, if is created by calling the @value_new_func. The key is +duplicated by calling @key_dup_func and the duplicated key and value +are inserted into the #GCache. + Use a #GHashTable instead + + a pointer to a #GCache value + + + + + a #GCache + + + + a key describing a #GCache object + + + + + + Calls the given function for each of the keys in the #GCache. + +NOTE @func is passed three parameters, the value and key of a cache +entry and the @user_data. The order of value and key is different +from the order in which g_hash_table_foreach() passes key-value +pairs to its callback function ! + Use a #GHashTable instead + + + + + + a #GCache + + + + the function to call with each #GCache key + + + + user data to pass to the function + + + + + + Decreases the reference count of the given value. If it drops to 0 +then the value and its corresponding key are destroyed, using the +@value_destroy_func and @key_destroy_func passed to g_cache_new(). + Use a #GHashTable instead + + + + + + a #GCache + + + + the value to remove + + + + + + Calls the given function for each of the values in the #GCache. + The reason is that it passes pointers to internal + data structures to @func; use g_cache_key_foreach() instead + + + + + + a #GCache + + + + the function to call with each #GCache value + + + + user data to pass to the function + + + + + + Creates a new #GCache. + Use a #GHashTable instead + + a new #GCache + + + + + a function to create a new object given a key. + This is called by g_cache_insert() if an object + with the given key does not already exist + + + + a function to destroy an object. It is called + by g_cache_remove() when the object is no + longer needed (i.e. its reference count drops + to 0) + + + + a function to copy a key. It is called by + g_cache_insert() if the key does not already exist in + the #GCache + + + + a function to destroy a key. It is called by + g_cache_remove() when the object is no longer + needed (i.e. its reference count drops to 0) + + + + a function to create a hash value from a key + + + + a function to create a hash value from a value + + + + a function to compare two keys. It should return + %TRUE if the two keys are equivalent + + + + + + + Specifies the type of the @value_destroy_func and @key_destroy_func +functions passed to g_cache_new(). The functions are passed a +pointer to the #GCache key or #GCache value and should free any +memory and other resources associated with it. + Use a #GHashTable instead + + + + + + the #GCache value to destroy + + + + + + Specifies the type of the @key_dup_func function passed to +g_cache_new(). The function is passed a key +(__not__ a value as the prototype implies) and +should return a duplicate of the key. + Use a #GHashTable instead + + a copy of the #GCache key + + + + + the #GCache key to destroy (__not__ a + #GCache value as it seems) + + + + + + Specifies the type of the @value_new_func function passed to +g_cache_new(). It is passed a #GCache key and should create the +value corresponding to the key. + Use a #GHashTable instead + + a new #GCache value corresponding to the key. + + + + + a #GCache key + + + + - An opaque structure representing a checksumming operation. + GLib provides a generic API for computing checksums (or ‘digests’) +for a sequence of arbitrary bytes, using various hashing algorithms +like MD5, SHA-1 and SHA-256. Checksums are commonly used in various +environments and specifications. -To create a new GChecksum, use g_checksum_new(). To free -a GChecksum, use g_checksum_free(). +To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free +a `GChecksum`, use [method@GLib.Checksum.free]. + +GLib supports incremental checksums using the `GChecksum` data +structure, by calling [method@GLib.Checksum.update] as long as there’s data +available and then using [method@GLib.Checksum.get_string] or +[method@GLib.Checksum.get_digest] to compute the checksum and return it +either as a string in hexadecimal form, or as a raw sequence of bytes. To +compute the checksum for binary blobs and nul-terminated strings in +one go, use the convenience functions [func@GLib.compute_checksum_for_data] +and [func@GLib.compute_checksum_for_string], respectively. Creates a new #GChecksum, using the checksum algorithm @checksum_type. If the @checksum_type is not known, %NULL is returned. @@ -3884,6 +4119,268 @@ integer if the first value comes after the second. + + `GCompletion` provides support for automatic completion of a string +using any group of target strings. It is typically used for file +name completion as is common in many UNIX shells. + +A `GCompletion` is created using [func@GLib.Completion.new]. Target items are +added and removed with [method@GLib.Completion.add_items], +[method@GLib.Completion.remove_items] and +[method@GLib.Completion.clear_items]. A completion attempt is requested with +[method@GLib.Completion.complete] or [method@GLib.Completion.complete_utf8]. +When no longer needed, the `GCompletion` is freed with +[method@GLib.Completion.free]. + +Items in the completion can be simple strings (e.g. filenames), or +pointers to arbitrary data structures. If data structures are used +you must provide a [type@GLib.CompletionFunc] in [func@GLib.Completion.new], +which retrieves the item’s string from the data structure. You can change +the way in which strings are compared by setting a different +[type@GLib.CompletionStrncmpFunc] in [method@GLib.Completion.set_compare]. + +`GCompletion` has been marked as deprecated, since this API is rarely +used and not very actively maintained. + Rarely used API + + list of target items (strings or data structures). + + + + + + function which is called to get the string associated with a + target item. It is %NULL if the target items are strings. + + + + the last prefix passed to g_completion_complete() or + g_completion_complete_utf8(). + + + + the list of items which begin with @prefix. + + + + + + The function to use when comparing strings. Use + g_completion_set_compare() to modify this function. + + + + Adds items to the #GCompletion. + Rarely used API + + + + + + the #GCompletion. + + + + the list of items to add. + + + + + + + + Removes all items from the #GCompletion. The items are not freed, so if the +memory was dynamically allocated, it should be freed after calling this +function. + Rarely used API + + + + + + the #GCompletion. + + + + + + Attempts to complete the string @prefix using the #GCompletion +target items. + Rarely used API + + the list of items whose strings begin with + @prefix. This should not be changed. + + + + + + + the #GCompletion. + + + + the prefix string, typically typed by the user, which is + compared with each of the items. + + + + if non-%NULL, returns the longest prefix which is + common to all items that matched @prefix, or %NULL if + no items matched @prefix. This string should be freed + when no longer needed. + + + + + + Attempts to complete the string @prefix using the #GCompletion target items. +In contrast to g_completion_complete(), this function returns the largest common +prefix that is a valid UTF-8 string, omitting a possible common partial +character. + +You should use this function instead of g_completion_complete() if your +items are UTF-8 strings. + Rarely used API + + the list of items whose strings begin with @prefix. This should +not be changed. + + + + + + + the #GCompletion + + + + the prefix string, typically used by the user, which is compared + with each of the items + + + + if non-%NULL, returns the longest prefix which is common to all + items that matched @prefix, or %NULL if no items matched @prefix. + This string should be freed when no longer needed. + + + + + + Frees all memory used by the #GCompletion. The items are not freed, so if +the memory was dynamically allocated, it should be freed after calling this +function. + Rarely used API + + + + + + the #GCompletion. + + + + + + Removes items from a #GCompletion. The items are not freed, so if the memory +was dynamically allocated, free @items with g_list_free_full() after calling +this function. + Rarely used API + + + + + + the #GCompletion. + + + + the items to remove. + + + + + + + + Sets the function to use for string comparisons. The default string +comparison function is strncmp(). + Rarely used API + + + + + + a #GCompletion. + + + + the string comparison function. + + + + + + Creates a new #GCompletion. + Rarely used API + + the new #GCompletion. + + + + + the function to be called to return the string representing + an item in the #GCompletion, or %NULL if strings are going to + be used as the #GCompletion items. + + + + + + + Specifies the type of the function passed to g_completion_new(). It +should return the string corresponding to the given target item. +This is used when you use data structures as #GCompletion items. + Rarely used API + + the string corresponding to the item. + + + + + the completion item. + + + + + + Specifies the type of the function passed to +g_completion_set_compare(). This is used when you use strings as +#GCompletion items. + Rarely used API + + an integer less than, equal to, or greater than zero if + the first @n bytes of @s1 is found, respectively, to be + less than, to match, or to be greater than the first @n + bytes of @s2. + + + + + string to compare with @s2. + + + + string to compare with @s1. + + + + maximal number of bytes to compare. + + + + The #GCond struct is an opaque data structure that represents a condition. Threads can block on a #GCond if they find a certain @@ -3991,6 +4488,23 @@ blocking leads to undefined behaviour. + + Destroys a #GCond that has been created with g_cond_new(). + +Calling g_cond_free() for a #GCond on which threads are +blocking leads to undefined behaviour. + GCond can now be statically allocated, or embedded +in structures and initialised with g_cond_init(). + + + + + + a #GCond + + + + Initialises a #GCond so that it can be used. @@ -4028,6 +4542,38 @@ while calling this function, though not required. + + Waits until this thread is woken up on @cond, but not longer than +until the time specified by @abs_time. The @mutex is unlocked before +falling asleep and locked again before resuming. + +If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait(). + +This function can be used even if g_thread_init() has not yet been +called, and, in that case, will immediately return %TRUE. + +To easily calculate @abs_time a combination of g_get_real_time() +and g_time_val_add() can be used. + Use g_cond_wait_until() instead. + + %TRUE if @cond was signalled, or %FALSE on timeout + + + + + a #GCond + + + + a #GMutex that is currently locked + + + + a #GTimeVal, determining the final time + + + + Atomically releases @mutex and waits until @cond is signalled. When this function returns, @mutex is locked again and owned by the @@ -4125,6 +4671,15 @@ time of more than 5 seconds). + + Allocates and initializes a new #GCond. + GCond can now be statically allocated, or embedded +in structures and initialised with g_cond_init(). + + a newly allocated #GCond. Free with g_cond_free() + + + Error codes returned by character set conversion routines. @@ -4199,86 +4754,29 @@ flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. functions when debugging. It prints the current monotonic time and the code location using %G_STRLOC. - - Defines the appropriate cleanup function for a pointer type. - -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 -type. - -With this definition, it will be possible to use g_autoptr() with -@TypeName. - -|[ -G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) -]| - -This macro should be used unconditionally; it is a no-op on compilers -where cleanup is not supported. + - a type name to define a g_autoptr() cleanup function for - the cleanup function - - Defines the appropriate cleanup function for a 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. - -|[ -G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) -]| - -This macro should be used unconditionally; it is a no-op on compilers -where cleanup is not supported. + - a type name to define a g_auto() cleanup function for - the clear function - - Defines the appropriate cleanup function for a type. - -With this definition, it will be possible to use g_auto() with -@TypeName. - -This function will be rarely used. It is used with pointer-based -typedefs and non-pointer types where the value of the variable -represents a resource that must be freed. Two examples are #GStrv -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 -contain this value then the free function will not be called. - -|[ -G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) -]| - -This macro should be used unconditionally; it is a no-op on compilers -where cleanup is not supported. + - a type name to define a g_auto() cleanup function for - the free function - the "none" value for the type @@ -4490,6 +4988,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + @@ -4658,6 +5162,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + @@ -4826,6 +5336,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + @@ -4994,20 +5510,22 @@ in the macro, so you shouldn't use double quotes. + + + + + + - The directory separator character. -This is '/' on UNIX machines and '\' under Windows. - The directory separator as a string. -This is "/" on UNIX machines and "\" under Windows. An opaque data structure that represents a keyed data list. -See also: [Keyed data lists][glib-Keyed-Data-Lists]. +See also: [Keyed data lists](datalist-and-dataset.html). Specifies the type of function passed to g_dataset_foreach(). It is @@ -5032,17 +5550,45 @@ with the @user_data parameter supplied to g_dataset_foreach(). - Represents a day between January 1, Year 1 and a few thousand years in -the future. None of its members should be accessed directly. + `GDate` is a struct for calendrical calculations. -If the `GDate` is obtained from g_date_new(), it will be safe -to mutate but invalid and thus not safe for calendrical computations. +The `GDate` data structure represents a day between January 1, Year 1, +and sometime a few thousand years in the future (right now it will go +to the year 65535 or so, but [method@GLib.Date.set_parse] only parses up to the +year 8000 or so - just count on "a few thousand"). `GDate` is meant to +represent everyday dates, not astronomical dates or historical dates +or ISO timestamps or the like. It extrapolates the current Gregorian +calendar forward and backward in time; there is no attempt to change +the calendar to match time periods or locations. `GDate` does not store +time information; it represents a day. -If it's declared on the stack, it will contain garbage so must be -initialized with g_date_clear(). g_date_clear() makes the date invalid -but safe. An invalid date doesn't represent a day, it's "empty." A date -becomes valid after you set it to a Julian day or you set a day, month, -and year. +The `GDate` implementation has several nice features; it is only a +64-bit struct, so storing large numbers of dates is very efficient. It +can keep both a Julian and day-month-year representation of the date, +since some calculations are much easier with one representation or the +other. A Julian representation is simply a count of days since some +fixed day in the past; for #GDate the fixed day is January 1, 1 AD. +("Julian" dates in the #GDate API aren't really Julian dates in the +technical sense; technically, Julian dates count from the start of the +Julian period, Jan 1, 4713 BC). + +`GDate` is simple to use. First you need a "blank" date; you can get a +dynamically allocated date from [ctor@GLib.Date.new], or you can declare an +automatic variable or array and initialize it by calling [method@GLib.Date.clear]. +A cleared date is safe; it's safe to call [method@GLib.Date.set_dmy] and the other +mutator functions to initialize the value of a cleared date. However, a cleared date +is initially invalid, meaning that it doesn't represent a day that exists. +It is undefined to call any of the date calculation routines on an invalid date. +If you obtain a date from a user or other unpredictable source, you should check +its validity with the [method@GLib.Date.valid] predicate. [method@GLib.Date.valid] +is also used to check for errors with [method@GLib.Date.set_parse] and other functions +that can fail. Dates can be invalidated by calling [method@GLib.Date.clear] again. + +It is very important to use the API to access the `GDate` struct. Often only the +day-month-year or only the Julian representation is valid. Sometimes neither is valid. +Use the API. + +GLib also features `GDateTime` which represents a precise time. the Julian representation of the date @@ -5061,12 +5607,12 @@ and year. - the day of the day-month-year representation of the date, + the month of the day-month-year representation of the date, as a number between 1 and 12 - the day of the day-month-year representation of the date + the year of the day-month-year representation of the date @@ -5996,7 +6542,31 @@ to mark a number as a day, month, or year. - An opaque structure that represents a date and time, including a time zone. + `GDateTime` is a structure that combines a Gregorian date and time +into a single structure. + +`GDateTime` provides many conversion and methods to manipulate dates and times. +Time precision is provided down to microseconds and the time can range +(proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999. +`GDateTime` follows POSIX time in the sense that it is oblivious to leap +seconds. + +`GDateTime` is an immutable object; once it has been created it cannot +be modified further. All modifiers will create a new `GDateTime`. +Nearly all such functions can fail due to the date or time going out +of range, in which case %NULL will be returned. + +`GDateTime` is reference counted: the reference count is increased by calling +[method@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref]. +When the reference count drops to 0, the resources allocated by the `GDateTime` +structure are released. + +Many parts of the API may produce non-obvious results. As an +example, adding two months to January 31st will yield March 31st +whereas adding one month and then one month again will yield either +March 28th or March 29th. Also note that adding 24 hours is not +always the same as adding one day (since days containing daylight +savings time transitions are either 23 or 25 hours in length). Creates a new #GDateTime corresponding to the given date and time in the time zone @tz. @@ -6194,6 +6764,29 @@ when you are done with it. + + Creates a [struct@GLib.DateTime] corresponding to the given Unix time @t in the +local time zone. + +Unix time is the number of microseconds that have elapsed since 1970-01-01 +00:00:00 UTC, regardless of the local time offset. + +This call can fail (returning `NULL`) if @t represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling [method@GLib.DateTime.unref] +when you are done with it. + + a new [struct@GLib.DateTime], or `NULL` + + + + + the Unix time in microseconds + + + + Creates a #GDateTime corresponding to the given Unix time @t in UTC. @@ -6216,6 +6809,28 @@ when you are done with it. + + Creates a [struct@GLib.DateTime] corresponding to the given Unix time @t in UTC. + +Unix time is the number of microseconds that have elapsed since 1970-01-01 +00:00:00 UTC. + +This call can fail (returning `NULL`) if @t represents a time outside +of the supported range of #GDateTime. + +You should release the return value by calling [method@GLib.DateTime.unref] +when you are done with it. + + a new [struct@GLib.DateTime], or `NULL` + + + + + the Unix time in microseconds + + + + Creates a new #GDateTime corresponding to the given date and time in the local time zone. @@ -6671,8 +7286,9 @@ The following format specifiers are supported: - `%%`: a literal `%` character Some conversion specifications can be modified by preceding the -conversion specifier by one or more modifier characters. The -following modifiers are supported for many of the numeric +conversion specifier by one or more modifier characters. + +The following modifiers are supported for many of the numeric conversions: - `O`: Use alternative numeric symbols, if the current locale supports those. @@ -6683,13 +7299,36 @@ conversions: - `0`: Pad a numeric result with zeros. This overrides the default padding for the specifier. +The following modifiers are supported for many of the alphabetic conversions: + +- `^`: Use upper case if possible. This is a gnulib `strftime()` extension. + Since: 2.80 +- `#`: Use opposite case if possible. This is a gnulib `strftime()` + extension. Since: 2.80 + Additionally, when `O` is used with `B`, `b`, or `h`, it produces the alternative form of a month name. The alternative form should be used when the month name is used without a day number (e.g., standalone). It is required in some languages (Baltic, Slavic, Greek, and more) due to their grammatical rules. For other languages there is no difference. `%OB` is a GNU and BSD `strftime()` extension expected to be added to the future POSIX specification, -`%Ob` and `%Oh` are GNU `strftime()` extensions. Since: 2.56 +`%Ob` and `%Oh` are GNU `strftime()` extensions. Since: 2.56 + +Since GLib 2.80, when `E` is used with `%c`, `%C`, `%x`, `%X`, `%y` or `%Y`, +the date is formatted using an alternate era representation specific to the +locale. This is typically used for the Thai solar calendar or Japanese era +names, for example. + +- `%Ec`: the preferred date and time representation for the current locale, + using the alternate era representation +- `%EC`: the name of the era +- `%Ex`: the preferred date representation for the current locale without + the time, using the alternate era representation +- `%EX`: the preferred time representation for the current locale without + the date, using the alternate era representation +- `%Ey`: the year since the beginning of the era denoted by the `%EC` + specifier +- `%EY`: the full alternative year representation a newly allocated string formatted to the requested format or %NULL in the case that there was an error (such @@ -7128,6 +7767,22 @@ Greenwich will fail (due to the year 0 being out of range). nearest second. Unix time is the number of seconds that have elapsed since 1970-01-01 +00:00:00 UTC, regardless of the time zone associated with @datetime. + + the Unix time corresponding to @datetime + + + + + a #GDateTime + + + + + + Gives the Unix time corresponding to @datetime, in microseconds. + +Unix time is the number of microseconds that have elapsed since 1970-01-01 00:00:00 UTC, regardless of the time zone associated with @datetime. the Unix time corresponding to @datetime @@ -7228,15 +7883,44 @@ should free any memory and resources allocated for it. - + An opaque structure representing an opened directory. + + Opens a directory for reading. The names of the files in the +directory can then be retrieved using g_dir_read_name(). Note +that the ordering is not defined. + + a newly allocated #GDir on success, %NULL on failure. + If non-%NULL, you must free the result with g_dir_close() + when you are finished with it. + + + + + the path to the directory you are interested in. On Unix + in the on-disk encoding. On Windows in UTF-8 + + + + Currently must be set to 0. Reserved for future use. + + + + - Closes the directory and deallocates all related resources. + Closes the directory immediately and decrements the reference count. + +Once the reference count reaches zero, the `GDir` structure itself will be +freed. Prior to GLib 2.80, `GDir` was not reference counted. + +It is an error to call any of the `GDir` methods other than +[method@GLib.Dir.ref] and [method@GLib.Dir.unref] on a `GDir` after calling +[method@GLib.Dir.close] on it. - + a #GDir* created by g_dir_open() @@ -7269,6 +7953,19 @@ filenames, the returned name is in UTF-8. + + Increment the reference count of `dir`. + + the same pointer as `dir` + + + + + a `GDir` + + + + Resets the given directory. The next call to g_dir_read_name() will return the first entry again. @@ -7282,6 +7979,28 @@ will return the first entry again. + + Decrements the reference count of `dir`. + +Once the reference count reaches zero, the directory will be closed and all +resources associated with it will be freed. If [method@GLib.Dir.close] is +called when the reference count is greater than zero, the directory is closed +but the `GDir` structure will not be freed until its reference count reaches +zero. + +It is an error to call any of the `GDir` methods other than +[method@GLib.Dir.ref] and [method@GLib.Dir.unref] on a `GDir` after calling +[method@GLib.Dir.close] on it. + + + + + + a `GDir` + + + + Creates a subdirectory in the preferred directory for temporary files (as returned by g_get_tmp_dir()). @@ -7309,36 +8028,9 @@ modified, and might thus be a read-only literal string. - - Opens a directory for reading. The names of the files in the -directory can then be retrieved using g_dir_read_name(). Note -that the ordering is not defined. - - a newly allocated #GDir on success, %NULL on failure. - If non-%NULL, you must free the result with g_dir_close() - when you are finished with it. - - - - - the path to the directory you are interested in. On Unix - in the on-disk encoding. On Windows in UTF-8 - - - - Currently must be set to 0. Reserved for future use. - - - - - The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, -mantissa and exponent of IEEE floats and doubles. These unions are defined -as appropriate for a given platform. IEEE floats and doubles are supported -(used for storage) by at least Intel, PPC and Sparc. - the double value @@ -7378,7 +8070,6 @@ object. - The base of natural logarithms. @@ -7580,7 +8271,7 @@ a certain case, your code will still work. - + This function registers an extended #GError domain. @error_type_name will be duplicated. Otherwise does the same as g_error_domain_register_static(). @@ -7597,21 +8288,21 @@ g_error_domain_register_static(). size of the private error data in bytes - + function initializing fields of the private error data - + function copying fields of the private error data - + function freeing fields of the private error data - + This function registers an extended #GError domain. @error_type_name should not be freed. @error_type_private_size must @@ -7642,15 +8333,15 @@ already takes care of passing valid information to this function. size of the private error data in bytes - + function initializing fields of the private error data - + function copying fields of the private error data - + function freeing fields of the private error data @@ -7924,12 +8615,7 @@ performance. - The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, -mantissa and exponent of IEEE floats and doubles. These unions are defined -as appropriate for a given platform. IEEE floats and doubles are supported -(used for storage) by at least Intel, PPC and Sparc. - the double value @@ -7961,7 +8647,7 @@ as appropriate for a given platform. IEEE floats and doubles are supported set the size as a quantity in bits, rather than - bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’. + bytes, and return units in bits. For example, ‘Mbit’ rather than ‘MB’. return only value, without unit; this should @@ -8006,124 +8692,33 @@ g_slist_foreach(). - This is the platform dependent conversion specifier for scanning and -printing values of type #gint16. It is a string literal, but doesn't -include the percent-sign, such that you can add precision and length -modifiers between percent-sign and conversion specifier. - -|[<!-- language="C" --> -gint16 in; -gint32 out; -sscanf ("42", "%" G_GINT16_FORMAT, &in) -out = in * 1000; -g_print ("%" G_GINT32_FORMAT, out); - -This is not necessarily the correct format for printing and scanning -`int16_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. -]| - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint16 or #guint16. It -is a string literal, but doesn't include the percent-sign, such -that you can add precision and length modifiers between percent-sign -and conversion specifier and append a conversion specifier. - -The following example prints "0x7b"; -|[<!-- language="C" --> -gint16 value = 123; -g_print ("%#" G_GINT16_MODIFIER "x", value); -]| - -This is not necessarily the correct modifier for printing and scanning -`int16_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`. + - This is the platform dependent conversion specifier for scanning -and printing values of type #gint32. See also %G_GINT16_FORMAT. - -This is not necessarily the correct modifier for printing and scanning -`int32_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint32 or #guint32. It -is a string literal. See also %G_GINT16_MODIFIER. - -This is not necessarily the correct modifier for printing and scanning -`int32_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`. + - This macro is used to insert 64-bit integer literals -into the source code. - -It is similar to the standard C `INT64_C` macro, -which should be preferred in new code. - a literal integer value, e.g. 0x1d636b02300a7aa7 - This is the platform dependent conversion specifier for scanning -and printing values of type #gint64. See also %G_GINT16_FORMAT. - -Some platforms do not support scanning and printing 64-bit integers, -even though the types are supported. On such platforms %G_GINT64_FORMAT -is not defined. Note that scanf() may not support 64-bit integers, even -if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() -is not recommended for parsing anyway; consider using g_ascii_strtoull() -instead. - -This is not necessarily the correct format for printing and scanning -`int64_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gint64 or #guint64. -It is a string literal. - -Some platforms do not support printing 64-bit integers, even -though the types are supported. On such platforms %G_GINT64_MODIFIER -is not defined. - -This is not necessarily the correct modifier for printing and scanning -`int64_t` values, even though the in-memory representation is the same. -Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`. + - - This is the platform dependent conversion specifier for scanning -and printing values of type #gintptr. - -Note that this is not necessarily the correct format to scan or -print an `intptr_t`, even though the in-memory representation is the -same. -Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for -`intptr_t`. + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gintptr or #guintptr. -It is a string literal. - -Note that this is not necessarily the correct modifier to scan or -print an `intptr_t`, even though the in-memory representation is the -same. -Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for -`intptr_t`. + @@ -8170,21 +8765,11 @@ See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function - - Expands to a check for a compiler with __GNUC__ defined and a version -greater than or equal to the major and minor numbers provided. For example, -the following would only match on compilers such as GCC 4.8 or newer. - -|[<!-- language="C" --> -#if G_GNUC_CHECK_VERSION(4, 8) -#endif -]| + - major version to check against - minor version to check against @@ -8327,114 +8912,40 @@ for details. - - This macro is used to insert #goffset 64-bit integer literals -into the source code. - -See also G_GINT64_CONSTANT(). + - a literal integer value, e.g. 0x1d636b02300a7aa7 - - This is the platform dependent conversion specifier for scanning -and printing values of type #gsize. See also %G_GINT16_FORMAT. - -Note that this is not necessarily the correct format to scan or -print a `size_t`, even though the in-memory representation is the -same. The standard C `"zu"` format should be used for `size_t`, -assuming a C99-compliant `printf` implementation is available. + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gsize. It -is a string literal. - -Note that this is not necessarily the correct modifier to scan or -print a `size_t`, even though the in-memory representation is the -same. The Standard C `"z"` modifier should be used for `size_t`, -assuming a C99-compliant `printf` implementation is available. + - - This is the platform dependent conversion specifier for scanning -and printing values of type #gssize. See also %G_GINT16_FORMAT. - -Note that this is not necessarily the correct format to scan or print -a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory -representation is the same. -On POSIX platforms, the `"zd"` format should be used for `ssize_t`. + - - The platform dependent length modifier for conversion specifiers -for scanning and printing values of type #gssize. It -is a string literal. - -Note that this is not necessarily the correct modifier to scan or print -a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory -representation is the same. -On POSIX platforms, the `"z"` modifier should be used for `ssize_t`. + - This is the platform dependent conversion specifier for scanning -and printing values of type #guint16. See also %G_GINT16_FORMAT - -This is not necessarily the correct modifier for printing and scanning -`uint16_t` values, even though the in-memory representation is the same. -Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`. - This is the platform dependent conversion specifier for scanning -and printing values of type #guint32. See also %G_GINT16_FORMAT. - -This is not necessarily the correct modifier for printing and scanning -`uint32_t` values, even though the in-memory representation is the same. -Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`. - - This macro is used to insert 64-bit unsigned integer -literals into the source code. - -It is similar to the standard C `UINT64_C` macro, -which should be preferred in new code. + - a literal integer value, e.g. 0x1d636b02300a7aa7U - This is the platform dependent conversion specifier for scanning -and printing values of type #guint64. See also %G_GINT16_FORMAT. - -Some platforms do not support scanning and printing 64-bit integers, -even though the types are supported. On such platforms %G_GUINT64_FORMAT -is not defined. Note that scanf() may not support 64-bit integers, even -if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf() -is not recommended for parsing anyway; consider using g_ascii_strtoull() -instead. - -This is not necessarily the correct modifier for printing and scanning -`uint64_t` values, even though the in-memory representation is the same. -Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`. - - This is the platform dependent conversion specifier -for scanning and printing values of type #guintptr. - -Note that this is not necessarily the correct format to scan or -print a `uintptr_t`, even though the in-memory representation is the -same. -Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for -`uintptr_t`. + @@ -8444,7 +8955,6 @@ Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for - Defined to 1 if gcc-style visibility handling is supported. @@ -8678,7 +9188,7 @@ destruction phase. - + Calls the given function for key/value pairs in the #GHashTable until @predicate returns %TRUE. The function is passed the key and value of each pair, and the given @user_data parameter. The @@ -8706,7 +9216,7 @@ values in a hash table ends up needing O(n*n) operations). - + function to test the key/value pairs for a certain property @@ -8716,7 +9226,7 @@ values in a hash table ends up needing O(n*n) operations). - + Calls the given function for each of the key/value pairs in the #GHashTable. The function is passed the key and value of each pair, and the given @user_data parameter. The hash table may not @@ -8740,7 +9250,7 @@ order searches in contrast to g_hash_table_lookup(). - + the function to call for each key/value pair @@ -8750,7 +9260,7 @@ order searches in contrast to g_hash_table_lookup(). - + Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable. If you supplied key or @@ -8771,7 +9281,7 @@ key/value pairs in the hash table. - + the function to call for each key/value pair @@ -8781,7 +9291,7 @@ key/value pairs in the hash table. - + Calls the given function for each key/value pair in the #GHashTable. If the function returns %TRUE, then the key/value pair is removed from the #GHashTable, but no key or value @@ -8801,7 +9311,7 @@ key/value pairs in the hash table. - + the function to call for each key/value pair @@ -9065,7 +9575,7 @@ a similar fashion to g_direct_equal(), but without the overhead of a function call. @key_equal_func is called with the key from the hash table as its first parameter, and the user-provided key to check against as its second. - + a new #GHashTable @@ -9095,7 +9605,7 @@ permissible if the application still holds a reference to the hash table. This means that you may need to ensure that the hash table is empty by calling g_hash_table_remove_all() before releasing the last reference using g_hash_table_unref(). - + a new #GHashTable @@ -9151,10 +9661,10 @@ or values from @other_hash_table. - + Atomically increments the reference count of @hash_table by one. This function is MT-safe and may be called from any thread. - + the passed in #GHashTable @@ -9401,7 +9911,7 @@ This function is MT-safe and may be called from any thread. - + a valid #GHashTable @@ -9437,9 +9947,9 @@ table is not defined. - + Returns the #GHashTable associated with @iter. - + the #GHashTable associated with @iter. @@ -9578,15 +10088,66 @@ be called more than once for the same key/value pair. - - An opaque structure representing a HMAC operation. -To create a new GHmac, use g_hmac_new(). To free -a GHmac, use g_hmac_unref(). - + + HMACs should be used when producing a cookie or hash based on data +and a key. Simple mechanisms for using SHA1 and other algorithms to +digest a key and data together are vulnerable to various security +issues. +[HMAC](http://en.wikipedia.org/wiki/HMAC) +uses algorithms like SHA1 in a secure way to produce a digest of a +key and data. + +Both the key and data are arbitrary byte arrays of bytes or characters. + +Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 +in GLib 2.42. Support for SHA-384 was added in GLib 2.52. + +To create a new `GHmac`, use [ctor@GLib.Hmac.new]. To free a `GHmac`, use +[method@GLib.Hmac.unref]. + + Creates a new #GHmac, using the digest algorithm @digest_type. +If the @digest_type is not known, %NULL is returned. +A #GHmac can be used to compute the HMAC of a key and an +arbitrary binary blob, using different hashing algorithms. + +A #GHmac works by feeding a binary blob through g_hmac_update() +until the data is complete; the digest can then be extracted +using g_hmac_get_string(), which will return the checksum as a +hexadecimal string; or g_hmac_get_digest(), which will return a +array of raw bytes. Once either g_hmac_get_string() or +g_hmac_get_digest() have been called on a #GHmac, the HMAC +will be closed and it won't be possible to call g_hmac_update() +on it anymore. + +Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. +Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. + + the newly created #GHmac, or %NULL. + Use g_hmac_unref() to free the memory allocated by it. + + + + + the desired type of digest + + + + the key for the HMAC + + + + + + the length of the keys + + + + + Copies a #GHmac. If @hmac has been closed, by calling g_hmac_get_string() or g_hmac_get_digest(), the copied HMAC will be closed as well. - + the copy of the passed #GHmac. Use g_hmac_unref() when finished using it. @@ -9645,11 +10206,11 @@ The hexadecimal characters will be lower case. - + Atomically increments the reference count of @hmac by one. This function is MT-safe and may be called from any thread. - + the passed in #GHmac. @@ -9671,7 +10232,7 @@ Frees the memory allocated for @hmac. - + a #GHmac @@ -9702,45 +10263,6 @@ g_hmac_get_digest() must not have been called on @hmac. - - Creates a new #GHmac, using the digest algorithm @digest_type. -If the @digest_type is not known, %NULL is returned. -A #GHmac can be used to compute the HMAC of a key and an -arbitrary binary blob, using different hashing algorithms. - -A #GHmac works by feeding a binary blob through g_hmac_update() -until the data is complete; the digest can then be extracted -using g_hmac_get_string(), which will return the checksum as a -hexadecimal string; or g_hmac_get_digest(), which will return a -array of raw bytes. Once either g_hmac_get_string() or -g_hmac_get_digest() have been called on a #GHmac, the HMAC -will be closed and it won't be possible to call g_hmac_update() -on it anymore. - -Support for digests of type %G_CHECKSUM_SHA512 has been added in GLib 2.42. -Support for %G_CHECKSUM_SHA384 was added in GLib 2.52. - - the newly created #GHmac, or %NULL. - Use g_hmac_unref() to free the memory allocated by it. - - - - - the desired type of digest - - - - the key for the HMAC - - - - - - the length of the keys - - - - The #GHook struct represents a single hook function in a #GHookList. @@ -9861,7 +10383,7 @@ test for a match. should be skipped - + the function to call for each #GHook, which should return %TRUE when the #GHook has been found @@ -10021,7 +10543,7 @@ and frees the memory allocated for the #GHook. - + Inserts a #GHook into a #GHookList, sorted by the given function. @@ -10035,7 +10557,7 @@ and frees the memory allocated for the #GHook. the #GHook to insert - + the comparison function used to sort the #GHook elements @@ -10328,7 +10850,7 @@ Any function which returns %FALSE is removed from the #GHookList. - + Calls a function on each valid #GHook. @@ -10344,7 +10866,7 @@ Any function which returns %FALSE is removed from the #GHookList. these are skipped - + the function to call for each #GHook @@ -10354,7 +10876,7 @@ Any function which returns %FALSE is removed from the #GHookList. - + Calls a function on each valid #GHook and destroys it if the function returns %FALSE. @@ -10371,7 +10893,7 @@ function returns %FALSE. these are skipped - + the function to call for each #GHook @@ -10487,17 +11009,48 @@ more convenient than the raw iconv wrappers. - The bias by which exponents in double-precision floats are offset. - The bias by which exponents in single-precision floats are offset. - A data structure representing an IO Channel. The fields should be -considered private and should only be accessed with the following -functions. + The `GIOChannel` data type aims to provide a portable method for +using file descriptors, pipes, and sockets, and integrating them +into the main event loop (see [struct@GLib.MainContext]). Currently, +full support is available on UNIX platforms; support for Windows +is only partially complete. + +To create a new `GIOChannel` on UNIX systems use +[ctor@GLib.IOChannel.unix_new]. This works for plain file descriptors, +pipes and sockets. Alternatively, a channel can be created for a +file in a system independent manner using [ctor@GLib.IOChannel.new_file]. + +Once a `GIOChannel` has been created, it can be used in a generic +manner with the functions [method@GLib.IOChannel.read_chars], +[method@GLib.IOChannel.write_chars], [method@GLib.IOChannel.seek_position], +and [method@GLib.IOChannel.shutdown]. + +To add a `GIOChannel` to the main event loop, use [func@GLib.io_add_watch] or +[func@GLib.io_add_watch_full]. Here you specify which events you are +interested in on the `GIOChannel`, and provide a function to be called +whenever these events occur. + +`GIOChannel` instances are created with an initial reference count of 1. +[method@GLib.IOChannel.ref] and [method@GLib.IOChannel.unref] can be used to +increment or decrement the reference count respectively. When the +reference count falls to 0, the `GIOChannel` is freed. (Though it +isn’t closed automatically, unless it was created using +[ctor@GLib.IOChannel.new_file].) Using [func@GLib.io_add_watch] or +[func@GLib.io_add_watch_full] increments a channel’s reference count. + +The new functions [method@GLib.IOChannel.read_chars], +[method@GLib.IOChannel.read_line], [method@GLib.IOChannel.read_line_string], +[method@GLib.IOChannel.read_to_end], [method@GLib.IOChannel.write_chars], +[method@GLib.IOChannel.seek_position], and [method@GLib.IOChannel.flush] +should not be mixed with the deprecated functions +[method@GLib.IOChannel.read], [method@GLib.IOChannel.write], and +[method@GLib.IOChannel.seek] on the same channel. @@ -11596,13 +12149,9 @@ in a generic way. Resource temporarily unavailable. - - Checks whether a character is a directory -separator. It returns %TRUE for '/' on UNIX -machines and for '\' or '/' under Windows. + - a character @@ -11753,19 +12302,20 @@ entries representing links to documents. - #GKeyFile lets you parse, edit or create files containing groups of + `GKeyFile` parses .ini-like config files. + +`GKeyFile` lets you parse, edit or create files containing groups of key-value pairs, which we call "key files" for lack of a better name. Several freedesktop.org specifications use key files now, e.g the [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) -and the -[Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). +and the [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). The syntax of key files is described in detail in the [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), -here is a quick summary: Key files -consists of groups of key-value pairs, interspersed with comments. +here is a quick summary: Key files consists of groups of key-value pairs, interspersed +with comments. -|[ +```txt # this is just an example # there can be comments before the first group @@ -11778,14 +12328,13 @@ Welcome=Hello Welcome[de]=Hallo Welcome[fr_FR]=Bonjour Welcome[it]=Ciao -Welcome[be@latin]=Hello [Another Group] Numbers=2;20;-200;0 Booleans=true;false;true;true -]| +``` Lines beginning with a '#' and blank lines are considered comments. @@ -11793,15 +12342,13 @@ Groups are started by a header line containing the group name enclosed in '[' and ']', and ended implicitly by the start of the next group or the end of the file. Each key-value pair must be contained in a group. -Key-value pairs generally have the form `key=value`, with the -exception of localized strings, which have the form -`key[locale]=value`, with a locale identifier of the -form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` -are optional. -Space before and after the '=' character are ignored. Newline, tab, -carriage return and backslash characters in value are escaped as \n, -\t, \r, and \\\\, respectively. To preserve leading spaces in values, -these can also be escaped as \s. +Key-value pairs generally have the form `key=value`, with the exception +of localized strings, which have the form `key[locale]=value`, with a +locale identifier of the form `lang_COUNTRY@MODIFIER` where `COUNTRY` +and `MODIFIER` are optional. Space before and after the '=' character +are ignored. Newline, tab, carriage return and backslash characters in +value are escaped as `\n`, `\t`, `\r`, and `\\\\`, respectively. To preserve +leading spaces in values, these can also be escaped as `\s`. Key files can store strings (possibly with localized variants), integers, booleans and lists of these. Lists are separated by a separator character, @@ -11828,15 +12375,14 @@ on Windows, but there are some important differences: Note that in contrast to the [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), -groups in key files may contain the same -key multiple times; the last entry wins. Key files may also contain -multiple groups with the same name; they are merged together. -Another difference is that keys and group names in key files are not +groups in key files may contain the same key multiple times; the last entry wins. +Key files may also contain multiple groups with the same name; they are merged +together. Another difference is that keys and group names in key files are not restricted to ASCII characters. Here is an example of loading a key file and reading a value: -|[<!-- language="C" --> +```c g_autoptr(GError) error = NULL; g_autoptr(GKeyFile) key_file = g_key_file_new (); @@ -11859,11 +12405,11 @@ else if (val == NULL) // Fall back to a default value. val = g_strdup ("default-value"); } -]| +``` Here is an example of creating and saving a key file: -|[<!-- language="C" --> +```c g_autoptr(GKeyFile) key_file = g_key_file_new (); const gchar *val = …; g_autoptr(GError) error = NULL; @@ -11886,7 +12432,7 @@ if (data == NULL) return; } g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); -]| +``` Creates a new empty #GKeyFile object. Use g_key_file_load_from_file(), g_key_file_load_from_data(), @@ -13249,31 +13795,19 @@ reaches zero, frees the key file and all its allocated memory. written back. - - Hints the compiler that the expression is likely to evaluate to -a true value. The compiler may use this information for optimizations. - -|[<!-- language="C" --> -if (G_LIKELY (random () != 1)) - g_print ("not one"); -]| + - the expression - Specifies one of the possible types of byte order. -See %G_BYTE_ORDER. - The natural logarithm of 10. - The natural logarithm of 2. @@ -13343,7 +13877,6 @@ module. - Multiplying the base 2 exponent by this number yields the base 10 exponent. @@ -13376,11 +13909,11 @@ above. GLib log levels that are considered fatal by default. This is not used if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). - Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib. + Log levels below `1<<G_LOG_LEVEL_USER_SHIFT` are used by GLib. Higher bits can be used for user-defined log levels. @@ -13548,7 +14081,7 @@ g_list_free_full (another_list, g_object_unref); - + a copy function used to copy every element in the list @@ -13628,7 +14161,7 @@ given user data. user data passed to the function - + the function to call for each element. It should return 0 when the desired element is found @@ -13668,7 +14201,7 @@ not modify any part of the list after that element. - + the function to call with each element's data @@ -13885,7 +14418,7 @@ with g_list_sort(). the data for the new element - + the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -13919,7 +14452,7 @@ with g_list_sort(). the data for the new element - + the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -14041,6 +14574,11 @@ described in the #GList introduction. + + + + + Gets the position of the given element in the #GList (starting from 0). @@ -14100,6 +14638,16 @@ element than the start of the list. Use g_list_insert_before() instead. + + + + + + + + + + Removes an element from a #GList. If two elements contain the same data, only the first is removed. @@ -14215,7 +14763,7 @@ used is a stable sort. - + the comparison function used to sort the #GList. This function is passed the data from 2 elements of the #GList and should return 0 if they are equal, a negative value if the @@ -14241,7 +14789,7 @@ a user data argument. - + comparison function @@ -14276,14 +14824,14 @@ value. Specifies the prototype of log handler functions. -The default log handler, g_log_default_handler(), automatically appends a +The default log handler, [func@GLib.log_default_handler], automatically appends a new-line character to @message when printing it. It is advised that any custom log handler functions behave similarly, so that logging calls in user code do not need modifying to add a new-line character to the message if the log handler is changed. This is not used if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). @@ -14294,7 +14842,7 @@ This is not used if structured logging is enabled; see the log level of the message (including the - fatal and recursion flags) + fatal and recursion flags) @@ -14302,7 +14850,7 @@ This is not used if structured logging is enabled; see - user data, set in g_log_set_handler() + user data, set in [func@GLib.log_set_handler] @@ -14311,7 +14859,7 @@ This is not used if structured logging is enabled; see Flags specifying the level of log messages. It is possible to change how GLib treats messages of the various -levels using g_log_set_handler() and g_log_set_fatal_mask(). +levels using [func@GLib.log_set_handler] and [func@GLib.log_set_fatal_mask]. internal flag @@ -14319,26 +14867,25 @@ levels using g_log_set_handler() and g_log_set_fatal_mask(). internal flag - log level for errors, see g_error(). - This level is also used for messages produced by g_assert(). + log level for errors, see [func@GLib.error]. + This level is also used for messages produced by [func@GLib.assert]. log level for critical warning messages, see - g_critical(). - This level is also used for messages produced by g_return_if_fail() - and g_return_val_if_fail(). + [func@GLib.critical]. This level is also used for messages produced by + [func@GLib.return_if_fail] and [func@GLib.return_val_if_fail]. - log level for warnings, see g_warning() + log level for warnings, see [func@GLib.warning] - log level for messages, see g_message() + log level for messages, see [func@GLib.message] - log level for informational messages, see g_info() + log level for informational messages, see [func@GLib.info] - log level for debug messages, see g_debug() + log level for debug messages, see [func@GLib.debug] a mask including all log levels @@ -14411,57 +14958,28 @@ application compile time, rather than from the library linked against at application run time. - - The maximum value which can be held in a #gint16. - -This is the same as standard C `INT16_MAX`, which should be -preferred in new code. + - - The maximum value which can be held in a #gint32. - -This is the same as standard C `INT32_MAX`, which should be -preferred in new code. + - The maximum value which can be held in a #gint64. - - The maximum value which can be held in a #gint8. - -This is the same as standard C `INT8_MAX`, which should be -preferred in new code. + - - The maximum value which can be held in a #guint16. - -This is the same as standard C `UINT16_MAX`, which should be -preferred in new code. + - - The maximum value which can be held in a #guint32. - -This is the same as standard C `UINT32_MAX`, which should be -preferred in new code. + - The maximum value which can be held in a #guint64. - -This is the same as standard C `UINT64_MAX`, which should be -preferred in new code. - - The maximum value which can be held in a #guint8. - -This is the same as standard C `UINT8_MAX`, which should be -preferred in new code. + @@ -14488,7 +15006,7 @@ linked against at application run time. The minimum value which can be held in a #gint8. - + The minor version number of the GLib library. Like #gtk_minor_version, but from the headers used at @@ -15616,7 +16134,7 @@ elements, see g_markup_parse_context_get_element_stack(). - + Retrieves the element stack from the internal state of the parser. The returned #GSList is a list of strings where the first item is @@ -15631,7 +16149,7 @@ processed. the element stack, which must not be modified - + @@ -16405,6 +16923,105 @@ to zero, it frees all the memory associated with the match_info structure. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + A set of functions used to perform memory allocation. The same #GMemVTable must be used for all allocations in the same program; a call to g_mem_set_vtable(), @@ -16564,6 +17181,23 @@ behaviour. + + Destroys a @mutex that has been created with g_mutex_new(). + +Calling g_mutex_free() on a locked mutex may result +in undefined behaviour. + GMutex can now be statically allocated, or embedded +in structures and initialised with g_mutex_init(). + + + + + + a #GMutex + + + + Initializes a #GMutex so that it can be used. @@ -16654,6 +17288,15 @@ current thread leads to undefined behaviour. + + Allocates and initializes a new #GMutex. + GMutex can now be statically allocated, or embedded +in structures and initialised with g_mutex_init(). + + a newly allocated #GMutex. Use g_mutex_free() to free + + + Returns %TRUE if a #GNode is a leaf node. @@ -16672,13 +17315,8 @@ current thread leads to undefined behaviour. - Determines the number of elements in an array. The array must be -declared so the compiler knows its size at compile-time; this -macro will not work on an array allocated on the heap, only static -arrays or arrays on the stack. - the array @@ -16746,7 +17384,7 @@ the second 1, and so on. - + Calls a function for each of the children of a #GNode. Note that it doesn't descend beneath the child nodes. @func must not do anything that would modify the structure of the tree. @@ -16763,7 +17401,7 @@ that would modify the structure of the tree. %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - + the function to call for each visited node @@ -16798,9 +17436,9 @@ nodes, see g_node_copy_deep() if you need that). a #GNode - - the function which is called to copy the data inside each node, - or %NULL to use the original data. + + the function which is called to copy the data + inside each node, or %NULL to use the original data. @@ -17123,7 +17761,7 @@ too big, %NULL is returned. - + Traverses a tree starting at the given root #GNode. It calls the given function for each node visited. The traversal can be halted at any point by returning %TRUE from @func. @@ -17153,7 +17791,7 @@ The traversal can be halted at any point by returning %TRUE from @func. If depth is 2, the root and its children are visited. And so on. - + the function to call for each visited #GNode @@ -17189,6 +17827,21 @@ Used to create the first node in a tree. + + + + + + + + + + + + + + + Specifies the type of function passed to g_node_children_foreach(). @@ -17228,41 +17881,41 @@ user data passed to g_node_traverse(). If the function returns - + Defines how a Unicode string is transformed in a canonical form, standardizing such issues as whether a character with an accent is represented as a base character and combining accent or as a single precomposed character. Unicode strings should generally be normalized before comparing them. - + standardize differences that do not affect the text content, such as the above-mentioned accent representation - + another name for %G_NORMALIZE_DEFAULT - + like %G_NORMALIZE_DEFAULT, but with composed forms rather than a maximally decomposed form - + another name for %G_NORMALIZE_DEFAULT_COMPOSE - + beyond %G_NORMALIZE_DEFAULT also standardize the "compatibility" characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this case DIGIT THREE). Formatting information may be lost but for most text operations such characters should be considered the same - + another name for %G_NORMALIZE_ALL - + like %G_NORMALIZE_ALL, but with composed forms rather than a maximally decomposed form - + another name for %G_NORMALIZE_ALL_COMPOSE @@ -17349,13 +18002,52 @@ the pointer passed to it should not be `volatile`. - + location of a static initializable variable containing 0 + + + + + + + + + + + + This functions behaves in the same way as g_once_init_enter(), but can +can be used to initialize pointers (or #guintptr) instead of #gsize. + +|[<!-- language="C" --> + static MyStruct *interesting_struct = NULL; + + if (g_once_init_enter_pointer (&interesting_struct)) + { + MyStruct *setup_value = allocate_my_struct (); // initialization code here + + g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value)); + } + + // use interesting_struct here +]| + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing `NULL` + + + + Counterpart to g_once_init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value @@ -17369,7 +18061,7 @@ the pointer passed to it should not be `volatile`. - + location of a static initializable variable containing 0 @@ -17380,6 +18072,30 @@ the pointer passed to it should not be `volatile`. + + Counterpart to g_once_init_enter_pointer(). Expects a location of a static +`NULL`-initialized initialization variable, and an initialization value +other than `NULL`. Sets the variable to the initialization value, and +releases concurrent threads blocking in g_once_init_enter_pointer() on this +initialization variable. + +This functions behaves in the same way as g_once_init_leave(), but +can be used to initialize pointers (or #guintptr) instead of #gsize. + + + + + + location of a static initializable variable + containing `NULL` + + + + new non-`NULL` value for `*location` + + + + The possible statuses of a one-time initialization function @@ -17463,159 +18179,9 @@ options. - The GOption commandline parser is intended to be a simpler replacement -for the popt library. It supports short and long commandline options, -as shown in the following example: - -`testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` - -The example demonstrates a number of features of the GOption -commandline parser: - -- Options can be single letters, prefixed by a single dash. - -- Multiple short options can be grouped behind a single dash. - -- Long options are prefixed by two consecutive dashes. - -- Options can have an extra argument, which can be a number, a string or - a filename. For long options, the extra argument can be appended with - an equals sign after the option name, which is useful if the extra - argument starts with a dash, which would otherwise cause it to be - interpreted as another option. - -- Non-option arguments are returned to the application as rest arguments. - -- An argument consisting solely of two dashes turns off further parsing, - any remaining arguments (even those starting with a dash) are returned - to the application as rest arguments. - -Another important feature of GOption is that it can automatically -generate nicely formatted help output. Unless it is explicitly turned -off with g_option_context_set_help_enabled(), GOption will recognize -the `--help`, `-?`, `--help-all` and `--help-groupname` options -(where `groupname` is the name of a #GOptionGroup) and write a text -similar to the one shown in the following example to stdout. - -|[ -Usage: - testtreemodel [OPTION...] - test tree model performance - -Help Options: - -h, --help Show help options - --help-all Show all help options - --help-gtk Show GTK Options - -Application Options: - -r, --repeats=N Average over N repetitions - -m, --max-size=M Test up to 2^M items - --display=DISPLAY X display to use - -v, --verbose Be verbose - -b, --beep Beep when done - --rand Randomize the data -]| - -GOption groups options in #GOptionGroups, which makes it easy to -incorporate options from multiple sources. The intended use for this is -to let applications collect option groups from the libraries it uses, -add them to their #GOptionContext, and parse all options by a single call -to g_option_context_parse(). See gtk_get_option_group() for an example. - -If an option is declared to be of type string or filename, GOption takes -care of converting it to the right encoding; strings are returned in -UTF-8, filenames are returned in the GLib filename encoding. Note that -this only works if setlocale() has been called before -g_option_context_parse(). - -Here is a complete example of setting up GOption to parse the example -commandline above and produce the example help output. -|[<!-- language="C" --> -static gint repeats = 2; -static gint max_size = 8; -static gboolean verbose = FALSE; -static gboolean beep = FALSE; -static gboolean randomize = FALSE; - -static GOptionEntry entries[] = -{ - { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" }, - { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, - { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, - { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, - { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, - G_OPTION_ENTRY_NULL -}; - -int -main (int argc, char *argv[]) -{ - GError *error = NULL; - GOptionContext *context; - - context = g_option_context_new ("- test tree model performance"); - g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); - g_option_context_add_group (context, gtk_get_option_group (TRUE)); - if (!g_option_context_parse (context, &argc, &argv, &error)) - { - g_print ("option parsing failed: %s\n", error->message); - exit (1); - } - - ... - -} -]| - -On UNIX systems, the argv that is passed to main() has no particular -encoding, even to the extent that different parts of it may have -different encodings. In general, normal arguments and flags will be -in the current locale and filenames should be considered to be opaque -byte strings. Proper use of %G_OPTION_ARG_FILENAME vs -%G_OPTION_ARG_STRING is therefore important. - -Note that on Windows, filenames do have an encoding, but using -#GOptionContext with the argv as passed to main() will result in a -program that can only accept commandline arguments with characters -from the system codepage. This can cause problems when attempting to -deal with filenames containing Unicode characters that fall outside -of the codepage. - -A solution to this is to use g_win32_get_command_line() and -g_option_context_parse_strv() which will properly handle full Unicode -filenames. If you are using #GApplication, this is done -automatically for you. - -The following example shows how you can use #GOptionContext directly -in order to correctly deal with Unicode filenames on Windows: - -|[<!-- language="C" --> -int -main (int argc, char **argv) -{ - GError *error = NULL; - GOptionContext *context; - gchar **args; - -#ifdef G_OS_WIN32 - args = g_win32_get_command_line (); -#else - args = g_strdupv (argv); -#endif - - // set up context - - if (!g_option_context_parse_strv (context, &args, &error)) - { - // error happened - } - - ... - - g_strfreev (args); - - ... -} -]| + A `GOptionContext` struct defines which options +are accepted by the commandline option parser. The struct has only private +fields and should not be directly accessed. Adds a #GOptionGroup to the @context, so that parsing with @context will recognize the options in the group. Note that this will take @@ -17669,7 +18235,7 @@ Please note that parsed arguments need to be freed separately (see - + a #GOptionContext @@ -18082,7 +18648,7 @@ below the usage line, use g_option_context_set_summary(). Note that the @parameter_string is translated using the function set with g_option_context_set_translate_func(), so it should normally be passed untranslated. - + a newly created #GOptionContext, which must be freed with g_option_context_free() after use. @@ -18460,12 +19026,9 @@ and all memory allocated by the @group is released. - Specifies one of the possible types of byte order -(currently unused). See %G_BYTE_ORDER. - The value of pi (ratio of circle's circumference to its diameter). @@ -18474,11 +19037,9 @@ when printing a #GPid. - Pi divided by 2. - Pi divided by 4. @@ -18575,12 +19136,12 @@ set_local_count (gint count) - + `GPathBuf` is a helper type that allows you to easily build paths from individual elements, using the platform specific conventions for path separators. -|[<!-- language="C" --> +```c g_auto (GPathBuf) path; g_path_buf_init (&path); @@ -18591,11 +19152,11 @@ g_path_buf_push (&path, "echo"); g_autofree char *echo = g_path_buf_to_path (&path); g_assert_cmpstr (echo, ==, "/usr/bin/echo"); -]| +``` You can also load a full path and then operate on its components: -|[<!-- language="C" --> +```c g_auto (GPathBuf) path; g_path_buf_init_from_path (&path, "/usr/bin/echo"); @@ -18605,9 +19166,7 @@ g_path_buf_push (&path, "sh"); g_autofree char *sh = g_path_buf_to_path (&path); g_assert_cmpstr (sh, ==, "/usr/bin/sh"); -]| - -`GPathBuf` is available since GLib 2.76. +``` @@ -18931,8 +19490,22 @@ This function can be passed to g_hash_table_new() as the - A GPatternSpec struct is the 'compiled' form of a pattern. This -structure is opaque and its fields cannot be accessed directly. + A `GPatternSpec` struct is the 'compiled' form of a glob-style pattern. + +The [func@GLib.pattern_match_simple] and [method@GLib.PatternSpec.match] functions +match a string against a pattern containing '*' and '?' wildcards with similar +semantics as the standard `glob()` function: '*' matches an arbitrary, +possibly empty, string, '?' matches an arbitrary character. + +Note that in contrast to `glob()`, the '/' character can be matched by +the wildcards, there are no '[...]' character ranges and '*' and '?' +can not be escaped to include them literally in a pattern. + +When multiple strings must be matched against the same pattern, it is better +to compile the pattern to a [struct@GLib.PatternSpec] using +[ctor@GLib.PatternSpec.new] and use [method@GLib.PatternSpec.match_string] +instead of [func@GLib.pattern_match_simple]. This avoids the overhead of repeated +pattern compilation. Compiles a pattern to a #GPatternSpec. @@ -19195,6 +19768,21 @@ the #GDestroyNotify for @key is not called on the old value. + + Creates a new #GPrivate. + dynamic allocation of #GPrivate is a bad idea. Use + static storage and G_PRIVATE_INIT() instead. + + a newly allocated #GPrivate (which can never be destroyed) + + + + + a #GDestroyNotify + + + + Contains the public fields of a pointer array. @@ -20412,14 +21000,14 @@ first argument and the given user data as the second argument. user data passed to @func - + a #GCompareFunc to call for each element. It should return 0 when the desired element is found - + Calls @func for each element in the queue passing @user_data to the function. @@ -20433,7 +21021,7 @@ not modify any part of the queue after that element. a #GQueue - + the function to call for each element's data @@ -20632,7 +21220,7 @@ data at the tail of the queue. - + Inserts @data into @queue using @func to determine the new position. @@ -20646,7 +21234,7 @@ data at the tail of the queue. the data to insert - + the #GCompareDataFunc used to compare elements in the queue. It is called with two elements of the @queue and @user_data. It should return 0 if the elements are equal, a negative value if the first @@ -21045,7 +21633,7 @@ data at the tail of the queue. - + Sorts @queue using @compare_func. @@ -21055,7 +21643,7 @@ data at the tail of the queue. a #GQueue - + the #GCompareDataFunc used to sort @queue. This function is passed two elements of the queue and should return 0 if they are equal, a negative value if the first comes before the second, and @@ -21348,14 +21936,56 @@ by the current thread leads to undefined behaviour. - + The GRand struct is an opaque data structure. It should only be accessed through the g_rand_* functions. - + + Creates a new random number generator initialized with a seed taken +either from `/dev/urandom` (if existing) or from the current time +(as a fallback). + +On Windows, the seed is taken from rand_s(). + + the new #GRand + + + + + Creates a new random number generator initialized with @seed. + + the new #GRand + + + + + a value to initialize the random number generator + + + + + + Creates a new random number generator initialized with @seed. + + the new #GRand + + + + + an array of seeds to initialize the random number generator + + + + an array of seeds to initialize the random number + generator + + + + + Copies a #GRand into a new one with the same exact state as before. This way you can take a snapshot of the random number generator for replaying later. - + the new #GRand @@ -21490,48 +22120,6 @@ your application. - - Creates a new random number generator initialized with a seed taken -either from `/dev/urandom` (if existing) or from the current time -(as a fallback). - -On Windows, the seed is taken from rand_s(). - - the new #GRand - - - - - Creates a new random number generator initialized with @seed. - - the new #GRand - - - - - a value to initialize the random number generator - - - - - - Creates a new random number generator initialized with @seed. - - the new #GRand - - - - - an array of seeds to initialize the random number generator - - - - an array of seeds to initialize the random number - generator - - - - The GRecMutex struct is an opaque data structure to represent a @@ -21661,9 +22249,11 @@ locked by the current thread leads to undefined behaviour. - The g_regex_*() functions implement regular -expression pattern matching using syntax and semantics similar to -Perl regular expression. + A `GRegex` is the "compiled" form of a regular expression pattern. + +`GRegex` implements regular expression pattern matching using syntax and +semantics similar to Perl regular expression. See the +[PCRE documentation](man:pcrepattern(3)) for the syntax definition. Some functions accept a @start_position argument, setting it differs from just passing over a shortened string and setting %G_REGEX_MATCH_NOTBOL @@ -21697,23 +22287,21 @@ separator, U+2028), or PS (paragraph separator, U+2029). The behaviour of the dot, circumflex, and dollar metacharacters are affected by newline characters, the default is to recognize any newline character (the same characters recognized by "\R"). This can be changed -with %G_REGEX_NEWLINE_CR, %G_REGEX_NEWLINE_LF and %G_REGEX_NEWLINE_CRLF -compile options, and with %G_REGEX_MATCH_NEWLINE_ANY, -%G_REGEX_MATCH_NEWLINE_CR, %G_REGEX_MATCH_NEWLINE_LF and -%G_REGEX_MATCH_NEWLINE_CRLF match options. These settings are also -relevant when compiling a pattern if %G_REGEX_EXTENDED is set, and an +with `G_REGEX_NEWLINE_CR`, `G_REGEX_NEWLINE_LF` and `G_REGEX_NEWLINE_CRLF` +compile options, and with `G_REGEX_MATCH_NEWLINE_ANY`, +`G_REGEX_MATCH_NEWLINE_CR`, `G_REGEX_MATCH_NEWLINE_LF` and +`G_REGEX_MATCH_NEWLINE_CRLF` match options. These settings are also +relevant when compiling a pattern if `G_REGEX_EXTENDED` is set, and an unescaped "#" outside a character class is encountered. This indicates a comment that lasts until after the next newline. -Creating and manipulating the same #GRegex structure from different -threads is not a problem as #GRegex does not modify its internal -state between creation and destruction, on the other hand #GMatchInfo +Creating and manipulating the same `GRegex` structure from different +threads is not a problem as `GRegex` does not modify its internal +state between creation and destruction, on the other hand `GMatchInfo` is not threadsafe. The regular expressions low-level functionalities are obtained through -the excellent -[PCRE](http://www.pcre.org/) -library written by Philip Hazel. +the excellent [PCRE](http://www.pcre.org/) library written by Philip Hazel. Compiles the regular expression to an internal form, and does the initial setup of the #GRegex structure. @@ -22191,7 +22779,7 @@ begins with any kind of lookbehind assertion, such as "\b". - + Replaces occurrences of the pattern in regex with the output of @eval for that occurrence. @@ -22264,7 +22852,7 @@ g_hash_table_destroy (h); options for the match - + a function to call for each match @@ -23046,14 +23634,232 @@ to g_regex_replace_eval(), and it should append the replacement to patterns this can only happen for pattern containing "\K". Since: 2.34 + + A `GRelation` is a table of data which can be indexed on any number +of fields, rather like simple database tables. A `GRelation` contains +a number of records, called tuples. Each record contains a number of +fields. Records are not ordered, so it is not possible to find the +record at a particular index. + +Note that `GRelation` tables are currently limited to 2 fields. + +To create a `GRelation`, use [func@GLib.Relation.new]. + +To specify which fields should be indexed, use [method@GLib.Relation.index]. +Note that this must be called before any tuples are added to the +`GRelation`. + +To add records to a `GRelation` use [method@GLib.Relation.insert]. + +To determine if a given record appears in a `GRelation`, use +[method@GLib.Relation.exists]. Note that fields are compared directly, so +pointers must point to the exact same position (i.e. different +copies of the same string will not match.) + +To count the number of records which have a particular value in a +given field, use [method@GLib.Relation.count]. + +To get all the records which have a particular value in a given +field, use [method@GLib.Relation.select]. To access fields of the resulting +records, use [method@GLib.Tuples.index]. To free the resulting records use +[method@GLib.Tuples.destroy]. + +To delete all records which have a particular value in a given +field, use [method@GLib.Relation.delete]. + +To destroy the `GRelation`, use [method@GLib.Relation.destroy]. + +To help debug `GRelation` objects, use [method@GLib.Relation.print]. + +`GRelation` has been marked as deprecated, since this API has never +been fully implemented, is not very actively maintained and rarely +used. + Rarely used API + + Returns the number of tuples in a #GRelation that have the given +value in the given field. + Rarely used API + + the number of matches. + + + + + a #GRelation. + + + + the value to compare with. + + + + the field of each record to match. + + + + + + Deletes any records from a #GRelation that have the given key value +in the given field. + Rarely used API + + the number of records deleted. + + + + + a #GRelation. + + + + the value to compare with. + + + + the field of each record to match. + + + + + + Destroys the #GRelation, freeing all memory allocated. However, it +does not free memory allocated for the tuple data, so you should +free that first if appropriate. + Rarely used API + + + + + + a #GRelation. + + + + + + Returns %TRUE if a record with the given values exists in a +#GRelation. Note that the values are compared directly, so that, for +example, two copies of the same string will not match. + Rarely used API + + %TRUE if a record matches. + + + + + a #GRelation. + + + + the fields of the record to compare. The number must match + the number of fields in the #GRelation. + + + + + + Creates an index on the given field. Note that this must be called +before any records are added to the #GRelation. + Rarely used API + + + + + + a #GRelation. + + + + the field to index, counting from 0. + + + + a function to produce a hash value from the field data. + + + + a function to compare two values of the given field. + + + + + + Inserts a record into a #GRelation. + Rarely used API + + + + + + a #GRelation. + + + + the fields of the record to add. These must match the + number of fields in the #GRelation, and of type #gpointer + or #gconstpointer. + + + + + + Outputs information about all records in a #GRelation, as well as +the indexes. It is for debugging. + Rarely used API + + + + + + a #GRelation. + + + + + + Returns all of the tuples which have the given key in the given +field. Use g_tuples_index() to access the returned records. The +returned records should be freed with g_tuples_destroy(). + Rarely used API + + the records (tuples) that matched. + + + + + a #GRelation. + + + + the value to compare with. + + + + the field of each record to match. + + + + + + Creates a new #GRelation with the given number of fields. Note that +currently the number of fields must be 2. + Rarely used API + + a new #GRelation. + + + + + the number of fields. + + + + + - The search path separator character. -This is ':' on UNIX machines and ';' under Windows. - The search path separator as a string. -This is ":" on UNIX machines and ";" under Windows. @@ -23229,7 +24035,7 @@ g_slist_free_full (another_list, g_object_unref); - + a copy function used to copy every element in the list @@ -23317,7 +24123,7 @@ given user data. user data passed to the function - + the function to call for each element. It should return 0 when the desired element is found @@ -23339,7 +24145,7 @@ not modify any part of the list after that element. - + the function to call with each element's data @@ -23517,7 +24323,7 @@ comparison function to determine its position. the data for the new element - + the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -23545,7 +24351,7 @@ comparison function to determine its position. the data for the new element - + the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. @@ -23638,6 +24444,11 @@ check @list against %NULL. + + + + + Gets the position of the given element in the #GSList (starting from 0). @@ -23692,6 +24503,16 @@ list = g_slist_prepend (list, "first"); + + + + + + + + + + Removes an element from a #GSList. If two elements contain the same data, only the first is removed. @@ -23804,7 +24625,7 @@ used is a stable sort. - + the comparison function used to sort the #GSList. This function is passed the data from 2 elements of the #GSList and should return 0 if they are equal, a negative value if the @@ -23829,7 +24650,7 @@ used is a stable sort. - + comparison function @@ -23867,26 +24688,11 @@ the #GSource from the main loop. - The square root of two. - Accepts a macro or a string and converts it into a string after -preprocessor argument expansion. For example, the following code: - -|[<!-- language="C" --> -#define AGE 27 -const gchar *greeting = G_STRINGIFY (AGE) " today!"; -]| - -is transformed by the preprocessor into (code equivalent to): - -|[<!-- language="C" --> -const gchar *greeting = "27 today!"; -]| - a macro or a string @@ -23897,43 +24703,28 @@ const gchar *greeting = "27 today!"; - Returns a member of a structure at a given offset, using the given type. - the type of the struct field - a pointer to a struct - the offset of the field from the start of the struct, - in bytes - Returns an untyped pointer to a given offset of a struct. - a pointer to a struct - the offset from the start of the struct, in bytes - Returns the offset, in bytes, of a member of a struct. - -Consider using standard C `offsetof()`, available since at least C89 -and C++98, in new code (but note that `offsetof()` returns a `size_t` -rather than a `long`). - a structure type, e.g. #GtkWidget - a field in the structure, e.g. @window @@ -23960,7 +24751,7 @@ rather than a `long`). - The data structure representing a lexical scanner. + `GScanner` provides a general-purpose lexical scanner. You should set @input_name after creating the scanner, since it is used by the default message handler when displaying @@ -24279,7 +25070,7 @@ any symbols that may have been added or removed in the new scope. - + Calls the given function for each of the symbol/value pairs in the given scope of the #GScanner. The function is passed the symbol and value of each pair, and the given @user_data @@ -24296,7 +25087,7 @@ parameter. the scope id - + the function to call for each symbol/value pair @@ -24667,7 +25458,7 @@ g_io_channel_seek_position() operation. - + Calls @func for each item in the sequence passing @user_data to the function. @func must not modify the sequence itself. @@ -24678,7 +25469,7 @@ to the function. @func must not modify the sequence itself. a #GSequence - + the function to call for each item in @seq @@ -24761,7 +25552,7 @@ to use g_sequence_is_empty() when comparing the length to zero. - + Inserts @data into @seq using @cmp_func to determine the new position. The sequence must already be sorted according to @cmp_func; otherwise the new position of @data is undefined. @@ -24787,7 +25578,7 @@ g_sequence_sort() or g_sequence_sort_iter(). the data to insert - + the function used to compare items in the sequence @@ -24797,7 +25588,7 @@ g_sequence_sort() or g_sequence_sort_iter(). - + Like g_sequence_insert_sorted(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @@ -24823,7 +25614,7 @@ g_sequence_sort() or g_sequence_sort_iter(). data for the new item - + the function used to compare iterators in the sequence @@ -24850,7 +25641,7 @@ implemented in O(1) running time. - + Returns an iterator pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data. If more than one item is equal, it is not guaranteed that it is the first which is @@ -24879,7 +25670,7 @@ unsorted. data to look up - + the function used to compare items in the sequence @@ -24889,7 +25680,7 @@ unsorted. - + Like g_sequence_lookup(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @@ -24915,7 +25706,7 @@ unsorted. data to look up - + the function used to compare iterators in the sequence @@ -24942,7 +25733,7 @@ unsorted. - + Returns an iterator pointing to the position where @data would be inserted according to @cmp_func and @cmp_data. @@ -24970,7 +25761,7 @@ unsorted. data for the new item - + the function used to compare items in the sequence @@ -24980,7 +25771,7 @@ unsorted. - + Like g_sequence_search(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @@ -25009,7 +25800,7 @@ unsorted. data for the new item - + the function used to compare iterators in the sequence @@ -25019,7 +25810,7 @@ unsorted. - + Sorts @seq using @cmp_func. @cmp_func is passed two items of @seq and should @@ -25034,7 +25825,7 @@ if the second comes before the first. a #GSequence - + the function used to sort the sequence @@ -25044,7 +25835,7 @@ if the second comes before the first. - + Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function @@ -25060,7 +25851,7 @@ iterator comes before the first. a #GSequence - + the function used to compare iterators in the sequence @@ -25070,7 +25861,7 @@ iterator comes before the first. - + Calls @func for each item in the range (@begin, @end) passing @user_data to the function. @func must not modify the sequence itself. @@ -25086,7 +25877,7 @@ itself. a #GSequenceIter - + a #GFunc @@ -25264,7 +26055,7 @@ function is called on the existing data that @iter pointed to. - + Moves the data pointed to by @iter to a new position as indicated by @cmp_func. This function should be called for items in a sequence already sorted according @@ -25283,7 +26074,7 @@ the second item comes before the first. A #GSequenceIter - + the function used to compare items in the sequence @@ -25293,7 +26084,7 @@ the second item comes before the first. - + Like g_sequence_sort_changed(), but uses a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as the compare function. @@ -25311,7 +26102,7 @@ iterator comes before the first. a #GSequenceIter - + the function used to compare iterators in the sequence @@ -25832,8 +26623,8 @@ name may be #NULL if it has never been set with g_source_set_name(). Gets the "ready time" of @source, as set by g_source_set_ready_time(). -Any time before the current monotonic time (including 0) is an -indication that the source will fire immediately. +Any time before or equal to the current monotonic time (including 0) +is an indication that the source will fire immediately. the monotonic ready time, -1 for "never" @@ -26811,8 +27602,606 @@ system call, depending on the platform and/or compiler being used. See g_stat() for more information. + + A #GStaticMutex works like a #GMutex. + +Prior to GLib 2.32, GStaticMutex had the significant advantage +that it doesn't need to be created at run-time, but can be defined +at compile-time. Since 2.32, #GMutex can be statically allocated +as well, and GStaticMutex has been deprecated. + +Here is a version of our give_me_next_number() example using +a GStaticMutex: +|[ + int + give_me_next_number (void) + { + static int current_number = 0; + int ret_val; + static GStaticMutex mutex = G_STATIC_MUTEX_INIT; + + g_static_mutex_lock (&mutex); + ret_val = current_number = calc_next_number (current_number); + g_static_mutex_unlock (&mutex); + + return ret_val; + } +]| + +Sometimes you would like to dynamically create a mutex. If you don't +want to require prior calling to g_thread_init(), because your code +should also be usable in non-threaded programs, you are not able to +use g_mutex_new() and thus #GMutex, as that requires a prior call to +g_thread_init(). In these cases you can also use a #GStaticMutex. +It must be initialized with g_static_mutex_init() before using it +and freed with with g_static_mutex_free() when not needed anymore to +free up any allocated resources. + +Even though #GStaticMutex is not opaque, it should only be used with +the following functions, as it is defined differently on different +platforms. + +All of the g_static_mutex_* functions apart from +g_static_mutex_get_mutex() can also be used even if g_thread_init() +has not yet been called. Then they do nothing, apart from +g_static_mutex_trylock() which does nothing but returning %TRUE. + +All of the g_static_mutex_* functions are actually macros. Apart from +taking their addresses, you can however use them as if they were +functions. + + + + + Releases all resources allocated to @mutex. + +You don't have to call this functions for a #GStaticMutex with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticMutex as a member of a structure and the structure is +freed, you should also free the #GStaticMutex. + +Calling g_static_mutex_free() on a locked mutex may result in +undefined behaviour. + Use g_mutex_clear() + + + + + + a #GStaticMutex to be freed. + + + + + + + + + + + + + + + + Initializes @mutex. +Alternatively you can initialize it with %G_STATIC_MUTEX_INIT. + Use g_mutex_init() + + + + + + a #GStaticMutex to be initialized. + + + + + + + A #GStaticPrivate works almost like a #GPrivate, but it has one +significant advantage. It doesn't need to be created at run-time +like a #GPrivate, but can be defined at compile-time. This is +similar to the difference between #GMutex and #GStaticMutex. + +Now look at our give_me_next_number() example with #GStaticPrivate: +|[ + int + give_me_next_number () + { + static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; + int *current_number = g_static_private_get (&current_number_key); + + if (!current_number) + { + current_number = g_new (int, 1); + *current_number = 0; + g_static_private_set (&current_number_key, current_number, g_free); + } + + *current_number = calc_next_number (*current_number); + + return *current_number; + } +]| + + + + + Releases all resources allocated to @private_key. + +You don't have to call this functions for a #GStaticPrivate with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticPrivate as a member of a structure and the structure is +freed, you should also free the #GStaticPrivate. + + + + + + a #GStaticPrivate to be freed + + + + + + Works like g_private_get() only for a #GStaticPrivate. + +This function works even if g_thread_init() has not yet been called. + + the corresponding pointer + + + + + a #GStaticPrivate + + + + + + Initializes @private_key. Alternatively you can initialize it with +%G_STATIC_PRIVATE_INIT. + + + + + + a #GStaticPrivate to be initialized + + + + + + Sets the pointer keyed to @private_key for the current thread and +the function @notify to be called with that pointer (%NULL or +non-%NULL), whenever the pointer is set again or whenever the +current thread ends. + +This function works even if g_thread_init() has not yet been called. +If g_thread_init() is called later, the @data keyed to @private_key +will be inherited only by the main thread, i.e. the one that called +g_thread_init(). + +@notify is used quite differently from @destructor in g_private_new(). + + + + + + a #GStaticPrivate + + + + the new pointer + + + + a function to be called with the pointer whenever the + current thread ends or sets this pointer again + + + + + + + The #GStaticRWLock struct represents a read-write lock. A read-write +lock can be used for protecting data that some portions of code only +read from, while others also write. In such situations it is +desirable that several readers can read at once, whereas of course +only one writer may write at a time. + +Take a look at the following example: +|[ + GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT; + GPtrArray *array; + + gpointer + my_array_get (guint index) + { + gpointer retval = NULL; + + if (!array) + return NULL; + + g_static_rw_lock_reader_lock (&rwlock); + if (index < array->len) + retval = g_ptr_array_index (array, index); + g_static_rw_lock_reader_unlock (&rwlock); + + return retval; + } + + void + my_array_set (guint index, gpointer data) + { + g_static_rw_lock_writer_lock (&rwlock); + + if (!array) + array = g_ptr_array_new (); + + if (index >= array->len) + g_ptr_array_set_size (array, index + 1); + g_ptr_array_index (array, index) = data; + + g_static_rw_lock_writer_unlock (&rwlock); + } +]| + +This example shows an array which can be accessed by many readers +(the my_array_get() function) simultaneously, whereas the writers +(the my_array_set() function) will only be allowed once at a time +and only if no readers currently access the array. This is because +of the potentially dangerous resizing of the array. Using these +functions is fully multi-thread safe now. + +Most of the time, writers should have precedence over readers. That +means, for this implementation, that as soon as a writer wants to +lock the data, no other reader is allowed to lock the data, whereas, +of course, the readers that already have locked the data are allowed +to finish their operation. As soon as the last reader unlocks the +data, the writer will lock it. + +Even though #GStaticRWLock is not opaque, it should only be used +with the following functions. + +All of the g_static_rw_lock_* functions can be used even if +g_thread_init() has not been called. Then they do nothing, apart +from g_static_rw_lock_*_trylock, which does nothing but returning %TRUE. + +A read-write lock has a higher overhead than a mutex. For example, both +g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock() have +to lock and unlock a #GStaticMutex, so it takes at least twice the time +to lock and unlock a #GStaticRWLock that it does to lock and unlock a +#GStaticMutex. So only data structures that are accessed by multiple +readers, and which keep the lock for a considerable time justify a +#GStaticRWLock. The above example most probably would fare better with a +#GStaticMutex. + Use a #GRWLock instead + + + + + + + + + + + + + + + + + + + + + + + Releases all resources allocated to @lock. + +You don't have to call this functions for a #GStaticRWLock with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticRWLock as a member of a structure, and the structure is +freed, you should also free the #GStaticRWLock. + Use a #GRWLock instead + + + + + + a #GStaticRWLock to be freed. + + + + + + A #GStaticRWLock must be initialized with this function before it +can be used. Alternatively you can initialize it with +%G_STATIC_RW_LOCK_INIT. + Use g_rw_lock_init() instead + + + + + + a #GStaticRWLock to be initialized. + + + + + + Locks @lock for reading. There may be unlimited concurrent locks for +reading of a #GStaticRWLock at the same time. If @lock is already +locked for writing by another thread or if another thread is already +waiting to lock @lock for writing, this function will block until +@lock is unlocked by the other writing thread and no other writing +threads want to lock @lock. This lock has to be unlocked by +g_static_rw_lock_reader_unlock(). + +#GStaticRWLock is not recursive. It might seem to be possible to +recursively lock for reading, but that can result in a deadlock, due +to writer preference. + Use g_rw_lock_reader_lock() instead + + + + + + a #GStaticRWLock to lock for reading. + + + + + + Tries to lock @lock for reading. If @lock is already locked for +writing by another thread or if another thread is already waiting to +lock @lock for writing, immediately returns %FALSE. Otherwise locks +@lock for reading and returns %TRUE. This lock has to be unlocked by +g_static_rw_lock_reader_unlock(). + Use g_rw_lock_reader_trylock() instead + + %TRUE, if @lock could be locked for reading + + + + + a #GStaticRWLock to lock for reading + + + + + + Unlocks @lock. If a thread waits to lock @lock for writing and all +locks for reading have been unlocked, the waiting thread is woken up +and can lock @lock for writing. + Use g_rw_lock_reader_unlock() instead + + + + + + a #GStaticRWLock to unlock after reading + + + + + + Locks @lock for writing. If @lock is already locked for writing or +reading by other threads, this function will block until @lock is +completely unlocked and then lock @lock for writing. While this +functions waits to lock @lock, no other thread can lock @lock for +reading. When @lock is locked for writing, no other thread can lock +@lock (neither for reading nor writing). This lock has to be +unlocked by g_static_rw_lock_writer_unlock(). + Use g_rw_lock_writer_lock() instead + + + + + + a #GStaticRWLock to lock for writing + + + + + + Tries to lock @lock for writing. If @lock is already locked (for +either reading or writing) by another thread, it immediately returns +%FALSE. Otherwise it locks @lock for writing and returns %TRUE. This +lock has to be unlocked by g_static_rw_lock_writer_unlock(). + Use g_rw_lock_writer_trylock() instead + + %TRUE, if @lock could be locked for writing + + + + + a #GStaticRWLock to lock for writing + + + + + + Unlocks @lock. If a thread is waiting to lock @lock for writing and +all locks for reading have been unlocked, the waiting thread is +woken up and can lock @lock for writing. If no thread is waiting to +lock @lock for writing, and some thread or threads are waiting to +lock @lock for reading, the waiting threads are woken up and can +lock @lock for reading. + Use g_rw_lock_writer_unlock() instead + + + + + + a #GStaticRWLock to unlock after writing. + + + + + + + A #GStaticRecMutex works like a #GStaticMutex, but it can be locked +multiple times by one thread. If you enter it n times, you have to +unlock it n times again to let other threads lock it. An exception +is the function g_static_rec_mutex_unlock_full(): that allows you to +unlock a #GStaticRecMutex completely returning the depth, (i.e. the +number of times this mutex was locked). The depth can later be used +to restore the state of the #GStaticRecMutex by calling +g_static_rec_mutex_lock_full(). In GLib 2.32, #GStaticRecMutex has +been deprecated in favor of #GRecMutex. + +Even though #GStaticRecMutex is not opaque, it should only be used +with the following functions. + +All of the g_static_rec_mutex_* functions can be used even if +g_thread_init() has not been called. Then they do nothing, apart +from g_static_rec_mutex_trylock(), which does nothing but returning +%TRUE. + + + + + + + + Releases all resources allocated to a #GStaticRecMutex. + +You don't have to call this functions for a #GStaticRecMutex with an +unbounded lifetime, i.e. objects declared 'static', but if you have +a #GStaticRecMutex as a member of a structure and the structure is +freed, you should also free the #GStaticRecMutex. + Use g_rec_mutex_clear() + + + + + + a #GStaticRecMutex to be freed. + + + + + + A #GStaticRecMutex must be initialized with this function before it +can be used. Alternatively you can initialize it with +%G_STATIC_REC_MUTEX_INIT. + Use g_rec_mutex_init() + + + + + + a #GStaticRecMutex to be initialized. + + + + + + Locks @mutex. If @mutex is already locked by another thread, the +current thread will block until @mutex is unlocked by the other +thread. If @mutex is already locked by the calling thread, this +functions increases the depth of @mutex and returns immediately. + Use g_rec_mutex_lock() + + + + + + a #GStaticRecMutex to lock. + + + + + + Works like calling g_static_rec_mutex_lock() for @mutex @depth times. + Use g_rec_mutex_lock() + + + + + + a #GStaticRecMutex to lock. + + + + number of times this mutex has to be unlocked to be + completely unlocked. + + + + + + Tries to lock @mutex. If @mutex is already locked by another thread, +it immediately returns %FALSE. Otherwise it locks @mutex and returns +%TRUE. If @mutex is already locked by the calling thread, this +functions increases the depth of @mutex and immediately returns +%TRUE. + Use g_rec_mutex_trylock() + + %TRUE, if @mutex could be locked. + + + + + a #GStaticRecMutex to lock. + + + + + + Unlocks @mutex. Another thread will be allowed to lock @mutex only +when it has been unlocked as many times as it had been locked +before. If @mutex is completely unlocked and another thread is +blocked in a g_static_rec_mutex_lock() call for @mutex, it will be +woken and can lock @mutex itself. + Use g_rec_mutex_unlock() + + + + + + a #GStaticRecMutex to unlock. + + + + + + Completely unlocks @mutex. If another thread is blocked in a +g_static_rec_mutex_lock() call for @mutex, it will be woken and can +lock @mutex itself. This function returns the number of times that +@mutex has been locked by the current thread. To restore the state +before the call to g_static_rec_mutex_unlock_full() you can call +g_static_rec_mutex_lock_full() with the depth returned by this +function. + Use g_rec_mutex_unlock() + + number of times @mutex has been locked by the current + thread. + + + + + a #GStaticRecMutex to completely unlock. + + + + + - The GString struct contains the public fields of a GString. + A `GString` is an object that handles the memory management of a C string. + +The emphasis of `GString` is on text, typically UTF-8. Crucially, the "str" member +of a `GString` is guaranteed to have a trailing nul character, and it is therefore +always safe to call functions such as `strchr()` or `strdup()` on it. + +However, a `GString` can also hold arbitrary binary data, because it has a "len" member, +which includes any possible embedded nul characters in the data. Conceptually then, +`GString` is like a `GByteArray` with the addition of many convenience methods for +text, and a guaranteed nul terminator. points to the character data. It may move as text is added. The @str field is null-terminated and so @@ -27605,8 +28994,29 @@ the arguments to the format string are passed as a va_list. - An opaque data structure representing String Chunks. -It should only be accessed by using the following functions. + `GStringChunk` provides efficient storage of groups of strings + +String chunks are used to store groups of strings. Memory is +allocated in blocks, and as strings are added to the `GStringChunk` +they are copied into the next free position in a block. When a block +is full a new block is allocated. + +When storing a large number of strings, string chunks are more +efficient than using [func@GLib.strdup] since fewer calls to `malloc()` +are needed, and less memory is wasted in memory allocation overheads. + +By adding strings with [method@GLib.StringChunk.insert_const] it is also +possible to remove duplicates. + +To create a new `GStringChunk` use [func@GLib.StringChunk.new]. + +To add strings to a `GStringChunk` use [method@GLib.StringChunk.insert]. + +To add strings to a `GStringChunk`, but without duplicating strings +which are already in the `GStringChunk`, use [method@GLib.StringChunk.insert_const]. + +To free the entire `GStringChunk` use [method@GLib.StringChunk.free]. +It is not possible to free individual strings. Frees all strings contained within the #GStringChunk. After calling g_string_chunk_clear() it is not safe to @@ -27629,7 +29039,7 @@ access any of the strings which were contained within it. - + a #GStringChunk @@ -27725,7 +29135,7 @@ though you should not change anything after the end of the string. Creates a new #GStringChunk. - + a new #GStringChunk @@ -27740,18 +29150,25 @@ though you should not change anything after the end of the string. - - #GStrvBuilder is a method of easily building dynamically sized -NULL-terminated string arrays. + + `GStrvBuilder` is a helper object to build a %NULL-terminated string arrays. The following example shows how to build a two element array: -|[<!-- language="C" --> +```c g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); g_strv_builder_add (builder, "hello"); g_strv_builder_add (builder, "world"); g_auto(GStrv) array = g_strv_builder_end (builder); -]| +``` + + Creates a new #GStrvBuilder with a reference count of 1. +Use g_strv_builder_unref() on the returned value when no longer needed. + + the new #GStrvBuilder + + + Add a string to the end of the array. @@ -27827,7 +29244,7 @@ Since 2.68 - + Atomically increments the reference count of @builder by one. This function is thread-safe and may be called from any thread. @@ -27841,6 +29258,26 @@ This function is thread-safe and may be called from any thread. + + Add a string to the end of the array. After @value belongs to the +#GStrvBuilder and may no longer be modified by the caller. + +Since 2.80 + + + + + + a #GStrvBuilder + + + + a string. + Ownership of the string is transferred to the #GStrvBuilder + + + + Decreases the reference count on @builder. @@ -27856,14 +29293,6 @@ associated with the #GStrvBuilder. - - Creates a new #GStrvBuilder with a reference count of 1. -Use g_strv_builder_unref() on the returned value when no longer needed. - - the new #GStrvBuilder - - - Creates a unique temporary directory for each unit test and uses @@ -27911,6 +29340,9 @@ to create the directory if it doesn’t exist. Evaluates to a time span of one second. + + + Works like g_mutex_trylock(), but for a lock defined with %G_LOCK_DEFINE. @@ -28267,7 +29699,7 @@ which is deprecated. g_test_trap_subprocess() uses It is redirected to `/dev/null` otherwise. - + The #GThread struct represents a running thread. This struct is returned by g_thread_new() or g_thread_try_new(). You can obtain the #GThread struct representing the current thread by @@ -28281,6 +29713,18 @@ explicitly. The structure is opaque -- none of its fields may be directly accessed. + + + + + + + + + + + + This function creates a new thread. The new thread starts by invoking @func with the argument data. The thread will run until @func returns @@ -28394,6 +29838,23 @@ want to keep the GThread alive beyond the g_thread_join() call. + + This function does nothing. + Thread priorities no longer have any effect. + + + + + + a #GThread. + + + + ignored + + + + Decrease the reference count on @thread, possibly freeing all resources associated with it. @@ -28411,6 +29872,74 @@ if you don't need it anymore. + + This function creates a new thread. + +The new thread executes the function @func with the argument @data. +If the thread was created successfully, it is returned. + +@error can be %NULL to ignore errors, or non-%NULL to report errors. +The error is set, if and only if the function returns %NULL. + +This function returns a reference to the created thread only if +@joinable is %TRUE. In that case, you must free this reference by +calling g_thread_unref() or g_thread_join(). If @joinable is %FALSE +then you should probably not touch the return value. + Use g_thread_new() instead + + the new #GThread on success + + + + + a function to execute in the new thread + + + + an argument to supply to the new thread + + + + should this thread be joinable? + + + + + + This function creates a new thread. + The @bound and @priority arguments are now ignored. +Use g_thread_new(). + + the new #GThread on success. + + + + + a function to execute in the new thread. + + + + an argument to supply to the new thread. + + + + a stack size for the new thread. + + + + should this thread be joinable? + + + + ignored + + + + ignored + + + + @@ -28440,6 +29969,86 @@ or or from within a #GThreadPool. + + Call @thread_func on all #GThreads that have been +created with g_thread_create(). + +Note that threads may decide to exit while @thread_func is +running, so without intimate knowledge about the lifetime of +foreign threads, @thread_func shouldn't access the GThread* +pointer passed in as first argument. However, @thread_func will +not be called for threads which are known to have exited already. + +Due to thread lifetime checks, this function has an execution complexity +which is quadratic in the number of existing threads. + There aren't many things you can do with a #GThread, + except comparing it with one that was returned from g_thread_create(). + There are better ways to find out if your thread is still alive. + + + + + + function to call for all #GThread structures + + + + second argument to @thread_func + + + + + + Indicates if g_thread_init() has been called. + + %TRUE if threads have been initialized. + + + + + If you use GLib from more than one thread, you must initialize the +thread system by calling g_thread_init(). + +Since version 2.24, calling g_thread_init() multiple times is allowed, +but nothing happens except for the first call. + +Since version 2.32, GLib does not support custom thread implementations +anymore and the @vtable parameter is ignored and you should pass %NULL. + +<note><para>g_thread_init() must not be called directly or indirectly +in a callback from GLib. Also no mutexes may be currently locked while +calling g_thread_init().</para></note> + +<note><para>To use g_thread_init() in your program, you have to link +with the libraries that the command <command>pkg-config --libs +gthread-2.0</command> outputs. This is not the case for all the +other thread-related functions of GLib. Those can be used without +having to link with the thread libraries.</para></note> + This function is no longer necessary. The GLib + threading system is automatically initialized at the start + of your program. + + + + + + a function table of type #GThreadFunctions, that provides + the entry points to the thread system to be used. Since 2.32, + this parameter is ignored and should always be %NULL + + + + + + + + + + + + + + This function returns the #GThread corresponding to the current thread. Note that this function does not increase @@ -28486,10 +30095,305 @@ or g_thread_try_new(). + + This function table is no longer used by g_thread_init() +to initialize the thread system. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - The #GThreadPool struct represents a thread pool. It has three -public read-only members, but the underlying struct is bigger, -so you must not copy this struct. + The `GThreadPool` struct represents a thread pool. + +A thread pool is useful when you wish to asynchronously fork out the execution of work +and continue working in your own thread. If that will happen often, the overhead of starting +and destroying a thread each time might be too high. In such cases reusing already started +threads seems like a good idea. And it indeed is, but implementing this can be tedious +and error-prone. + +Therefore GLib provides thread pools for your convenience. An added advantage is, that the +threads can be shared between the different subsystems of your program, when they are using GLib. + +To create a new thread pool, you use [func@GLib.ThreadPool.new]. +It is destroyed by [method@GLib.ThreadPool.free]. + +If you want to execute a certain task within a thread pool, use [method@GLib.ThreadPool.push]. + +To get the current number of running threads you call [method@GLib.ThreadPool.get_num_threads]. +To get the number of still unprocessed tasks you call [method@GLib.ThreadPool.unprocessed]. +To control the maximum number of threads for a thread pool, you use +[method@GLib.ThreadPool.get_max_threads]. and [method@GLib.ThreadPool.set_max_threads]. + +Finally you can control the number of unused threads, that are kept alive by GLib for future use. +The current number can be fetched with [func@GLib.ThreadPool.get_num_unused_threads]. +The maximum number can be controlled by [func@GLib.ThreadPool.get_max_unused_threads] and +[func@GLib.ThreadPool.set_max_unused_threads]. All currently unused threads +can be stopped by calling [func@GLib.ThreadPool.stop_unused_threads]. the function to execute in the threads of this pool @@ -28870,6 +30774,22 @@ regularly stop all unused threads e.g. from g_timeout_add(). + + Thread priorities. + Thread priorities no longer have any effect. + + a priority lower than normal + + + the default priority + + + a priority higher than normal + + + the highest priority + + Disambiguates a given time in two ways. @@ -29014,8 +30934,32 @@ g_date_time_unref (dt); - #GTimeZone is an opaque structure whose members cannot be accessed -directly. + A `GTimeZone` represents a time zone, at no particular point in time. + +The `GTimeZone` struct is refcounted and immutable. + +Each time zone has an identifier (for example, ‘Europe/London’) which is +platform dependent. See [ctor@GLib.TimeZone.new] for information on the +identifier formats. The identifier of a time zone can be retrieved using +[method@GLib.TimeZone.get_identifier]. + +A time zone contains a number of intervals. Each interval has an abbreviation +to describe it (for example, ‘PDT’), an offset to UTC and a flag indicating +if the daylight savings time is in effect during that interval. A time zone +always has at least one interval — interval 0. Note that interval abbreviations +are not the same as time zone identifiers (apart from ‘UTC’), and cannot be +passed to [ctor@GLib.TimeZone.new]. + +Every UTC time is contained within exactly one interval, but a given +local time may be contained within zero, one or two intervals (due to +incontinuities associated with daylight savings time). + +An interval may refer to a specific period of time (eg: the duration +of daylight savings time during 2010) or it may refer to many periods +of time that share the same properties (eg: all periods of daylight +savings time). It is also possible (usually for political reasons) +that some properties (like the abbreviation) change between intervals +without other properties changing. A version of g_time_zone_new_identifier() which returns the UTC time zone if @identifier could not be parsed or loaded. @@ -29349,7 +31293,11 @@ west of GMT, positive numbers for east). - Opaque datatype that records a start time. + `GTimer` records a start time, and counts microseconds elapsed since +that time. + +This is done somewhat differently on different platforms, and can be +tricky to get exactly right, so `GTimer` provides a portable/convenient interface. Resumes a timer that has previously been stopped with g_timer_stop(). g_timer_stop() must be called before using this @@ -29459,7 +31407,7 @@ difference between this end time and the start time. Creates a new timer, and starts timing (i.e. g_timer_start() is implicitly called for you). - + a new #GTimer. @@ -29610,9 +31558,20 @@ strings, for <option>--help</option> output. - Each piece of memory that is pushed onto the stack -is cast to a GTrashStack*. - #GTrashStack is deprecated without replacement + A `GTrashStack` is an efficient way to keep a stack of unused allocated +memory chunks. Each memory chunk is required to be large enough to hold +a `gpointer`. This allows the stack to be maintained without any space +overhead, since the stack pointers can be stored inside the memory chunks. + +There is no function to create a `GTrashStack`. A `NULL` `GTrashStack*` +is a perfectly valid empty stack. + +Each piece of memory that is pushed onto the stack is cast to a +`GTrashStack*`. + +There is no longer any good reason to use `GTrashStack`. If you have +extra pieces of memory, `free()` them and allocate them again later. + `GTrashStack` is deprecated without replacement pointer to the previous element of the stack, gets stored in the first `sizeof (gpointer)` @@ -29873,7 +31832,7 @@ the #GTree. - + Calls the given function for each of the key/value pairs in the #GTree. The function is passed the key and value of each pair, and the given @data parameter. The tree is traversed in sorted order. @@ -29890,7 +31849,7 @@ the tree, then walk the list and remove each item. a #GTree - + the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. @@ -29901,7 +31860,7 @@ the tree, then walk the list and remove each item. - + Calls the given function for each of the nodes in the #GTree. The function is passed the pointer to the particular node, and the given @data parameter. The tree traversal happens in-order. @@ -29918,7 +31877,7 @@ the tree, then walk the list and remove each item. a #GTree - + the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. @@ -30247,7 +32206,7 @@ if insertion would overflow the tree node counter. - + Searches a #GTree using @search_func. The @search_func is called with a pointer to the key of a key/value @@ -30267,7 +32226,7 @@ pairs that have a larger key. a #GTree - + a function used to search the #GTree @@ -30277,7 +32236,7 @@ pairs that have a larger key. - + Searches a #GTree using @search_func. The @search_func is called with a pointer to the key of a key/value @@ -30297,7 +32256,7 @@ pairs that have a larger key. a #GTree - + a function used to search the #GTree @@ -30328,7 +32287,7 @@ If the key does not exist in the #GTree, the function does nothing. - + Calls the given function for each node in the #GTree. The order of a balanced tree is somewhat arbitrary. If you just want to visit all nodes in sorted order, use @@ -30342,7 +32301,7 @@ If the key does not exist in the #GTree, the function does nothing. a #GTree - + the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. @@ -30457,6 +32416,57 @@ if the passed node was already the first one. + + The #GTuples struct is used to return records (or tuples) from the +#GRelation by g_relation_select(). It only contains one public +member - the number of records that matched. To access the matched +records, you must use g_tuples_index(). + Rarely used API + + the number of records that matched. + + + + Frees the records which were returned by g_relation_select(). This +should always be called after g_relation_select() when you are +finished with the records. The records are not removed from the +#GRelation. + Rarely used API + + + + + + the tuple data to free. + + + + + + Gets a field from the records returned by g_relation_select(). It +returns the given field of the record at the given index. The +returned value should not be changed. + Rarely used API + + the field of the record. + + + + + the tuple data, returned by g_relation_select(). + + + + the index of the record. + + + + the field to return. + + + + + @@ -30504,17 +32514,9 @@ decomposition of a single Unicode character. This is as defined by Unicode 6.1. - - Hints the compiler that the expression is unlikely to evaluate to -a true value. The compiler may use this information for optimizations. - -|[<!-- language="C" --> -if (G_UNLIKELY (random () == 1)) - g_print ("a random one"); -]| + - the expression @@ -30542,147 +32544,162 @@ if (G_UNLIKELY (random () == 1)) This macro is provided for code readability. - + These are the possible line break classifications. -Since new unicode versions may add new types here, applications should be ready +Since new Unicode versions may add new types here, applications should be ready to handle unknown values. They may be regarded as %G_UNICODE_BREAK_UNKNOWN. See [Unicode Line Breaking Algorithm](https://www.unicode.org/reports/tr14/). - + Mandatory Break (BK) - + Carriage Return (CR) - + Line Feed (LF) - + Attached Characters and Combining Marks (CM) - + Surrogates (SG) - + Zero Width Space (ZW) - + Inseparable (IN) - + Non-breaking ("Glue") (GL) - + Contingent Break Opportunity (CB) - + Space (SP) - + Break Opportunity After (BA) - + Break Opportunity Before (BB) - + Break Opportunity Before and After (B2) - + Hyphen (HY) - + Nonstarter (NS) - + Opening Punctuation (OP) - + Closing Punctuation (CL) - + Ambiguous Quotation (QU) - + Exclamation/Interrogation (EX) - + Ideographic (ID) - + Numeric (NU) - + Infix Separator (Numeric) (IS) - + Symbols Allowing Break After (SY) - + Ordinary Alphabetic and Symbol Characters (AL) - + Prefix (Numeric) (PR) - + Postfix (Numeric) (PO) - + Complex Content Dependent (South East Asian) (SA) - + Ambiguous (Alphabetic or Ideographic) (AI) - + Unknown (XX) - + Next Line (NL) - + Word Joiner (WJ) - + Hangul L Jamo (JL) - + Hangul V Jamo (JV) - + Hangul T Jamo (JT) - + Hangul LV Syllable (H2) - + Hangul LVT Syllable (H3) - + Closing Parenthesis (CP). Since 2.28. Deprecated: 2.70: Use %G_UNICODE_BREAK_CLOSE_PARENTHESIS instead. - + Closing Parenthesis (CP). Since 2.70 - + Conditional Japanese Starter (CJ). Since: 2.32 - + Hebrew Letter (HL). Since: 2.32 - + Regional Indicator (RI). Since: 2.36 - + Emoji Base (EB). Since: 2.50 - + Emoji Modifier (EM). Since: 2.50 - + Zero Width Joiner (ZWJ). Since: 2.50 + + Aksara (AK). Since: 2.80 +@G_UNICODE_BREAK_AKSARA_PRE_BASE (AP). Since: 2.80 +@G_UNICODE_BREAK_AKSARA_START (AS). Since: 2.80 +@G_UNICODE_BREAK_VIRAMA_FINAL (VF). Since: 2.80 +@G_UNICODE_BREAK_VIRAMA (VI). Since: 2.80 + + + + + + + + + - + The #GUnicodeScript enumeration identifies different writing systems. The values correspond to the names as defined in the Unicode standard. The enumeration has been added in GLib 2.14, @@ -30691,598 +32708,644 @@ and is interchangeable with #PangoScript. Note that new types may be added in the future. Applications should be ready to handle unknown values. See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr24/). - + a value never returned from g_unichar_get_script() - + a character used by multiple different scripts - + a mark glyph that takes its script from the base glyph to which it is attached - + Arabic - + Armenian - + Bengali - + Bopomofo - + Cherokee - + Coptic - + Cyrillic - + Deseret - + Devanagari - + Ethiopic - + Georgian - + Gothic - + Greek - + Gujarati - + Gurmukhi - + Han - + Hangul - + Hebrew - + Hiragana - + Kannada - + Katakana - + Khmer - + Lao - + Latin - + Malayalam - + Mongolian - + Myanmar - + Ogham - + Old Italic - + Oriya - + Runic - + Sinhala - + Syriac - + Tamil - + Telugu - + Thaana - + Thai - + Tibetan - + Canadian Aboriginal - + Yi - + Tagalog - + Hanunoo - + Buhid - + Tagbanwa - + Braille - + Cypriot - + Limbu - + Osmanya - + Shavian - + Linear B - + Tai Le - + Ugaritic - + New Tai Lue - + Buginese - + Glagolitic - + Tifinagh - + Syloti Nagri - + Old Persian - + Kharoshthi - + an unassigned code point - + Balinese - + Cuneiform - + Phoenician - + Phags-pa - + N'Ko - + Kayah Li. Since 2.16.3 - + Lepcha. Since 2.16.3 - + Rejang. Since 2.16.3 - + Sundanese. Since 2.16.3 - + Saurashtra. Since 2.16.3 - + Cham. Since 2.16.3 - + Ol Chiki. Since 2.16.3 - + Vai. Since 2.16.3 - + Carian. Since 2.16.3 - + Lycian. Since 2.16.3 - + Lydian. Since 2.16.3 - + Avestan. Since 2.26 - + Bamum. Since 2.26 - + Egyptian Hieroglpyhs. Since 2.26 - + Imperial Aramaic. Since 2.26 - + Inscriptional Pahlavi. Since 2.26 - + Inscriptional Parthian. Since 2.26 - + Javanese. Since 2.26 - + Kaithi. Since 2.26 - + Lisu. Since 2.26 - + Meetei Mayek. Since 2.26 - + Old South Arabian. Since 2.26 - + Old Turkic. Since 2.28 - + Samaritan. Since 2.26 - + Tai Tham. Since 2.26 - + Tai Viet. Since 2.26 - + Batak. Since 2.28 - + Brahmi. Since 2.28 - + Mandaic. Since 2.28 - + Chakma. Since: 2.32 - + Meroitic Cursive. Since: 2.32 - + Meroitic Hieroglyphs. Since: 2.32 - + Miao. Since: 2.32 - + Sharada. Since: 2.32 - + Sora Sompeng. Since: 2.32 - + Takri. Since: 2.32 - + Bassa. Since: 2.42 - + Caucasian Albanian. Since: 2.42 - + Duployan. Since: 2.42 - + Elbasan. Since: 2.42 - + Grantha. Since: 2.42 - + Kjohki. Since: 2.42 - + Khudawadi, Sindhi. Since: 2.42 - + Linear A. Since: 2.42 - + Mahajani. Since: 2.42 - + Manichaean. Since: 2.42 - + Mende Kikakui. Since: 2.42 - + Modi. Since: 2.42 - + Mro. Since: 2.42 - + Nabataean. Since: 2.42 - + Old North Arabian. Since: 2.42 - + Old Permic. Since: 2.42 - + Pahawh Hmong. Since: 2.42 - + Palmyrene. Since: 2.42 - + Pau Cin Hau. Since: 2.42 - + Psalter Pahlavi. Since: 2.42 - + Siddham. Since: 2.42 - + Tirhuta. Since: 2.42 - + Warang Citi. Since: 2.42 - + Ahom. Since: 2.48 - + Anatolian Hieroglyphs. Since: 2.48 - + Hatran. Since: 2.48 - + Multani. Since: 2.48 - + Old Hungarian. Since: 2.48 - + Signwriting. Since: 2.48 - + Adlam. Since: 2.50 - + Bhaiksuki. Since: 2.50 - + Marchen. Since: 2.50 - + Newa. Since: 2.50 - + Osage. Since: 2.50 - + Tangut. Since: 2.50 - + Masaram Gondi. Since: 2.54 - + Nushu. Since: 2.54 - + Soyombo. Since: 2.54 - + Zanabazar Square. Since: 2.54 - + Dogra. Since: 2.58 - + Gunjala Gondi. Since: 2.58 - + Hanifi Rohingya. Since: 2.58 - + Makasar. Since: 2.58 - + Medefaidrin. Since: 2.58 - + Old Sogdian. Since: 2.58 - + Sogdian. Since: 2.58 - + Elym. Since: 2.62 - + Nand. Since: 2.62 - + Rohg. Since: 2.62 - + Wcho. Since: 2.62 - + Chorasmian. Since: 2.66 - + Dives Akuru. Since: 2.66 - + Khitan small script. Since: 2.66 - + Yezidi. Since: 2.66 - + Cypro-Minoan. Since: 2.72 - + Old Uyghur. Since: 2.72 - + Tangsa. Since: 2.72 - + Toto. Since: 2.72 - + Vithkuqi. Since: 2.72 - + Mathematical notation. Since: 2.72 - + Kawi. Since 2.74 - + Nag Mundari. Since 2.74 + + Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter +codes to scripts. For example, the code for Arabic is 'Arab'. +This function accepts four letter codes encoded as a @guint32 in a +big-endian fashion. That is, the code expected for Arabic is +0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). + +See +[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) +for details. + + the Unicode script for @iso15924, or + of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and + %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown. + + + + + a Unicode script + + + + + + Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter +codes to scripts. For example, the code for Arabic is 'Arab'. The +four letter codes are encoded as a @guint32 by this function in a +big-endian fashion. That is, the code returned for Arabic is +0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc). + +See +[Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html) +for details. + + the ISO 15924 code for @script, encoded as an integer, + of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or + ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood. + + + + + a Unicode script + + + + - + These are the possible character classifications from the Unicode specification. See [Unicode Character Database](http://www.unicode.org/reports/tr44/#General_Category_Values). - + General category "Other, Control" (Cc) - + General category "Other, Format" (Cf) - + General category "Other, Not Assigned" (Cn) - + General category "Other, Private Use" (Co) - + General category "Other, Surrogate" (Cs) - + General category "Letter, Lowercase" (Ll) - + General category "Letter, Modifier" (Lm) - + General category "Letter, Other" (Lo) - + General category "Letter, Titlecase" (Lt) - + General category "Letter, Uppercase" (Lu) - + General category "Mark, Spacing" (Mc) - + General category "Mark, Enclosing" (Me) - + General category "Mark, Nonspacing" (Mn) - + General category "Number, Decimal Digit" (Nd) - + General category "Number, Letter" (Nl) - + General category "Number, Other" (No) - + General category "Punctuation, Connector" (Pc) - + General category "Punctuation, Dash" (Pd) - + General category "Punctuation, Close" (Pe) - + General category "Punctuation, Final quote" (Pf) - + General category "Punctuation, Initial quote" (Pi) - + General category "Punctuation, Other" (Po) - + General category "Punctuation, Open" (Ps) - + General category "Symbol, Currency" (Sc) - + General category "Symbol, Modifier" (Sk) - + General category "Symbol, Math" (Sm) - + General category "Symbol, Other" (So) - + General category "Separator, Line" (Zl) - + General category "Separator, Paragraph" (Zp) - + General category "Separator, Space" (Zs) @@ -31308,20 +33371,95 @@ triggers. + + A Unix pipe. The advantage of this type over `int[2]` is that it can +be closed automatically when it goes out of scope, using `g_auto(GUnixPipe)`, +on compilers that support that feature. + + A pair of file descriptors, each negative if closed or not yet opened. + The file descriptor with index %G_UNIX_PIPE_END_READ is readable. + The file descriptor with index %G_UNIX_PIPE_END_WRITE is writable. + + + + + + + Mnemonic constants for the ends of a Unix pipe. + + The readable file descriptor 0 + + + The writable file descriptor 1 + + - The #GUri type and related functions can be used to parse URIs into + The `GUri` type and related functions can be used to parse URIs into their components, and build valid URIs from individual components. -Note that #GUri scope is to help manipulate URIs in various applications, +Since `GUri` only represents absolute URIs, all `GUri`s will have a +URI scheme, so [method@GLib.Uri.get_scheme] will always return a non-`NULL` +answer. Likewise, by definition, all URIs have a path component, so +[method@GLib.Uri.get_path] will always return a non-`NULL` string (which may +be empty). + +If the URI string has an +[‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that +is, if the scheme is followed by `://` rather than just `:`), then the +`GUri` will contain a hostname, and possibly a port and ‘userinfo’. +Additionally, depending on how the `GUri` was constructed/parsed (for example, +using the `G_URI_FLAGS_HAS_PASSWORD` and `G_URI_FLAGS_HAS_AUTH_PARAMS` flags), +the userinfo may be split out into a username, password, and +additional authorization-related parameters. + +Normally, the components of a `GUri` will have all `%`-encoded +characters decoded. However, if you construct/parse a `GUri` with +`G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in +the userinfo, path, and query fields (and in the host field if also +created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if +the URI may contain binary data or non-UTF-8 text, or if decoding +the components might change the interpretation of the URI. + +For example, with the encoded flag: + +```c +g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err); +g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue"); +``` + +While the default `%`-decoding behaviour would give: + +```c +g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err); +g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value"); +``` + +During decoding, if an invalid UTF-8 string is encountered, parsing will fail +with an error indicating the bad string location: + +```c +g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err); +g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY); +``` + +You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you +need to handle that case manually. In particular, if the query string +contains `=` characters that are `%`-encoded, you should let +[func@GLib.Uri.parse_params] do the decoding once of the query. + +`GUri` is immutable once constructed, and can safely be accessed from +multiple threads. Its reference counting is atomic. + +Note that the scope of `GUri` is to help manipulate URIs in various applications, following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, -it doesn't intend to cover web browser needs, and doesn't implement the +it doesn't intend to cover web browser needs, and doesn’t implement the [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to help prevent [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so -#GUri is not suitable for formatting URIs for display to the user for making +`GUri` is not suitable for formatting URIs for display to the user for making security-sensitive decisions. -## Relative and absolute URIs # {#relative-absolute-uris} +## Relative and absolute URIs As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the hierarchical nature of URIs means that they can either be ‘relative @@ -31341,79 +33479,79 @@ For example, a valid relative reference is `./path?query`, Absolute URIs have a scheme specified. Any other components of the URI which are missing are specified as explicitly unset in the URI, rather than being -resolved relative to a base URI using g_uri_parse_relative(). +resolved relative to a base URI using [method@GLib.Uri.parse_relative]. For example, a valid absolute URI is `file:///home/bob` or `https://search.com?query=string`. -A #GUri instance is always an absolute URI. A string may be an absolute URI +A `GUri` instance is always an absolute URI. A string may be an absolute URI or a relative reference; see the documentation for individual functions as to what forms they accept. ## Parsing URIs -The most minimalist APIs for parsing URIs are g_uri_split() and -g_uri_split_with_user(). These split a URI into its component +The most minimalist APIs for parsing URIs are [func@GLib.Uri.split] and +[func@GLib.Uri.split_with_user]. These split a URI into its component parts, and return the parts; the difference between the two is that -g_uri_split() treats the ‘userinfo’ component of the URI as a -single element, while g_uri_split_with_user() can (depending on the -#GUriFlags you pass) treat it as containing a username, password, -and authentication parameters. Alternatively, g_uri_split_network() +[func@GLib.Uri.split] treats the ‘userinfo’ component of the URI as a +single element, while [func@GLib.Uri.split_with_user] can (depending on the +[flags@GLib.UriFlags] you pass) treat it as containing a username, password, +and authentication parameters. Alternatively, [func@GLib.Uri.split_network] can be used when you are only interested in the components that are needed to initiate a network connection to the service (scheme, host, and port). -g_uri_parse() is similar to g_uri_split(), but instead of returning -individual strings, it returns a #GUri structure (and it requires +[func@GLib.Uri.parse] is similar to [func@GLib.Uri.split], but instead of +returning individual strings, it returns a `GUri` structure (and it requires that the URI be an absolute URI). -g_uri_resolve_relative() and g_uri_parse_relative() allow you to -resolve a relative URI relative to a base URI. -g_uri_resolve_relative() takes two strings and returns a string, -and g_uri_parse_relative() takes a #GUri and a string and returns a -#GUri. +[func@GLib.Uri.resolve_relative] and [method@GLib.Uri.parse_relative] allow +you to resolve a relative URI relative to a base URI. +[func@GLib.Uri.resolve_relative] takes two strings and returns a string, +and [method@GLib.Uri.parse_relative] takes a `GUri` and a string and returns a +`GUri`. -All of the parsing functions take a #GUriFlags argument describing +All of the parsing functions take a [flags@GLib.UriFlags] argument describing exactly how to parse the URI; see the documentation for that type for more details on the specific flags that you can pass. If you need to choose different flags based on the type of URI, you can -use g_uri_peek_scheme() on the URI string to check the scheme +use [func@GLib.Uri.peek_scheme] on the URI string to check the scheme first, and use that to decide what flags to parse it with. -For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the -params for a web URI, so compare the result of g_uri_peek_scheme() against -`http` and `https`. +For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the +params for a web URI, so compare the result of [func@GLib.Uri.peek_scheme] +against `http` and `https`. ## Building URIs -g_uri_join() and g_uri_join_with_user() can be used to construct +[func@GLib.Uri.join] and [func@GLib.Uri.join_with_user] can be used to construct valid URI strings from a set of component strings. They are the -inverse of g_uri_split() and g_uri_split_with_user(). +inverse of [func@GLib.Uri.split] and [func@GLib.Uri.split_with_user]. -Similarly, g_uri_build() and g_uri_build_with_user() can be used to -construct a #GUri from a set of component strings. +Similarly, [func@GLib.Uri.build] and [func@GLib.Uri.build_with_user] can be +used to construct a `GUri` from a set of component strings. As with the parsing functions, the building functions take a -#GUriFlags argument. In particular, it is important to keep in mind +[flags@GLib.UriFlags] argument. In particular, it is important to keep in mind whether the URI components you are using are already `%`-encoded. If so, -you must pass the %G_URI_FLAGS_ENCODED flag. +you must pass the `G_URI_FLAGS_ENCODED` flag. ## `file://` URIs Note that Windows and Unix both define special rules for parsing `file://` URIs (involving non-UTF-8 character sets on Unix, and the -interpretation of path separators on Windows). #GUri does not -implement these rules. Use g_filename_from_uri() and -g_filename_to_uri() if you want to properly convert between +interpretation of path separators on Windows). `GUri` does not +implement these rules. Use [func@GLib.filename_from_uri] and +[func@GLib.filename_to_uri] if you want to properly convert between `file://` URIs and local filenames. ## URI Equality Note that there is no `g_uri_equal ()` function, because comparing -URIs usefully requires scheme-specific knowledge that #GUri does -not have. #GUri can help with normalization if you use the various -encoded #GUriFlags as well as %G_URI_FLAGS_SCHEME_NORMALIZE however -it is not comprehensive. +URIs usefully requires scheme-specific knowledge that `GUri` does +not have. `GUri` can help with normalization if you use the various +encoded [flags@GLib.UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE` +however it is not comprehensive. For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same thing according to the `data:` URI specification which GLib does not handle. @@ -31589,7 +33727,7 @@ the flags with which @uri was created. Parses @uri_ref according to @flags and, if it is a -[relative URI][relative-absolute-uris], resolves it relative to @base_uri. +[relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri. If the result is not a valid absolute URI, it will be discarded, and an error returned. @@ -31855,7 +33993,7 @@ returned string should be freed when no longer needed. Parses @uri_string according to @flags, to determine whether it is a valid -[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved +[absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved relative to another URI using g_uri_parse_relative(). If it’s not a valid URI, an error is returned explaining how it’s invalid. @@ -32011,7 +34149,7 @@ discarding any comments. The URIs are not validated. Parses @uri_string according to @flags. If the result is not a -valid [absolute URI][relative-absolute-uris], it will be discarded, and an +valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an error returned. a new #GUri, or NULL on error. @@ -32132,7 +34270,7 @@ all-lowercase and does not need to be freed. Parses @uri_ref according to @flags and, if it is a -[relative URI][relative-absolute-uris], resolves it relative to +[relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned. @@ -32160,7 +34298,7 @@ or NULL on error. Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -32227,7 +34365,7 @@ g_uri_split_with_user() if you want it split up. - Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) + Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces relevant to connecting to a host. See the documentation for g_uri_split() for more details; this is mostly a wrapper around that function with simpler arguments. @@ -32266,7 +34404,7 @@ or does not contain a hostname component. Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -32809,110 +34947,112 @@ using functions deprecated in later releases will not). - #GVariant is a variant datatype; it can contain one or more values + `GVariant` is a variant datatype; it can contain one or more values along with information about the type of the values. -A #GVariant may contain simple types, like an integer, or a boolean value; +A `GVariant` may contain simple types, like an integer, or a boolean value; or complex types, like an array of two strings, or a dictionary of key -value pairs. A #GVariant is also immutable: once it's been created neither +value pairs. A `GVariant` is also immutable: once it’s been created neither its type nor its content can be modified further. -GVariant is useful whenever data needs to be serialized, for example when -sending method parameters in D-Bus, or when saving settings using GSettings. +`GVariant` is useful whenever data needs to be serialized, for example when +sending method parameters in D-Bus, or when saving settings using +[class@Gio.Settings]. -When creating a new #GVariant, you pass the data you want to store in it +When creating a new `GVariant`, you pass the data you want to store in it along with a string representing the type of data you wish to pass to it. -For instance, if you want to create a #GVariant holding an integer value you +For instance, if you want to create a `GVariant` holding an integer value you can use: -|[<!-- language="C" --> - GVariant *v = g_variant_new ("u", 40); -]| +```c +GVariant *v = g_variant_new ("u", 40); +``` -The string "u" in the first argument tells #GVariant that the data passed to -the constructor (40) is going to be an unsigned integer. +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 -[GVariant format strings][gvariant-format-strings-pointers]. +More advanced examples of `GVariant` in use can be found in documentation for +[`GVariant` format strings](gvariant-format-strings.html#pointers). The range of possible values is determined by the type. -The type system used by #GVariant is #GVariantType. +The type system used by `GVariant` is [type@GLib.VariantType]. -#GVariant instances always have a type and a value (which are given -at construction time). The type and value of a #GVariant instance -can never change other than by the #GVariant itself being -destroyed. A #GVariant cannot contain a pointer. +`GVariant` instances always have a type and a value (which are given +at construction time). The type and value of a `GVariant` instance +can never change other than by the `GVariant` itself being +destroyed. A `GVariant` cannot contain a pointer. -#GVariant is reference counted using g_variant_ref() and -g_variant_unref(). #GVariant also has floating reference counts -- -see g_variant_ref_sink(). +`GVariant` is reference counted using [method@GLib.Variant.ref] and +[method@GLib.Variant.unref]. `GVariant` also has floating reference counts — +see [method@GLib.Variant.ref_sink]. -#GVariant is completely threadsafe. A #GVariant instance can be +`GVariant` is completely threadsafe. A `GVariant` instance can be concurrently accessed in any way from any number of threads without problems. -#GVariant is heavily optimised for dealing with data in serialized +`GVariant` is heavily optimised for dealing with data in serialized form. It works particularly well with data located in memory-mapped files. It can perform nearly all deserialization operations in a small constant time, usually touching only a single memory page. -Serialized #GVariant data can also be sent over the network. +Serialized `GVariant` data can also be sent over the network. -#GVariant is largely compatible with D-Bus. Almost all types of -#GVariant instances can be sent over D-Bus. See #GVariantType for -exceptions. (However, #GVariant's serialization format is not the same -as the serialization format of a D-Bus message body: use #GDBusMessage, -in the gio library, for those.) +`GVariant` is largely compatible with D-Bus. Almost all types of +`GVariant` instances can be sent over D-Bus. See [type@GLib.VariantType] for +exceptions. (However, `GVariant`’s serialization format is not the same +as the serialization format of a D-Bus message body: use +[class@Gio.DBusMessage], in the GIO library, for those.) -For space-efficiency, the #GVariant serialization format does not -automatically include the variant's length, type or endianness, +For space-efficiency, the `GVariant` serialization format does not +automatically include the variant’s length, type or endianness, which must either be implied from context (such as knowledge that a particular file format always contains a little-endian -%G_VARIANT_TYPE_VARIANT which occupies the whole length of the file) +`G_VARIANT_TYPE_VARIANT` which occupies the whole length of the file) or supplied out-of-band (for instance, a length, type and/or endianness indicator could be placed at the beginning of a file, network message or network stream). -A #GVariant's size is limited mainly by any lower level operating -system constraints, such as the number of bits in #gsize. For +A `GVariant`’s size is limited mainly by any lower level operating +system constraints, such as the number of bits in `gsize`. For example, it is reasonable to have a 2GB file mapped into memory -with #GMappedFile, and call g_variant_new_from_data() on it. +with [struct@GLib.MappedFile], and call [ctor@GLib.Variant.new_from_data] on +it. -For convenience to C programmers, #GVariant features powerful +For convenience to C programmers, `GVariant` features powerful varargs-based value construction and destruction. This feature is designed to be embedded in other libraries. -There is a Python-inspired text language for describing #GVariant -values. #GVariant includes a printer for this language and a parser +There is a Python-inspired text language for describing `GVariant` +values. `GVariant` includes a printer for this language and a parser with type inferencing. ## Memory Use -#GVariant tries to be quite efficient with respect to memory use. +`GVariant` tries to be quite efficient with respect to memory use. This section gives a rough idea of how much memory is used by the current implementation. The information here is subject to change in the future. -The memory allocated by #GVariant can be grouped into 4 broad +The memory allocated by `GVariant` can be grouped into 4 broad purposes: memory for serialized data, memory for the type information cache, buffer management memory and memory for the -#GVariant structure itself. +`GVariant` structure itself. ## Serialized Data Memory -This is the memory that is used for storing GVariant data in +This is the memory that is used for storing `GVariant` data in serialized form. This is what would be sent over the network or what would end up on disk, not counting any indicator of the endianness, or of the length or type of the top-level variant. The amount of memory required to store a boolean is 1 byte. 16, 32 and 64 bit integers and double precision floating point numbers -use their "natural" size. Strings (including object path and +use their ‘natural’ size. Strings (including object path and signature strings) are stored with a nul terminator, and as such use the length of the string plus 1 byte. -Maybe types use no space at all to represent the null value and +‘Maybe’ types use no space at all to represent the null value and use the same amount of space (sometimes plus one byte) as the equivalent non-maybe-typed value to represent the non-null case. @@ -32938,39 +35078,39 @@ As an example, consider a dictionary mapping strings to variants. In the case that the dictionary is empty, 0 bytes are required for the serialization. -If we add an item "width" that maps to the int32 value of 500 then -we will use 4 byte to store the int32 (so 6 for the variant +If we add an item ‘width’ that maps to the int32 value of 500 then +we will use 4 bytes to store the int32 (so 6 for the variant containing it) and 6 bytes for the string. The variant must be -aligned to 8 after the 6 bytes of the string, so that's 2 extra +aligned to 8 after the 6 bytes of the string, so that’s 2 extra bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used for the dictionary entry. An additional 1 byte is added to the array as a framing offset making a total of 15 bytes. -If we add another entry, "title" that maps to a nullable string +If we add another entry, ‘title’ that maps to a nullable string that happens to have a value of null, then we use 0 bytes for the null value (and 3 bytes for the variant to contain it along with its type string) plus 6 bytes for the string. Again, we need 2 padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes. We now require extra padding between the two items in the array. -After the 14 bytes of the first item, that's 2 bytes required. +After the 14 bytes of the first item, that’s 2 bytes required. We now require 2 framing offsets for an extra two bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item dictionary. ## Type Information Cache -For each GVariant type that currently exists in the program a type +For each `GVariant` type that currently exists in the program a type information structure is kept in the type information cache. The type information structure is required for rapid deserialization. -Continuing with the above example, if a #GVariant exists with the -type "a{sv}" then a type information struct will exist for -"a{sv}", "{sv}", "s", and "v". Multiple uses of the same type +Continuing with the above example, if a `GVariant` exists with the +type `a{sv}` then a type information struct will exist for +`a{sv}`, `{sv}`, `s`, and `v`. Multiple uses of the same type will share the same type information. Additionally, all single-digit types are stored in read-only static memory and do not contribute to the writable memory footprint of a program using -#GVariant. +`GVariant`. Aside from the type information structures stored in read-only memory, there are two forms of type information. One is used for @@ -32978,23 +35118,23 @@ container types where there is a single element type: arrays and maybe types. The other is used for container types where there are multiple element types: tuples and dictionary entries. -Array type info structures are 6 * sizeof (void *), plus the +Array type info structures are `6 * sizeof (void *)`, plus the memory required to store the type string itself. This means that -on 32-bit systems, the cache entry for "a{sv}" would require 30 -bytes of memory (plus malloc overhead). +on 32-bit systems, the cache entry for `a{sv}` would require 30 +bytes of memory (plus allocation overhead). -Tuple type info structures are 6 * sizeof (void *), plus 4 * -sizeof (void *) for each item in the tuple, plus the memory +Tuple type info structures are `6 * sizeof (void *)`, plus `4 * +sizeof (void *)` for each item in the tuple, plus the memory required to store the type string itself. A 2-item tuple, for example, would have a type information structure that consumed -writable memory in the size of 14 * sizeof (void *) (plus type +writable memory in the size of `14 * sizeof (void *)` (plus type string) This means that on 32-bit systems, the cache entry for -"{sv}" would require 61 bytes of memory (plus malloc overhead). +`{sv}` would require 61 bytes of memory (plus allocation overhead). -This means that in total, for our "a{sv}" example, 91 bytes of +This means that in total, for our `a{sv}` example, 91 bytes of type information would be allocated. -The type information cache, additionally, uses a #GHashTable to +The type information cache, additionally, uses a [struct@GLib.HashTable] to 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. @@ -33006,34 +35146,34 @@ structure is required for many different values of the same type. ## Buffer Management Memory -#GVariant uses an internal buffer management structure to deal +`GVariant` uses an internal buffer management structure to deal with the various different possible sources of serialized data that it uses. The buffer is responsible for ensuring that the correct call is made when the data is no longer in use by -#GVariant. This may involve a g_free() or a g_slice_free() or -even g_mapped_file_unref(). +`GVariant`. This may involve a [func@GLib.free] or +even [method@GLib.MappedFile.unref]. One buffer management structure is used for each chunk of serialized data. The size of the buffer management structure -is 4 * (void *). On 32-bit systems, that's 16 bytes. +is `4 * (void *)`. On 32-bit systems, that’s 16 bytes. ## GVariant structure -The size of a #GVariant structure is 6 * (void *). On 32-bit -systems, that's 24 bytes. +The size of a `GVariant` structure is `6 * (void *)`. On 32-bit +systems, that’s 24 bytes. -#GVariant structures only exist if they are explicitly created -with API calls. For example, if a #GVariant is constructed out of +`GVariant` structures only exist if they are explicitly created +with API calls. For example, if a `GVariant` is constructed out of serialized data for the example given above (with the dictionary) then although there are 9 individual values that comprise the entire dictionary (two keys, two values, two variants containing the values, two dictionary entries, plus the dictionary itself), -only 1 #GVariant instance exists -- the one referring to the +only 1 `GVariant` instance exists — the one referring to the dictionary. If calls are made to start accessing the other values then -#GVariant instances will exist for those values only for as long -as they are in use (ie: until you call g_variant_unref()). The +`GVariant` instances will exist for those values only for as long +as they are in use (ie: until you call [method@GLib.Variant.unref]). The type information is shared. The serialized data and the buffer management structure for that serialized data is shared by the child. @@ -33044,9 +35184,9 @@ To put the entire example together, for our dictionary mapping strings to variants (with two entries, as given above), we are using 91 bytes of memory for type information, 29 bytes of memory for the serialized data, 16 bytes for buffer management and 24 -bytes for the #GVariant instance, or a total of 160 bytes, plus -malloc overhead. If we were to use g_variant_get_child_value() to -access the two dictionary entries, we would use an additional 48 +bytes for the `GVariant` instance, or a total of 160 bytes, plus +allocation overhead. If we were to use [method@GLib.Variant.get_child_value] +to access the two dictionary entries, we would use an additional 48 bytes. If we were to have other dictionaries of the same type, we would use more memory for the serialized data and buffer management for those dictionaries, but the type information would @@ -34091,7 +36231,7 @@ extended in the future. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). @@ -34212,7 +36352,7 @@ g_variant_get(). @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). @@ -34728,7 +36868,7 @@ varargs call by the user. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). @@ -34894,7 +37034,7 @@ value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). This function is currently implemented with a linear scan. If you plan to do many lookups then #GVariantDict may be more efficient. @@ -35207,7 +37347,7 @@ strings in sequence. A single #GVariant is parsed from the content of @text. -The format is described [here][gvariant-text]. +The format is described [here](gvariant-text-format.html). The memory at @limit will never be accessed and the parser behaves as if the character at @limit is the nul terminator. This has the @@ -35227,13 +37367,14 @@ with empty arrays). In the event that the parsing is successful, the resulting #GVariant is returned. It is never floating, and must be freed with -g_variant_unref(). +[method@GLib.Variant.unref]. In case of any error, %NULL will be returned. If @error is non-%NULL then it will be set to reflect the error that occurred. -Officially, the language understood by the parser is "any string -produced by g_variant_print()". +Officially, the language understood by the parser is “any string +produced by [method@GLib.Variant.print]”. This explicitly includes +`g_variant_print()`’s annotated types like `int64 -1000`. There may be implementation specific restrictions on deeply nested values, which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is @@ -36032,7 +38173,7 @@ value and returns %TRUE. @format_string determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the -section on [GVariant format strings][gvariant-format-strings-pointers]. +section on [`GVariant` format strings](gvariant-format-strings.html#pointers). %TRUE if a value was unpacked @@ -36267,7 +38408,7 @@ thereby avoiding the need to free anything as well). the values and also determines if the values are copied or borrowed. See the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). %TRUE if a value was unpacked, or %FALSE if there was no value @@ -36346,7 +38487,7 @@ when dealing with loops, see g_variant_iter_loop(). the values and also determines if the values are copied or borrowed. See the section on -[GVariant format strings][gvariant-format-strings-pointers]. +[`GVariant` format strings](gvariant-format-strings.html#pointers). %TRUE if a value was unpacked, or %FALSE if there as no value @@ -36466,154 +38607,157 @@ Here is an example for iterating with g_variant_iter_next_value(): variant was too deeply nested; #GVariant is only guaranteed to handle nesting up to 64 levels (Since: 2.64) - - This section introduces the GVariant type system. It is based, in + + A type in the [type@GLib.Variant] type system. + +This section introduces the [type@GLib.Variant] type system. It is based, in large part, on the D-Bus type system, with two major changes and some minor lifting of restrictions. The [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html), therefore, provides a significant amount of -information that is useful when working with GVariant. +information that is useful when working with [type@GLib.Variant]. The first major change with respect to the D-Bus type system is the -introduction of maybe (or "nullable") types. Any type in GVariant can be -converted to a maybe type, in which case, "nothing" (or "null") becomes a -valid value. Maybe types have been added by introducing the -character "m" to type strings. +introduction of maybe (or ‘nullable’) types. Any type in [type@GLib.Variant] +can be converted to a maybe type, in which case, `nothing` (or `null`) +becomes a valid value. Maybe types have been added by introducing the +character `m` to type strings. -The second major change is that the GVariant type system supports the -concept of "indefinite types" -- types that are less specific than +The second major change is that the [type@GLib.Variant] type system supports +the concept of ‘indefinite types’ — types that are less specific than the normal types found in D-Bus. For example, it is possible to speak -of "an array of any type" in GVariant, where the D-Bus type system -would require you to speak of "an array of integers" or "an array of -strings". Indefinite types have been added by introducing the -characters "*", "?" and "r" to type strings. +of ‘an array of any type’ in [type@GLib.Variant], where the D-Bus type system +would require you to speak of ‘an array of integers’ or ‘an array of +strings’. Indefinite types have been added by introducing the +characters `*`, `?` and `r` to type strings. Finally, all arbitrary restrictions relating to the complexity of types are lifted along with the restriction that dictionary entries may only appear nested inside of arrays. -Just as in D-Bus, GVariant types are described with strings ("type -strings"). Subject to the differences mentioned above, these strings +Just as in D-Bus, [type@GLib.Variant] types are described with strings (‘type +strings’). Subject to the differences mentioned above, these strings are of the same form as those found in D-Bus. Note, however: D-Bus always works in terms of messages and therefore individual type -strings appear nowhere in its interface. Instead, "signatures" +strings appear nowhere in its interface. Instead, ‘signatures’ are a concatenation of the strings of the type of each argument in a -message. GVariant deals with single values directly so GVariant type -strings always describe the type of exactly one value. This means -that a D-Bus signature string is generally not a valid GVariant type -string -- except in the case that it is the signature of a message -containing exactly one argument. +message. [type@GLib.Variant] deals with single values directly so +[type@GLib.Variant] type strings always describe the type of exactly one +value. This means that a D-Bus signature string is generally not a valid +[type@GLib.Variant] type string — except in the case that it is the signature +of a message containing exactly one argument. An indefinite type is similar in spirit to what may be called an abstract type in other type systems. No value can exist that has an indefinite type as its type, but values can exist that have types that are subtypes of indefinite types. That is to say, -g_variant_get_type() will never return an indefinite type, but -calling g_variant_is_of_type() with an indefinite type may return -%TRUE. For example, you cannot have a value that represents "an -array of no particular type", but you can have an "array of integers" -which certainly matches the type of "an array of no particular type", -since "array of integers" is a subtype of "array of no particular -type". +[method@GLib.Variant.get_type] will never return an indefinite type, but +calling [method@GLib.Variant.is_of_type] with an indefinite type may return +true. For example, you cannot have a value that represents ‘an +array of no particular type’, but you can have an ‘array of integers’ +which certainly matches the type of ‘an array of no particular type’, +since ‘array of integers’ is a subtype of ‘array of no particular +type’. This is similar to how instances of abstract classes may not directly exist in other type systems, but instances of their non-abstract subtypes may. For example, in GTK, no object that has -the type of #GtkBin can exist (since #GtkBin is an abstract class), -but a #GtkWindow can certainly be instantiated, and you would say -that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of -#GtkBin). +the type of [class@Gtk.Widget] can exist (since [class@Gtk.Widget] is an +abstract class), but a [class@Gtk.Window] can certainly be instantiated, and +you would say that the [class@Gtk.Window] is a [class@Gtk.Widget] (since +[class@Gtk.Window] is a subclass of [class@Gtk.Widget]). + +Two types may not be compared by value; use [method@GLib.VariantType.equal] +or [method@GLib.VariantType.is_subtype_of] May be copied using +[method@GLib.VariantType.copy] and freed using [method@GLib.VariantType.free]. ## GVariant Type Strings -A GVariant type string can be any of the following: +A [type@GLib.Variant] type string can be any of the following: - any basic type string (listed below) - -- "v", "r" or "*" - -- one of the characters 'a' or 'm', followed by another type string - -- the character '(', followed by a concatenation of zero or more other - type strings, followed by the character ')' - -- the character '{', followed by a basic type string (see below), - followed by another type string, followed by the character '}' +- `v`, `r` or `*` +- one of the characters `a` or `m`, followed by another type string +- the character `(`, followed by a concatenation of zero or more other + type strings, followed by the character `)` +- the character `{`, followed by a basic type string (see below), + followed by another type string, followed by the character `}` A basic type string describes a basic type (as per -g_variant_type_is_basic()) and is always a single character in length. -The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t", -"h", "d", "s", "o", "g" and "?". +[method@GLib.VariantType.is_basic]) and is always a single character in +length. The valid basic type strings are `b`, `y`, `n`, `q`, `i`, `u`, `x`, +`t`, `h`, `d`, `s`, `o`, `g` and `?`. -The above definition is recursive to arbitrary depth. "aaaaai" and -"(ui(nq((y)))s)" are both valid type strings, as is -"a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant -imposes a limit on recursion depth of 65 nested containers. This is the -limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to -be nested in a top-level tuple. +The above definition is recursive to arbitrary depth. `aaaaai` and +`(ui(nq((y)))s)` are both valid type strings, as is +`a(aa(ui)(qna{ya(yd)}))`. In order to not hit memory limits, +[type@GLib.Variant] imposes a limit on recursion depth of 65 nested +containers. This is the limit in the D-Bus specification (64) plus one to +allow a [class@Gio.DBusMessage] to be nested in a top-level tuple. The meaning of each of the characters is as follows: -- `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. -- `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. -- `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. -- `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. -- `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. -- `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. -- `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. -- `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. -- `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value + +- `b`: the type string of `G_VARIANT_TYPE_BOOLEAN`; a boolean value. +- `y`: the type string of `G_VARIANT_TYPE_BYTE`; a byte. +- `n`: the type string of `G_VARIANT_TYPE_INT16`; a signed 16 bit integer. +- `q`: the type string of `G_VARIANT_TYPE_UINT16`; an unsigned 16 bit integer. +- `i`: the type string of `G_VARIANT_TYPE_INT32`; a signed 32 bit integer. +- `u`: the type string of `G_VARIANT_TYPE_UINT32`; an unsigned 32 bit integer. +- `x`: the type string of `G_VARIANT_TYPE_INT64`; a signed 64 bit integer. +- `t`: the type string of `G_VARIANT_TYPE_UINT64`; an unsigned 64 bit integer. +- `h`: the type string of `G_VARIANT_TYPE_HANDLE`; a signed 32 bit value that, by convention, is used as an index into an array of file descriptors that are sent alongside a D-Bus message. -- `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision +- `d`: the type string of `G_VARIANT_TYPE_DOUBLE`; a double precision floating point value. -- `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 +- `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_SIGNATURE; 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 +- `?`: the type string of `G_VARIANT_TYPE_BASIC`; an indefinite type that is a supertype of any of the basic types. -- `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that +- `v`: the type string of `G_VARIANT_TYPE_VARIANT`; a container type that contain any other type of value. - `a`: used as a prefix on another type string to mean an array of that - type; the type string "ai", for example, is the type of an array of + type; the type string `ai`, for example, is the type of an array of signed 32-bit integers. -- `m`: used as a prefix on another type string to mean a "maybe", or - "nullable", version of that type; the type string "ms", for example, +- `m`: used as a prefix on another type string to mean a ‘maybe’, or + ‘nullable’, version of that type; the type string `ms`, for example, is the type of a value that maybe contains a string, or maybe contains nothing. - `()`: used to enclose zero or more other concatenated type strings to - create a tuple type; the type string "(is)", for example, is the type of + create a tuple type; the type string `(is)`, for example, is the type of a pair of an integer and a string. -- `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is +- `r`: the type string of `G_VARIANT_TYPE_TUPLE`; an indefinite type that is a supertype of any tuple type, regardless of the number of items. - `{}`: used to enclose a basic type string concatenated with another type string to create a dictionary entry type, which usually appears inside of - an array to form a dictionary; the type string "a{sd}", for example, is + an array to form a dictionary; the type string `a{sd}`, for example, is the type of a dictionary that maps strings to double precision floating point values. The first type (the basic type) is the key type and the second type is the value type. The reason that the first type is restricted to being a basic type is so that it can easily be hashed. -- `*`: the type string of %G_VARIANT_TYPE_ANY; the indefinite type that is +- `*`: the type string of `G_VARIANT_TYPE_ANY`; the indefinite type that is a supertype of all types. Note that, as with all type strings, this character represents exactly one type. It cannot be used inside of tuples - to mean "any number of items". + to mean ‘any number of items’. Any type string of a container that contains an indefinite type is, -itself, an indefinite type. For example, the type string "a*" -(corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type -that is a supertype of every array type. "(*s)" is a supertype +itself, an indefinite type. For example, the type string `a*` +(corresponding to `G_VARIANT_TYPE_ARRAY`) is an indefinite type +that is a supertype of every array type. `(*s)` is a supertype of all tuples that contain exactly two items where the second item is a string. -"a{?*}" is an indefinite type that is a supertype of all arrays +`a{?*}` is an indefinite type that is a supertype of all arrays containing dictionary entries where the key is any basic type and the value is any type at all. This is, by definition, a dictionary, -so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note +so this type string corresponds to `G_VARIANT_TYPE_DICTIONARY`. Note that, due to the restriction that the key of a dictionary entry must -be a basic type, "{**}" is not a valid type string. +be a basic type, `{**}` is not a valid type string. Creates a new #GVariantType corresponding to the type string given by @type_string. It is appropriate to call g_variant_type_free() on @@ -37172,7 +39316,7 @@ Since 2.24 - + @@ -37247,40 +39391,33 @@ function passed to g_atexit(). - On Windows, this macro defines a DllMain() function that stores -the actual DLL name that the code being compiled will be included in. - -On non-Windows platforms, expands to nothing. - empty or "static" - the name of the (pointer to the) char array where - the DLL name will be stored. If this is used, you must also - include `windows.h`. If you need a more complex DLL entry - point function, you cannot use this - - On Windows, this macro defines an expression which evaluates to -%TRUE if the code is running on a version of Windows where the wide -character versions of the Win32 API functions, and the wide character -versions of the C library functions work. (They are always present in -the DLLs, but don't work on Windows 9x and Me.) - -On non-Windows platforms, it is not defined. - - - On Windows, this macro defines an expression which evaluates to -%TRUE if the code is running on an NT-based Windows operating system. - -On non-Windows platforms, it is not defined. - + + + + Type of Windows edition to check for at run-time. + + The running system can be a workstation or a server edition of + Windows. The type of the running system is therefore not checked. + + + The running system is a workstation edition of Windows, + such as Windows 7 Professional. + + + The running system is a server edition of Windows, such as + Windows Server 2008 R2. + + A wrapper for the POSIX abort() function. @@ -37462,124 +39599,6 @@ Note that the @size argument will be evaluated multiple times. - - An "atomically reference counted box", or "ArcBox", is an opaque wrapper -data type that is guaranteed to be as big as the size of a given data type, -and which augments the given data type with thread safe reference counting -semantics for its memory management. - -ArcBox is useful if you have a plain old data type, like a structure -typically placed on the stack, and you wish to provide additional API -to use it on the heap; or if you want to implement a new type to be -passed around by reference without necessarily implementing copy/free -semantics or your own reference counting. - -The typical use is: - -|[<!-- language="C" --> -typedef struct { - char *name; - char *address; - char *city; - char *state; - int age; -} Person; - -Person * -person_new (void) -{ - return g_atomic_rc_box_new0 (Person); -} -]| - -Every time you wish to acquire a reference on the memory, you should -call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference -you should call g_atomic_rc_box_release(): - -|[<!-- language="C" --> -// Add a Person to the Database; the Database acquires ownership -// of the Person instance -void -add_person_to_database (Database *db, Person *p) -{ - db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p)); -} - -// Removes a Person from the Database; the reference acquired by -// add_person_to_database() is released here -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_atomic_rc_box_release (p); -} -]| - -If you have additional memory allocated inside the structure, you can -use g_atomic_rc_box_release_full(), which takes a function pointer, which -will be called if the reference released was the last: - -|[<!-- language="C" --> -void -person_clear (Person *p) -{ - g_free (p->name); - g_free (p->address); - g_free (p->city); - g_free (p->state); -} - -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear); -} -]| - -If you wish to transfer the ownership of a reference counted data -type without increasing the reference count, you can use g_steal_pointer(): - -|[<!-- language="C" --> - Person *p = g_atomic_rc_box_new (Person); - - fill_person_details (p); - - add_person_to_database (db, g_steal_pointer (&p)); -]| - -## Thread safety - -The reference counting operations on data allocated using g_atomic_rc_box_alloc(), -g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus -can be safely be performed by different threads. It is important to note that -only the reference acquisition and release are atomic; changes to the content -of the data are your responsibility. - -## Automatic pointer clean up - -If you want to add g_autoptr() support to your plain old data type through -reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and -g_atomic_rc_box_release(): - -|[<!-- language="C" --> -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release) -]| - -If you need to clear the contents of the data, you will need to use an -ancillary function that calls g_rc_box_release_full(): - -|[<!-- language="C" --> -static void -my_data_struct_release (MyDataStruct *data) -{ - // my_data_struct_clear() is defined elsewhere - g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); -} - -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) -]| - Adds the value on to the end of the array. The array will grow in size automatically if necessary. @@ -37762,123 +39781,6 @@ such as "27". You must use variables. - - Arrays are similar to standard C arrays, except that they grow -automatically as elements are added. - -Array elements can be of any size (though all elements of one array -are the same size), and the array can be automatically cleared to -'0's and zero-terminated. - -To create a new array use g_array_new(). - -To add elements to an array with a cost of O(n) at worst, use -g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), -g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals(). - -To access an element of an array in O(1) (to read it or to write it), -use g_array_index(). - -To set the size of an array, use g_array_set_size(). - -To free an array, use g_array_unref() or g_array_free(). - -All the sort functions are internally calling a quick-sort (or similar) -function with an average cost of O(n log(n)) and a worst case -cost of O(n^2). - -Here is an example that stores integers in a #GArray: -|[<!-- language="C" --> - GArray *garray; - gint i; - // We create a new array to store gint values. - // We don't want it zero-terminated or cleared to 0's. - garray = g_array_new (FALSE, FALSE, sizeof (gint)); - for (i = 0; i < 10000; i++) - g_array_append_val (garray, i); - for (i = 0; i < 10000; i++) - if (g_array_index (garray, gint, i) != i) - g_print ("ERROR: got %d instead of %d\n", - g_array_index (garray, gint, i), i); - g_array_free (garray, TRUE); -]| - - - #GByteArray is a mutable array of bytes based on #GArray, to provide arrays -of bytes which grow automatically as elements are added. - -To create a new #GByteArray use g_byte_array_new(). To add elements to a -#GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). - -To set the size of a #GByteArray, use g_byte_array_set_size(). - -To free a #GByteArray, use g_byte_array_free(). - -An example for using a #GByteArray: -|[<!-- language="C" --> - GByteArray *gbarray; - gint i; - - gbarray = g_byte_array_new (); - for (i = 0; i < 10000; i++) - g_byte_array_append (gbarray, (guint8*) "abcd", 4); - - for (i = 0; i < 10000; i++) - { - g_assert (gbarray->data[4*i] == 'a'); - g_assert (gbarray->data[4*i+1] == 'b'); - g_assert (gbarray->data[4*i+2] == 'c'); - g_assert (gbarray->data[4*i+3] == 'd'); - } - - g_byte_array_free (gbarray, TRUE); -]| - -See #GBytes if you are interested in an immutable object representing a -sequence of bytes. - - - Pointer Arrays are similar to Arrays but are used only for storing -pointers. - -If you remove elements from the array, elements at the end of the -array are moved into the space previously occupied by the removed -element. This means that you should not rely on the index of particular -elements remaining the same. You should also be careful when deleting -elements while iterating over the array. - -To create a pointer array, use g_ptr_array_new(). - -To add elements to a pointer array, use g_ptr_array_add(). - -To remove elements from a pointer array, use g_ptr_array_remove(), -g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). - -To access an element of a pointer array, use g_ptr_array_index(). - -To set the size of a pointer array, use g_ptr_array_set_size(). - -To free a pointer array, use g_ptr_array_free(). - -An example using a #GPtrArray: -|[<!-- language="C" --> - GPtrArray *array; - gchar *string1 = "one"; - gchar *string2 = "two"; - gchar *string3 = "three"; - - array = g_ptr_array_new (); - g_ptr_array_add (array, (gpointer) string1); - g_ptr_array_add (array, (gpointer) string2); - g_ptr_array_add (array, (gpointer) string3); - - if (g_ptr_array_index (array, 0) != (gpointer) string1) - g_print ("ERROR: got %p instead of %p\n", - g_ptr_array_index (array, 0), string1); - - g_ptr_array_free (array, TRUE); -]| - Determines the numeric value of a character as a decimal digit. Differs from g_unichar_digit_value() because it takes a char, so @@ -39091,49 +40993,6 @@ g_assert_not_reached() macros. - - Often you need to communicate between different threads. In general -it's safer not to do this by shared memory, but by explicit message -passing. These messages only make sense asynchronously for -multi-threaded applications though, as a synchronous operation could -as well be done in the same thread. - -Asynchronous queues are an exception from most other GLib data -structures, as they can be used simultaneously from multiple threads -without explicit locking and they bring their own builtin reference -counting. This is because the nature of an asynchronous queue is that -it will always be used by at least 2 concurrent threads. - -For using an asynchronous queue you first have to create one with -g_async_queue_new(). #GAsyncQueue structs are reference counted, -use g_async_queue_ref() and g_async_queue_unref() to manage your -references. - -A thread which wants to send a message to that queue simply calls -g_async_queue_push() to push the message to the queue. - -A thread which is expecting messages from an asynchronous queue -simply calls g_async_queue_pop() for that queue. If no message is -available in the queue at that point, the thread is now put to sleep -until a message arrives. The message will be removed from the queue -and returned. The functions g_async_queue_try_pop() and -g_async_queue_timeout_pop() can be used to only check for the presence -of messages or to only wait a certain time for messages respectively. - -For almost every function there exist two variants, one that locks -the queue and one that doesn't. That way you can hold the queue lock -(acquire it with g_async_queue_lock() and release it with -g_async_queue_unlock()) over multiple queue accessing instructions. -This can be necessary to ensure the integrity of the queue, but should -only be used when really necessary, as it can make your life harder -if used unwisely. Normally you should only use the locking function -variants (those without the _unlocked suffix). - -In many cases, it may be more convenient to use #GThreadPool when -you need to distribute work to a set of worker threads instead of -using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue -internally. - Specifies a function to be called at normal program termination. @@ -39475,43 +41334,6 @@ the pointer passed to it should not be `volatile`. - - The following is a collection of compiler macros to provide atomic -access to integer and pointer-sized values. - -The macros that have 'int' in the name will operate on pointers to -#gint and #guint. The macros with 'pointer' in the name will operate -on pointers to any pointer-sized value, including #gsize. There is -no support for 64bit operations on platforms with 32bit pointers -because it is not generally possible to perform these operations -atomically. - -The get, set and exchange operations for integers and pointers -nominally operate on #gint and #gpointer, respectively. Of the -arithmetic operations, the 'add' operation operates on (and returns) -signed integer values (#gint and #gssize) and the 'and', 'or', and -'xor' operations operate on (and return) unsigned integer values -(#guint and #gsize). - -All of the operations act as a full compiler and (where appropriate) -hardware memory barrier. Acquire and release or producer and -consumer barrier semantics are not available through this API. - -It is very important that all accesses to a particular integer or -pointer be performed using only this API and that different sizes of -operation are not mixed or used on overlapping memory regions. Never -read or assign directly from or to a value -- always use this API. - -For simple reference counting purposes you should use -g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that -fall outside of simple reference counting patterns are prone to -subtle bugs and occasionally undefined behaviour. It is also worth -noting that since all of these operations require global -synchronisation of the entire machine, they can be quite slow. In -the case of performing multiple atomic operations it can often be -faster to simply acquire a mutex lock around the critical area, -perform the operations normally and then release the lock. - Atomically adds @val to the value of @atomic. @@ -39521,10 +41343,14 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gssize to #gintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. the value of @atomic before the add, signed - + @@ -39547,10 +41373,14 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gsize to #guintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. the value of @atomic before the operation, unsigned - + @@ -39684,10 +41514,14 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gsize to #guintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. the value of @atomic before the operation, unsigned - + @@ -39732,10 +41566,14 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. While @atomic has a `volatile` qualifier, this is a historical artifact and -the pointer passed to it should not be `volatile`. +the pointer passed to it should not be `volatile`. + +In GLib 2.80, the return type was changed from #gsize to #guintptr to add +support for platforms with 128-bit pointers. This should not affect existing +code. the value of @atomic before the operation, unsigned - + @@ -39958,24 +41796,6 @@ g_atomic_ref_count_init() to be used again. - - Base64 is an encoding that allows a sequence of arbitrary bytes to be -encoded as a sequence of printable ASCII characters. For the definition -of Base64, see -[RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) -or -[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). -Base64 is most commonly used as a MIME transfer encoding -for email. - -GLib supports incremental encoding using g_base64_encode_step() and -g_base64_encode_close(). Incremental decoding can be done with -g_base64_decode_step(). To encode or decode data in one go, use -g_base64_encode() or g_base64_decode(). To avoid memory allocation when -decoding, you can use g_base64_decode_inplace(). - -Support for Base64 encoding has been added in GLib 2.12. - Decode a sequence of Base-64 encoded text into binary data. Note that the returned binary data is not necessarily zero-terminated, @@ -40330,6 +42150,11 @@ artifact and the argument passed to it should not be `volatile`. + + + + + @@ -40489,6 +42314,32 @@ This function is mainly meant for language bindings. + + Adds the given bytes to the end of the #GByteArray. +The array will grow in size automatically if necessary. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the byte data to be added + + + + the number of bytes to add + + + + Frees the memory allocated by the #GByteArray. If @free_segment is %TRUE it frees the actual byte data. If the reference count of @@ -40572,6 +42423,211 @@ stores the length of its data in #guint, which may be shorter than + + Adds the given data to the start of the #GByteArray. +The array will grow in size automatically if necessary. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the byte data to be added + + + + the number of bytes to add + + + + + + Atomically increments the reference count of @array by one. +This function is thread-safe and may be called from any thread. + + The passed in #GByteArray + + + + + + + A #GByteArray + + + + + + + + Removes the byte at the given index from a #GByteArray. +The following bytes are moved down one place. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the index of the byte to remove + + + + + + Removes the byte at the given index from a #GByteArray. The last +element in the array is used to fill in the space, so this function +does not preserve the order of the #GByteArray. But it is faster +than g_byte_array_remove_index(). + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the index of the byte to remove + + + + + + Removes the given number of bytes starting at the given index from a +#GByteArray. The following elements are moved to close the gap. + + the #GByteArray + + + + + + + a @GByteArray + + + + + + the index of the first byte to remove + + + + the number of bytes to remove + + + + + + Sets the size of the #GByteArray, expanding it if necessary. + + the #GByteArray + + + + + + + a #GByteArray + + + + + + the new size of the #GByteArray + + + + + + Creates a new #GByteArray with @reserved_size bytes preallocated. +This avoids frequent reallocation, if you are going to add many +bytes to the array. Note however that the size of the array is still +0. + + the new #GByteArray + + + + + + + number of bytes preallocated + + + + + + Sorts a byte array, using @compare_func which should be a +qsort()-style comparison function (returns less than zero for first +arg is less than second arg, zero for equal, greater than zero if +first arg is greater than second arg). + +If two array elements compare equal, their order in the sorted array +is undefined. If you want equal elements to keep their order (i.e. +you want a stable sort) you can write a comparison function that, +if two elements would otherwise compare equal, compares them by +their addresses. + + + + + + a #GByteArray + + + + + + comparison function + + + + + + Like g_byte_array_sort(), but the comparison function takes an extra +user data argument. + + + + + + a #GByteArray + + + + + + comparison function + + + + data to pass to @compare_func + + + + Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned @@ -40612,36 +42668,6 @@ thread. - - These macros provide a portable way to determine the host byte order -and to convert values between different byte orders. - -The byte order is the order in which bytes are stored to create larger -data types such as the #gint and #glong values. -The host byte order is the byte order used on the current machine. - -Some processors store the most significant bytes (i.e. the bytes that -hold the largest part of the value) first. These are known as big-endian -processors. Other processors (notably the x86 family) store the most -significant byte last. These are known as little-endian processors. - -Finally, to complicate matters, some other processors store the bytes in -a rather curious order known as PDP-endian. For a 4-byte word, the 3rd -most significant byte is stored first, then the 4th, then the 1st and -finally the 2nd. - -Obviously there is a problem when these different processors communicate -with each other, for example over networks or by using binary file formats. -This is where these macros come in. They are typically used to convert -values into a byte order which has been agreed on for use when -communicating between different processors. The Internet uses what is -known as 'network byte order' as the standard byte order (which is in -fact the big-endian byte order). - -Note that the byte order conversion macros may evaluate their arguments -multiple times, thus you should not use them with arguments which have -side-effects. - Gets the canonical file name from @filename. All triple slashes are turned into single slashes, and all `..` and `.`s resolved against @relative_to. @@ -40729,38 +42755,6 @@ version `@required_major.@required_minor.@required_micro` - - GLib offers a set of macros for doing additions and multiplications -of unsigned integers, with checks for overflows. - -The helpers all have three arguments. A pointer to the destination -is always the first argument and the operands to the operation are -the other two. - -Following standard GLib convention, the helpers return %TRUE in case -of success (ie: no overflow). - -The helpers may be macros, normal functions or inlines. They may be -implemented with inline assembly or compiler intrinsics where -available. - - - GLib provides a generic API for computing checksums (or "digests") -for a sequence of arbitrary bytes, using various hashing algorithms -like MD5, SHA-1 and SHA-256. Checksums are commonly used in various -environments and specifications. - -GLib supports incremental checksums using the GChecksum data -structure, by calling g_checksum_update() as long as there's data -available and then using g_checksum_get_string() or -g_checksum_get_digest() to compute the checksum and return it either -as a string in hexadecimal form, or as a raw sequence of bytes. To -compute the checksum for binary blobs and NUL-terminated strings in -one go, use the convenience functions g_compute_checksum_for_data() -and g_compute_checksum_for_string(), respectively. - -Support for checksums has been added in GLib 2.16 - Gets the length in bytes of digests of type @checksum_type @@ -40924,6 +42918,57 @@ Windows a handle for a process (which doesn't have to be a child). + + A wrapper for the POSIX chmod() function. The chmod() function is +used to set the permissions of a file system object. + +On Windows the file protection mechanism is not at all POSIX-like, +and the underlying chmod() function in the C library just sets or +clears the FAT-style READONLY attribute. It does not touch any +ACL. Software that needs to manage file permissions on Windows +exactly should use the Win32 API. + +See your C library manual for more details about chmod(). + + 0 if the operation succeeded, -1 on error + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in chmod() + + + + + + + + + + + + + + + + + + + + + + + + + + + + If @err or *@err is %NULL, does nothing. Otherwise, calls g_error_free() on *@err and sets *@err to %NULL. @@ -41233,100 +43278,15 @@ The hexadecimal string returned will be in lower case. - - The g_convert() family of function wraps the functionality of iconv(). -In addition to pure character set conversions, GLib has functions to -deal with the extra complications of encodings for file names. - -## File Name Encodings - -Historically, UNIX has not had a defined encoding for file names: -a file name is valid as long as it does not have path separators -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 -ISO-8859-1 for its encoding, -|[ -Character: P r e s e n t a c i ó n . s x i -Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 -]| -However, if the application use UTF-8, the actual file name on -disk would look like this: -|[ -Character: P r e s e n t a c i ó n . s x i -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, -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 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 -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 -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`: -|[ -export G_FILENAME_ENCODING=ISO-8859-1 -]| -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 -[diagram][file-name-encodings-diagram] illustrates how -these functions are used to convert between UTF-8 and the -encoding for file names in the file system. - -## Conversion between file name encodings # {#file-name-encodings-diagram) - -![](file-name-encodings.png) - -## Checklist for Application Writers - -This section is a practical summary of the detailed -things to do to make sure your applications process file -name encodings correctly. - -1. If you get a file name from the file system from a function - such as readdir() or gtk_file_chooser_get_filename(), you do - not need to do any conversion to pass that file name to - functions like open(), rename(), or fopen() -- those are "raw" - file names which the file system understands. - -2. If you need to display a file name, convert it to UTF-8 first - by using g_filename_to_utf8(). If conversion fails, display a - string like "Unknown file name". Do not convert this string back - into the encoding used for file names if you wish to pass it to - the file system; use the original file name instead. - - For example, the document window of a word processor could display - "Unknown file name" in its title bar but still let the user save - the file, as it would keep the raw file name internally. This - can happen if the user has not set the `G_FILENAME_ENCODING` - environment variable even though they have files whose names are - not encoded in UTF-8. - -3. If your user interface lets the user type a file name for saving - or renaming, convert it to the encoding used for file names in - the file system by using g_filename_from_utf8(). Pass the converted - file name to functions like fopen(). If conversion fails, ask the - user to enter a different file name. This can happen if the user - types Japanese characters when `G_FILENAME_ENCODING` is set to - `ISO-8859-1`, for example. - + + Allocates and initializes a new #GCond. + GCond can now be statically allocated, or embedded +in structures and initialised with g_cond_init(). + + a newly allocated #GCond. Free with g_cond_free() + + + Converts a string from one character set to another. @@ -41536,75 +43496,85 @@ unrepresentable characters, use g_convert_with_fallback(). + + A wrapper for the POSIX creat() function. The creat() function is +used to convert a pathname into a file descriptor, creating a file +if necessary. + +On POSIX systems file descriptors are implemented by the operating +system. On Windows, it's the C library that implements creat() and +file descriptors. The actual Windows API for opening files is +different, see MSDN documentation for CreateFile(). The Win32 API +uses file handles, which are more randomish integers, not small +integers like file descriptors. + +Because file descriptors are specific to the C library on Windows, +the file descriptor returned by this function makes sense only to +functions in the same C library. Thus if the GLib-using code uses a +different C library than GLib does, the file descriptor returned by +this function cannot be passed to C library functions like write() +or read(). + +See your C library manual for more details about creat(). + + a new file descriptor, or -1 if an error occurred. + The return value can be used exactly like the return value + from creat(). + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in creat() + + + + - Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL). + Logs a ‘critical warning’ ([flags@GLib.LogLevelFlags.CRITICAL]). Critical warnings are intended to be used in the event of an error that originated in the current process (a programmer error). Logging of a critical error is by definition an indication of a bug somewhere in the current program (or its libraries). -g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and -g_return_val_if_reached() log at %G_LOG_LEVEL_CRITICAL. +[func@GLib.return_if_fail], [func@GLib.return_val_if_fail], [func@GLib.return_if_reached] and +[func@GLib.return_val_if_reached] log at [flags@GLib.LogLevelFlags.CRITICAL]. You can make critical warnings fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](glib-running.html)): -|[ - G_DEBUG=fatal-warnings gdb ./my-program -]| +``` +G_DEBUG=fatal-warnings gdb ./my-program +``` -You can also use g_log_set_always_fatal(). +You can also use [func@GLib.log_set_always_fatal]. Any unrelated failures can be skipped over in [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. The message should typically *not* be translated to the -user's language. +user’s language. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). - format string, followed by parameters to insert - into the format string (as with printf()) + format string, followed by parameters to insert into the format string + (as with `printf()`) - - Keyed data lists provide lists of arbitrary data elements which can -be accessed either with a string or with a #GQuark corresponding to -the string. - -The #GQuark methods are quicker, since the strings have to be -converted to #GQuarks anyway. - -Data lists are used for associating arbitrary data with #GObjects, -using g_object_set_data() and related functions. - -To create a datalist, use g_datalist_init(). - -To add data elements to a datalist use g_datalist_id_set_data(), -g_datalist_id_set_data_full(), g_datalist_set_data() and -g_datalist_set_data_full(). - -To get data elements from a datalist use g_datalist_id_get_data() -and g_datalist_get_data(). - -To iterate over all data elements in a datalist use -g_datalist_foreach() (not thread-safe). - -To remove data elements from a datalist use -g_datalist_id_remove_data() and g_datalist_remove_data(). - -To remove all data elements from a datalist, use g_datalist_clear(). - Frees all the data elements of the datalist. The data elements' destroy functions are called @@ -42210,107 +44180,6 @@ function to call when the data element is destroyed. - - Datasets associate groups of data elements with particular memory -locations. These are useful if you need to associate data with a -structure returned from an external library. Since you cannot modify -the structure, you use its location in memory as the key into a -dataset, where you can associate any number of data elements with it. - -There are two forms of most of the dataset functions. The first form -uses strings to identify the data elements associated with a -location. The second form uses #GQuark identifiers, which are -created with a call to g_quark_from_string() or -g_quark_from_static_string(). The second form is quicker, since it -does not require looking up the string in the hash table of #GQuark -identifiers. - -There is no function to create a dataset. It is automatically -created as soon as you add elements to it. - -To add data elements to a dataset use g_dataset_id_set_data(), -g_dataset_id_set_data_full(), g_dataset_set_data() and -g_dataset_set_data_full(). - -To get data elements from a dataset use g_dataset_id_get_data() and -g_dataset_get_data(). - -To iterate over all data elements in a dataset use -g_dataset_foreach() (not thread-safe). - -To remove data elements from a dataset use -g_dataset_id_remove_data() and g_dataset_remove_data(). - -To destroy a dataset, use g_dataset_destroy(). - - - The #GDate data structure represents a day between January 1, Year 1, -and sometime a few thousand years in the future (right now it will go -to the year 65535 or so, but g_date_set_parse() only parses up to the -year 8000 or so - just count on "a few thousand"). #GDate is meant to -represent everyday dates, not astronomical dates or historical dates -or ISO timestamps or the like. It extrapolates the current Gregorian -calendar forward and backward in time; there is no attempt to change -the calendar to match time periods or locations. #GDate does not store -time information; it represents a day. - -The #GDate implementation has several nice features; it is only a -64-bit struct, so storing large numbers of dates is very efficient. It -can keep both a Julian and day-month-year representation of the date, -since some calculations are much easier with one representation or the -other. A Julian representation is simply a count of days since some -fixed day in the past; for #GDate the fixed day is January 1, 1 AD. -("Julian" dates in the #GDate API aren't really Julian dates in the -technical sense; technically, Julian dates count from the start of the -Julian period, Jan 1, 4713 BC). - -#GDate is simple to use. First you need a "blank" date; you can get a -dynamically allocated date from g_date_new(), or you can declare an -automatic variable or array and initialize it by -calling g_date_clear(). A cleared date is safe; it's safe to call -g_date_set_dmy() and the other mutator functions to initialize the -value of a cleared date. However, a cleared date is initially -invalid, meaning that it doesn't represent a day that exists. -It is undefined to call any of the date calculation routines on an -invalid date. If you obtain a date from a user or other -unpredictable source, you should check its validity with the -g_date_valid() predicate. g_date_valid() is also used to check for -errors with g_date_set_parse() and other functions that can -fail. Dates can be invalidated by calling g_date_clear() again. - -It is very important to use the API to access the #GDate -struct. Often only the day-month-year or only the Julian -representation is valid. Sometimes neither is valid. Use the API. - -GLib also features #GDateTime which represents a precise time. - - - #GDateTime is a structure that combines a Gregorian date and time -into a single structure. It provides many conversion and methods to -manipulate dates and times. Time precision is provided down to -microseconds and the time can range (proleptically) from 0001-01-01 -00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX -time in the sense that it is oblivious to leap seconds. - -#GDateTime is an immutable object; once it has been created it cannot -be modified further. All modifiers will create a new #GDateTime. -Nearly all such functions can fail due to the date or time going out -of range, in which case %NULL will be returned. - -#GDateTime is reference counted: the reference count is increased by calling -g_date_time_ref() and decreased by calling g_date_time_unref(). When the -reference count drops to 0, the resources allocated by the #GDateTime -structure are released. - -Many parts of the API may produce non-obvious results. As an -example, adding two months to January 31st will yield March 31st -whereas adding one month and then one month again will yield either -March 28th or March 29th. Also note that adding 24 hours is not -always the same as adding one day (since days containing daylight -savings time transitions are either 23 or 25 hours in length). - -#GDateTime is available since GLib 2.26. - Returns the number of days in a month, taking leap years into account. @@ -42541,24 +44410,26 @@ dcgettext() directly. - A convenience function/macro to log a debug message. The message should -typically *not* be translated to the user's language. + A convenience function/macro to log a debug message. + +The message should typically *not* be translated to the user’s language. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -Such messages are suppressed by the g_log_default_handler() and -g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is -set appropriately. +Such messages are suppressed by the [func@GLib.log_default_handler] and +[func@GLib.log_writer_default] unless the `G_MESSAGES_DEBUG` environment variable is +set appropriately. If you need to set the allowed domains at runtime, use +[func@GLib.log_writer_default_set_debug_domains]. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). - format string, followed by parameters to insert - into the format string (as with printf()) + format string, followed by parameters to insert into the format string + (as with `printf()`) @@ -42901,503 +44772,110 @@ environment @envp. - A convenience function/macro to log an error message. The message should -typically *not* be translated to the user's language. + A convenience function/macro to log an error message. -This is not intended for end user error reporting. Use of #GError is +The message should typically *not* be translated to the user’s language. + +This is not intended for end user error reporting. Use of [type@GLib.Error] is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error. -Error messages are always fatal, resulting in a call to G_BREAKPOINT() +Error messages are always fatal, resulting in a call to [func@GLib.BREAKPOINT] to terminate the application. This function will -result in a core dump; don't use it for errors you expect. +result in a core dump; don’t use it for errors you expect. Using this function indicates a bug in your program, i.e. an assertion failure. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). - format string, followed by parameters to insert - into the format string (as with printf()) + format string, followed by parameters to insert into the format string + (as with `printf()`) - - GLib provides a standard method of reporting errors from a called -function to the calling code. (This is the same problem solved by -exceptions in other languages.) It's important to understand that -this method is both a data type (the #GError struct) and a [set of -rules][gerror-rules]. If you use #GError incorrectly, then your code will not -properly interoperate with other code that uses #GError, and users -of your API will probably get confused. In most cases, [using #GError is -preferred over numeric error codes][gerror-comparison], but there are -situations where numeric error codes are useful for performance. - -First and foremost: #GError should only be used to report recoverable -runtime errors, never to report programming errors. If the programmer -has screwed up, then you should use g_warning(), g_return_if_fail(), -g_assert(), g_error(), or some similar facility. (Incidentally, -remember that the g_error() function should only be used for -programming errors, it should not be used to print any error -reportable via #GError.) - -Examples of recoverable runtime errors are "file not found" or -"failed to parse input." Examples of programming errors are "NULL -passed to strcmp()" or "attempted to free the same pointer twice." -These two kinds of errors are fundamentally different: runtime errors -should be handled or reported to the user, programming errors should -be eliminated by fixing the bug in the program. This is why most -functions in GLib and GTK do not use the #GError facility. - -Functions that can fail take a return location for a #GError as their -last argument. On error, a new #GError instance will be allocated and -returned to the caller via this argument. For example: -|[<!-- language="C" --> -gboolean g_file_get_contents (const gchar *filename, - gchar **contents, - gsize *length, - GError **error); -]| -If you pass a non-%NULL value for the `error` argument, it should -point to a location where an error can be placed. For example: -|[<!-- language="C" --> -gchar *contents; -GError *err = NULL; - -g_file_get_contents ("foo.txt", &contents, NULL, &err); -g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); -if (err != NULL) - { - // Report error to user, and free error - g_assert (contents == NULL); - fprintf (stderr, "Unable to read file: %s\n", err->message); - g_error_free (err); - } -else - { - // Use file contents - g_assert (contents != NULL); - } -]| -Note that `err != NULL` in this example is a reliable indicator -of whether g_file_get_contents() failed. Additionally, -g_file_get_contents() returns a boolean which -indicates whether it was successful. - -Because g_file_get_contents() returns %FALSE on failure, if you -are only interested in whether it failed and don't need to display -an error message, you can pass %NULL for the @error argument: -|[<!-- language="C" --> -if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors - // no error occurred - ; -else - // error - ; -]| - -The #GError object contains three fields: @domain indicates the module -the error-reporting function is located in, @code indicates the specific -error that occurred, and @message is a user-readable error message with -as many details as possible. Several functions are provided to deal -with an error received from a called function: g_error_matches() -returns %TRUE if the error matches a given domain and code, -g_propagate_error() copies an error into an error location (so the -calling function will receive it), and g_clear_error() clears an -error location by freeing the error and resetting the location to -%NULL. To display an error to the user, simply display the @message, -perhaps along with additional context known only to the calling -function (the file being opened, or whatever - though in the -g_file_get_contents() case, the @message already contains a filename). - -Since error messages may be displayed to the user, they need to be valid -UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in -particular when formatting error messages with filenames, which are in -the 'filename encoding', and need to be turned into UTF-8 using -g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid(). - -Note, however, that many error messages are too technical to display to the -user in an application, so prefer to use g_error_matches() to categorize errors -from called functions, and build an appropriate error message for the context -within your application. Error messages from a #GError are more appropriate -to be printed in system logs or on the command line. They are typically -translated. - -When implementing a function that can report errors, the basic -tool is g_set_error(). Typically, if a fatal error occurs you -want to g_set_error(), then return immediately. g_set_error() -does nothing if the error location passed to it is %NULL. -Here's an example: -|[<!-- language="C" --> -gint -foo_open_file (GError **error) -{ - gint fd; - int saved_errno; - - g_return_val_if_fail (error == NULL || *error == NULL, -1); - - fd = open ("file.txt", O_RDONLY); - saved_errno = errno; - - if (fd < 0) - { - g_set_error (error, - FOO_ERROR, // error domain - FOO_ERROR_BLAH, // error code - "Failed to open file: %s", // error message format string - g_strerror (saved_errno)); - return -1; - } - else - return fd; -} -]| - -Things are somewhat more complicated if you yourself call another -function that can report a #GError. If the sub-function indicates -fatal errors in some way other than reporting a #GError, such as -by returning %TRUE on success, you can simply do the following: -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - if (!sub_function_that_can_fail (err)) - { - // assert that error was set by the sub-function - g_assert (err == NULL || *err != NULL); - return FALSE; - } - - // otherwise continue, no error occurred - g_assert (err == NULL || *err == NULL); -} -]| - -If the sub-function does not indicate errors other than by -reporting a #GError (or if its return value does not reliably indicate -errors) you need to create a temporary #GError -since the passed-in one may be %NULL. g_propagate_error() is -intended for use in this case. -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - GError *tmp_error; - - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - tmp_error = NULL; - sub_function_that_can_fail (&tmp_error); - - if (tmp_error != NULL) - { - // store tmp_error in err, if err != NULL, - // otherwise call g_error_free() on tmp_error - g_propagate_error (err, tmp_error); - return FALSE; - } - - // otherwise continue, no error occurred -} -]| - -Error pileups are always a bug. For example, this code is incorrect: -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - GError *tmp_error; - - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - tmp_error = NULL; - sub_function_that_can_fail (&tmp_error); - other_function_that_can_fail (&tmp_error); - - if (tmp_error != NULL) - { - g_propagate_error (err, tmp_error); - return FALSE; - } -} -]| -@tmp_error should be checked immediately after sub_function_that_can_fail(), -and either cleared or propagated upward. The rule is: after each error, -you must either handle the error, or return it to the calling function. - -Note that passing %NULL for the error location is the equivalent -of handling an error by always doing nothing about it. So the -following code is fine, assuming errors in sub_function_that_can_fail() -are not fatal to my_function_that_can_fail(): -|[<!-- language="C" --> -gboolean -my_function_that_can_fail (GError **err) -{ - GError *tmp_error; - - g_return_val_if_fail (err == NULL || *err == NULL, FALSE); - - sub_function_that_can_fail (NULL); // ignore errors - - tmp_error = NULL; - other_function_that_can_fail (&tmp_error); - - if (tmp_error != NULL) - { - g_propagate_error (err, tmp_error); - return FALSE; - } -} -]| - -Note that passing %NULL for the error location ignores errors; -it's equivalent to -`try { sub_function_that_can_fail (); } catch (...) {}` -in C++. It does not mean to leave errors unhandled; it means -to handle them by doing nothing. - -Error domains and codes are conventionally named as follows: - -- The error domain is called <NAMESPACE>_<MODULE>_ERROR, - for example %G_SPAWN_ERROR or %G_THREAD_ERROR: - |[<!-- language="C" --> - #define G_SPAWN_ERROR g_spawn_error_quark () - - G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error) - ]| - -- The quark function for the error domain is called - <namespace>_<module>_error_quark, - for example g_spawn_error_quark() or g_thread_error_quark(). - -- The error codes are in an enumeration called - <Namespace><Module>Error; - for example, #GThreadError or #GSpawnError. - -- Members of the error code enumeration are called - <NAMESPACE>_<MODULE>_ERROR_<CODE>, - for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. - -- If there's a "generic" or "unknown" error code for unrecoverable - errors it doesn't make sense to distinguish with specific codes, - it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, - for example %G_SPAWN_ERROR_FAILED. In the case of error code - enumerations that may be extended in future releases, you should - generally not handle this error code explicitly, but should - instead treat any unrecognized error code as equivalent to - FAILED. - -## Comparison of #GError and traditional error handling # {#gerror-comparison} - -#GError has several advantages over traditional numeric error codes: -importantly, tools like -[gobject-introspection](https://developer.gnome.org/gi/stable/) understand -#GErrors and convert them to exceptions in bindings; the message includes -more information than just a code; and use of a domain helps prevent -misinterpretation of error codes. - -#GError has disadvantages though: it requires a memory allocation, and -formatting the error message string has a performance overhead. This makes it -unsuitable for use in retry loops where errors are a common case, rather than -being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these -overheads in the normal control flow. String formatting overhead can be -eliminated by using g_set_error_literal() in some cases. - -These performance issues can be compounded if a function wraps the #GErrors -returned by the functions it calls: this multiplies the number of allocations -and string formatting operations. This can be partially mitigated by using -g_prefix_error(). - -## Rules for use of #GError # {#gerror-rules} - -Summary of rules for use of #GError: - -- Do not report programming errors via #GError. - -- The last argument of a function that returns an error should - be a location where a #GError can be placed (i.e. `GError **error`). - If #GError is used with varargs, the `GError**` should be the last - argument before the `...`. - -- The caller may pass %NULL for the `GError**` if they are not interested - in details of the exact error that occurred. - -- If %NULL is passed for the `GError**` argument, then errors should - not be returned to the caller, but your function should still - abort and return if an error occurs. That is, control flow should - not be affected by whether the caller wants to get a #GError. - -- If a #GError is reported, then your function by definition had a - fatal failure and did not complete whatever it was supposed to do. - If the failure was not fatal, then you handled it and you should not - report it. If it was fatal, then you must report it and discontinue - whatever you were doing immediately. - -- If a #GError is reported, out parameters are not guaranteed to - be set to any defined value. - -- A `GError*` must be initialized to %NULL before passing its address - to a function that can report errors. - -- #GError structs must not be stack-allocated. - -- "Piling up" errors is always a bug. That is, if you assign a - new #GError to a `GError*` that is non-%NULL, thus overwriting - the previous error, it indicates that you should have aborted - the operation instead of continuing. If you were able to continue, - you should have cleared the previous error with g_clear_error(). - g_set_error() will complain if you pile up errors. - -- By convention, if you return a boolean value indicating success - then %TRUE means success and %FALSE means failure. Avoid creating - functions which have a boolean return value and a #GError parameter, - but where the boolean does something other than signal whether the - #GError is set. Among other problems, it requires C callers to allocate - a temporary error. Instead, provide a `gboolean *` out parameter. - There are functions in GLib itself such as g_key_file_has_key() that - are hard to use because of this. If %FALSE is returned, the error must - be set to a non-%NULL value. One exception to this is that in situations - that are already considered to be undefined behaviour (such as when a - g_return_val_if_fail() check fails), the error need not be set. - Instead of checking separately whether the error is set, callers - should ensure that they do not provoke undefined behaviour, then - assume that the error will be set on failure. - -- A %NULL return value is also frequently used to mean that an error - occurred. You should make clear in your documentation whether %NULL - is a valid return value in non-error cases; if %NULL is a valid value, - then users must check whether an error was returned to see if the - function succeeded. - -- When implementing a function that can report errors, you may want - to add a check at the top of your function that the error return - location is either %NULL or contains a %NULL error (e.g. - `g_return_if_fail (error == NULL || *error == NULL);`). - -## Extended #GError Domains # {#gerror-extended-domains} - -Since GLib 2.68 it is possible to extend the #GError type. This is -done with the G_DEFINE_EXTENDED_ERROR() macro. To create an -extended #GError type do something like this in the header file: -|[<!-- language="C" --> -typedef enum -{ - MY_ERROR_BAD_REQUEST, -} MyError; -#define MY_ERROR (my_error_quark ()) -GQuark my_error_quark (void); -int -my_error_get_parse_error_id (GError *error); -const char * -my_error_get_bad_request_details (GError *error); -]| -and in implementation: -|[<!-- language="C" --> -typedef struct -{ - int parse_error_id; - char *bad_request_details; -} MyErrorPrivate; - -static void -my_error_private_init (MyErrorPrivate *priv) -{ - priv->parse_error_id = -1; - // No need to set priv->bad_request_details to NULL, - // the struct is initialized with zeros. -} - -static void -my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv) -{ - dest_priv->parse_error_id = src_priv->parse_error_id; - dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details); -} - -static void -my_error_private_clear (MyErrorPrivate *priv) -{ - g_free (priv->bad_request_details); -} - -// This defines the my_error_get_private and my_error_quark functions. -G_DEFINE_EXTENDED_ERROR (MyError, my_error) + + This function registers an extended #GError domain. +@error_type_name will be duplicated. Otherwise does the same as +g_error_domain_register_static(). + + #GQuark representing the error domain + + + + + string to create a #GQuark from + + + + size of the private error data in bytes + + + + function initializing fields of the private error data + + + + function copying fields of the private error data + + + + function freeing fields of the private error data + + + + + + This function registers an extended #GError domain. -int -my_error_get_parse_error_id (GError *error) -{ - MyErrorPrivate *priv = my_error_get_private (error); - g_return_val_if_fail (priv != NULL, -1); - return priv->parse_error_id; -} +@error_type_name should not be freed. @error_type_private_size must +be greater than 0. -const char * -my_error_get_bad_request_details (GError *error) -{ - MyErrorPrivate *priv = my_error_get_private (error); - g_return_val_if_fail (priv != NULL, NULL); - g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL); - return priv->bad_request_details; -} +@error_type_init receives an initialized #GError and should then initialize +the private data. -static void -my_error_set_bad_request (GError **error, - const char *reason, - int error_id, - const char *details) -{ - MyErrorPrivate *priv; - g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason); - if (error != NULL && *error != NULL) - { - priv = my_error_get_private (error); - g_return_val_if_fail (priv != NULL, NULL); - priv->parse_error_id = error_id; - priv->bad_request_details = g_strdup (details); - } -} -]| -An example of use of the error could be: -|[<!-- language="C" --> -gboolean -send_request (GBytes *request, GError **error) -{ - ParseFailedStatus *failure = validate_request (request); - if (failure != NULL) - { - my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details); - parse_failed_status_free (failure); - return FALSE; - } +@error_type_copy is a function that receives both original and a copy +#GError and should copy the fields of the private error data. The standard +#GError fields are already handled. - return send_one (request, error); -} -]| +@error_type_clear receives the pointer to the error, and it should free the +fields of the private error data. It should not free the struct itself though. -Please note that if you are a library author and your library -exposes an existing error domain, then you can't make this error -domain an extended one without breaking ABI. This is because -earlier it was possible to create an error with this error domain -on the stack and then copy it with g_error_copy(). If the new -version of your library makes the error domain an extended one, -then g_error_copy() called by code that allocated the error on the -stack will try to copy more data than it used to, which will lead -to undefined behavior. You must not stack-allocate errors with an -extended error domain, and it is bad practice to stack-allocate any -other #GErrors. - -Extended error domains in unloadable plugins/modules are not -supported. - +Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it +already takes care of passing valid information to this function. + + #GQuark representing the error domain + + + + + static string to create a #GQuark from + + + + size of the private error data in bytes + + + + function initializing fields of the private error data + + + + function copying fields of the private error data + + + + function freeing fields of the private error data + + + + Gets a #GFileError constant based on the passed-in @err_no. @@ -43915,38 +45393,6 @@ may contain embedded nul characters. - - Do not use these APIs unless you are porting a POSIX application to Windows. -A more high-level file access API is provided as GIO — see the documentation -for #GFile. - -There is a group of functions which wrap the common POSIX functions -dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(), -g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these -wrappers is to make it possible to handle file names with any Unicode -characters in them on Windows without having to use ifdefs and the -wide character API in the application code. - -On some Unix systems, these APIs may be defined as identical to their POSIX -counterparts. For this reason, you must check for and include the necessary -header files (such as `fcntl.h`) before using functions like g_creat(). You -must also define the relevant feature test macros. - -The pathname argument should be in the GLib file name encoding. -On POSIX this is the actual on-disk encoding which might correspond -to the locale settings of the process (or the `G_FILENAME_ENCODING` -environment variable), or not. - -On Windows the GLib file name encoding is UTF-8. Note that the -Microsoft C library does not use UTF-8, but has separate APIs for -current system code page and wide characters (UTF-16). The GLib -wrappers call the wide character API if present (on modern Windows -systems), otherwise convert to/from the system code page. - -Another group of functions allows to open and read directories -in the GLib file name encoding. These are g_dir_open(), -g_dir_read_name(), g_dir_rewind(), g_dir_close(). - Locates the first executable named @program in the user's path, in the same way that execvp() would locate it. Returns an allocated string @@ -43977,6 +45423,40 @@ including the type suffix. + + A wrapper for the stdio `fopen()` function. The `fopen()` function +opens a file and associates a new stream with it. + +Because file descriptors are specific to the C library on Windows, +and a file descriptor is part of the `FILE` struct, the `FILE*` returned +by this function makes sense only to functions in the same C library. +Thus if the GLib-using code uses a different C library than GLib does, +the FILE* returned by this function cannot be passed to C library +functions like `fprintf()` or `fread()`. + +See your C library manual for more details about `fopen()`. + +As `close()` and `fclose()` are part of the C library, this implies that it is +currently impossible to close a file if the application C library and the C library +used by GLib are different. Convenience functions like g_file_set_contents_full() +avoid this problem. + + A `FILE*` if the file was successfully opened, or %NULL if + an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a string describing the mode in which the file should be opened + + + + Formats a size (for example the size of a file) into a human readable string. Sizes are rounded to the nearest size prefix (kB, MB, GB) @@ -44064,7 +45544,7 @@ positional parameters, as specified in the Single Unix Specification. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -44123,6 +45603,53 @@ since GLib 2.78. + + A wrapper for the POSIX freopen() function. The freopen() function +opens a file and associates it with an existing stream. + +See your C library manual for more details about freopen(). + + A FILE* if the file was successfully opened, or %NULL if + an error occurred. + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a string describing the mode in which the file should be opened + + + + an existing stream which will be reused, or %NULL + + + + + + A wrapper for the POSIX `fsync()` function. On Windows, `_commit()` will be +used. On macOS, `fcntl(F_FULLFSYNC)` will be used. +The `fsync()` function is used to synchronize a file's in-core +state with that of the disk. + +This wrapper will handle retrying on `EINTR`. + +See the C library manual for more details about fsync(). + + 0 on success, or -1 if an error occurred. +The return value can be used exactly like the return value from fsync(). + + + + + a file descriptor + + + + Gets a human-readable name for the application, as set by g_set_application_name(). This name should be localized if @@ -44776,29 +46303,6 @@ references to other environment variables, they are expanded. - - Functions for manipulating internet hostnames; in particular, for -converting between Unicode and ASCII-encoded forms of -Internationalized Domain Names (IDNs). - -The -[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) -standards allow for the use -of Unicode domain names in applications, while providing -backward-compatibility with the old ASCII-only DNS, by defining an -ASCII-Compatible Encoding of any given Unicode name, which can be -used with non-IDN-aware applications and protocols. (For example, -"Παν語.org" maps to "xn--4wa8awb4637h.org".) - - - Most of GLib is intended to be portable; in contrast, this set of -functions is designed for programs which explicitly target UNIX, -or are using it to build higher level abstractions which would be -conditionally compiled if the platform matches %G_OS_UNIX. - -To use these functions, you must explicitly include the -"glib-unix.h" header. - This is a convenience function for using a #GHashTable as a set. It is equivalent to calling g_hash_table_replace() with @key as both the @@ -44873,6 +46377,139 @@ destruction phase. + + Calls the given function for key/value pairs in the #GHashTable +until @predicate returns %TRUE. The function is passed the key +and value of each pair, and the given @user_data parameter. The +hash table may not be modified while iterating over it (you can't +add/remove items). + +Note, that hash tables are really only optimized for forward +lookups, i.e. g_hash_table_lookup(). So code that frequently issues +g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of +once per every entry in a hash table) should probably be reworked +to use additional or different data structures for reverse lookups +(keep in mind that an O(n) find/foreach operation issued for all n +values in a hash table ends up needing O(n*n) operations). + + The value of the first key/value pair is returned, + for which @predicate evaluates to %TRUE. If no pair with the + requested property is found, %NULL is returned. + + + + + a #GHashTable + + + + + + + function to test the key/value pairs for a certain property + + + + user data to pass to the function + + + + + + Calls the given function for each of the key/value pairs in the +#GHashTable. The function is passed the key and value of each +pair, and the given @user_data parameter. The hash table may not +be modified while iterating over it (you can't add/remove +items). To remove all items matching a predicate, use +g_hash_table_foreach_remove(). + +The order in which g_hash_table_foreach() iterates over the keys/values in +the hash table is not defined. + +See g_hash_table_find() for performance caveats for linear +order searches in contrast to g_hash_table_lookup(). + + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Calls the given function for each key/value pair in the +#GHashTable. If the function returns %TRUE, then the key/value +pair is removed from the #GHashTable. If you supplied key or +value destroy functions when creating the #GHashTable, they are +used to free the memory allocated for the removed keys and values. + +See #GHashTableIter for an alternative way to loop over the +key/value pairs in the hash table. + + the number of key/value pairs removed + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + + + Calls the given function for each key/value pair in the +#GHashTable. If the function returns %TRUE, then the key/value +pair is removed from the #GHashTable, but no key or value +destroy functions are called. + +See #GHashTableIter for an alternative way to loop over the +key/value pairs in the hash table. + + the number of key/value pairs removed. + + + + + a #GHashTable + + + + + + + the function to call for each key/value pair + + + + user data to pass to the function + + + + This function is deprecated and will be removed in the next major release of GLib. It does nothing. @@ -45054,6 +46691,26 @@ or values from @other_hash_table. + + Atomically increments the reference count of @hash_table by one. +This function is MT-safe and may be called from any thread. + + the passed in #GHashTable + + + + + + + + a valid #GHashTable + + + + + + + Removes a key and its associated value from a #GHashTable. @@ -45293,7 +46950,7 @@ This function is MT-safe and may be called from any thread. - + a valid #GHashTable @@ -45302,73 +46959,6 @@ This function is MT-safe and may be called from any thread. - - A #GHashTable provides associations between keys and values which is -optimized so that given a key, the associated value can be found, -inserted or removed in amortized O(1). All operations going through -each element take O(n) time (list all keys/values, table resize, etc.). - -Note that neither keys nor values are copied when inserted into the -#GHashTable, so they must exist for the lifetime of the #GHashTable. -This means that the use of static strings is OK, but temporary -strings (i.e. those created in buffers and those returned by GTK -widgets) should be copied with g_strdup() before being inserted. - -If keys or values are dynamically allocated, you must be careful to -ensure that they are freed when they are removed from the -#GHashTable, and also when they are overwritten by new insertions -into the #GHashTable. It is also not advisable to mix static strings -and dynamically-allocated strings in a #GHashTable, because it then -becomes difficult to determine whether the string should be freed. - -To create a #GHashTable, use g_hash_table_new(). - -To insert a key and value into a #GHashTable, use -g_hash_table_insert(). - -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 -check if a key is present in the hash table. - -To remove a key and value, use g_hash_table_remove(). - -To call a function for each key and value pair use -g_hash_table_foreach() or use an iterator to iterate over the -key/value pairs in the hash table, see #GHashTableIter. The iteration order -of a hash table is not defined, and you must not rely on iterating over -keys/values in the same order as they were inserted. - -To destroy a #GHashTable use g_hash_table_destroy(). - -A common use-case for hash tables is to store information about a -set of keys, without associating any particular value with each -key. GHashTable optimizes one way of doing so: If you store only -key-value pairs where key == value, then GHashTable does not -allocate memory to store the values, which can be a considerable -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/). - - - HMACs should be used when producing a cookie or hash based on data -and a key. Simple mechanisms for using SHA1 and other algorithms to -digest a key and data together are vulnerable to various security -issues. -[HMAC](http://en.wikipedia.org/wiki/HMAC) -uses algorithms like SHA1 in a secure way to produce a digest of a -key and data. - -Both the key and data are arbitrary byte arrays of bytes or characters. - -Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 -in GLib 2.42. Support for SHA-384 was added in GLib 2.52. - Appends a #GHook onto the end of a #GHookList. @@ -45451,6 +47041,26 @@ and frees the memory allocated for the #GHook. + + Inserts a #GHook into a #GHookList, sorted by the given function. + + + + + + a #GHookList + + + + the #GHook to insert + + + + the comparison function used to sort the #GHook elements + + + + Prepends a #GHook on the start of a #GHookList. @@ -45485,11 +47095,6 @@ from the #GHookList and g_hook_free() is called to free it. - - The #GHookList, #GHook and their related functions provide support for -lists of hook functions. Functions can be added and removed from the lists, -and the list of hook functions can be invoked. - Tests if @hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns @@ -45583,65 +47188,17 @@ the canonical presentation form will be entirely ASCII. - Converts a 32-bit integer value from host to network byte order. - a 32-bit integer value in host byte order - Converts a 16-bit integer value from host to network byte order. - a 16-bit integer value in host byte order - - GLib doesn't force any particular localization method upon its users. -But since GLib itself is localized using the gettext() mechanism, it seems -natural to offer the de-facto standard gettext() support macros in an -easy-to-use form. - -In order to use these macros in an application, you must include -`<glib/gi18n.h>`. For use in a library, you must include -`<glib/gi18n-lib.h>` -after defining the %GETTEXT_PACKAGE macro suitably for your library: -|[<!-- language="C" --> -#define GETTEXT_PACKAGE "gtk20" -#include <glib/gi18n-lib.h> -]| -For an application, note that you also have to call bindtextdomain(), -bind_textdomain_codeset(), textdomain() and setlocale() early on in your -main() to make gettext() work. For example: -|[<!-- language="C" --> -#include <glib/gi18n.h> -#include <locale.h> - -int -main (int argc, char **argv) -{ - setlocale (LC_ALL, ""); - bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale"); - bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8"); - textdomain (GETTEXT_PACKAGE); - - // Rest of your application. -} -]| -where `DATADIR` is as typically provided by automake or Meson. - -For a library, you only have to call bindtextdomain() and -bind_textdomain_codeset() in your initialization function. If your library -doesn't have an initialization function, you can call the functions before -the first translated message. - -The -[gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers) -covers details of how to integrate gettext into a project’s build system and -workflow. - Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack @@ -45826,23 +47383,26 @@ have a default priority of %G_PRIORITY_DEFAULT. - A convenience function/macro to log an informational message. Seldom used. + A convenience function/macro to log an informational message. + +Seldom used. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -Such messages are suppressed by the g_log_default_handler() and -g_log_writer_default() unless the `G_MESSAGES_DEBUG` environment variable is -set appropriately. +Such messages are suppressed by the [func@GLib.log_default_handler] and +[func@GLib.log_writer_default] unless the `G_MESSAGES_DEBUG` environment variable is +set appropriately. If you need to set the allowed domains at runtime, use +[func@GLib.log_writer_default_set_debug_domains]. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). - format string, followed by parameters to insert - into the format string (as with printf()) + format string, followed by parameters to insert into the format string + (as with `printf()`) @@ -46080,173 +47640,11 @@ implementation and unavoidable. - - The #GIOChannel data type aims to provide a portable method for -using file descriptors, pipes, and sockets, and integrating them -into the [main event loop][glib-The-Main-Event-Loop]. Currently, -full support is available on UNIX platforms, support for Windows -is only partially complete. - -To create a new #GIOChannel on UNIX systems use -g_io_channel_unix_new(). This works for plain file descriptors, -pipes and sockets. Alternatively, a channel can be created for a -file in a system independent manner using g_io_channel_new_file(). - -Once a #GIOChannel has been created, it can be used in a generic -manner with the functions g_io_channel_read_chars(), -g_io_channel_write_chars(), g_io_channel_seek_position(), and -g_io_channel_shutdown(). - -To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], -use g_io_add_watch() or g_io_add_watch_full(). Here you specify which -events you are interested in on the #GIOChannel, and provide a -function to be called whenever these events occur. - -#GIOChannel instances are created with an initial reference count of 1. -g_io_channel_ref() and g_io_channel_unref() can be used to -increment or decrement the reference count respectively. When the -reference count falls to 0, the #GIOChannel is freed. (Though it -isn't closed automatically, unless it was created using -g_io_channel_new_file().) Using g_io_add_watch() or -g_io_add_watch_full() increments a channel's reference count. - -The new functions g_io_channel_read_chars(), -g_io_channel_read_line(), g_io_channel_read_line_string(), -g_io_channel_read_to_end(), g_io_channel_write_chars(), -g_io_channel_seek_position(), and g_io_channel_flush() should not be -mixed with the deprecated functions g_io_channel_read(), -g_io_channel_write(), and g_io_channel_seek() on the same channel. - - - The #GList structure and its associated functions provide a standard -doubly-linked list data structure. The benefit of this data-structure -is to provide insertion/deletion operations in O(1) complexity where -access/search operations are in O(n). The benefit of #GList over -#GSList (singly linked list) is that the worst case on access/search -operations is divided by two which comes at a cost in space as we need -to retain two pointers in place of one. - -Each element in the list contains a piece of data, together with -pointers which link to the previous and next elements in the list. -Using these pointers it is possible to move through the list in both -directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], -which only allows movement through the list in the forward direction). - -The double linked list does not keep track of the number of items -and does not keep track of both the start and end of the list. If -you want fast access to both the start and the end of the list, -and/or the number of items in the list, use a -[GQueue][glib-Double-ended-Queues] instead. - -The data contained in each element can be either integer values, by -using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], -or simply pointers to any type of data. - -List elements are allocated from the [slice allocator][glib-Memory-Slices], -which is more efficient than allocating elements individually. - -Note that most of the #GList functions expect to be passed a pointer -to the first element in the list. The functions which insert -elements return the new start of the list, which may have changed. - -There is no function to create a #GList. %NULL is considered to be -a valid, empty list so you simply set a #GList* to %NULL to initialize -it. - -To add elements, use g_list_append(), g_list_prepend(), -g_list_insert() and g_list_insert_sorted(). - -To visit all elements in the list, use a loop over the list: -|[<!-- language="C" --> -GList *l; -for (l = list; l != NULL; l = l->next) - { - // do something with l->data - } -]| - -To call a function for each element in the list, use g_list_foreach(). - -To loop over the list and modify it (e.g. remove a certain element) -a while loop is more appropriate, for example: -|[<!-- language="C" --> -GList *l = list; -while (l != NULL) - { - GList *next = l->next; - if (should_be_removed (l)) - { - // possibly free l->data - list = g_list_delete_link (list, l); - } - l = next; - } -]| - -To remove elements, use g_list_remove(). - -To navigate in a list, use g_list_first(), g_list_last(), -g_list_next(), g_list_previous(). - -To find elements in the list use g_list_nth(), g_list_nth_data(), -g_list_find() and g_list_find_custom(). - -To find the index of an element use g_list_position() and -g_list_index(). - -To free the entire list, use g_list_free() or g_list_free_full(). - - - The #GSList structure and its associated functions provide a -standard singly-linked list data structure. The benefit of this -data-structure is to provide insertion/deletion operations in O(1) -complexity where access/search operations are in O(n). The benefit -of #GSList over #GList (doubly linked list) is that they are lighter -in space as they only need to retain one pointer but it double the -cost of the worst case access/search operations. - -Each element in the list contains a piece of data, together with a -pointer which links to the next element in the list. Using this -pointer it is possible to move through the list in one direction -only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], -which allow movement in both directions). - -The data contained in each element can be either integer values, by -using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], -or simply pointers to any type of data. - -List elements are allocated from the [slice allocator][glib-Memory-Slices], -which is more efficient than allocating elements individually. - -Note that most of the #GSList functions expect to be passed a -pointer to the first element in the list. The functions which insert -elements return the new start of the list, which may have changed. - -There is no function to create a #GSList. %NULL is considered to be -the empty list so you simply set a #GSList* to %NULL. - -To add elements, use g_slist_append(), g_slist_prepend(), -g_slist_insert() and g_slist_insert_sorted(). - -To remove elements, use g_slist_remove(). - -To find elements in the list use g_slist_last(), g_slist_next(), -g_slist_nth(), g_slist_nth_data(), g_slist_find() and -g_slist_find_custom(). - -To find the index of an element use g_slist_position() and -g_slist_index(). - -To call a function for each element in the list use -g_slist_foreach(). - -To free the entire list, use g_slist_free(). - A convenience macro to get the next element in a #GList. Note that it is considered perfectly acceptable to access @@ -46257,6 +47655,11 @@ Note that it is considered perfectly acceptable to access + + + + + A convenience macro to get the previous element in a #GList. Note that it is considered perfectly acceptable to access @@ -46267,6 +47670,16 @@ Note that it is considered perfectly acceptable to access + + + + + + + + + + Gets the names of all variables set in the environment. @@ -46384,27 +47797,27 @@ may contain embedded nul characters. Logs an error or debugging message. -If the log level has been set as fatal, G_BREAKPOINT() is called -to terminate the program. See the documentation for G_BREAKPOINT() for +If the log level has been set as fatal, [func@GLib.BREAKPOINT] is called +to terminate the program. See the documentation for [func@GLib.BREAKPOINT] for details of the debugging options this provides. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If [structured logging is enabled][using-structured-logging] this will -output via the structured log writer function (see g_log_set_writer_func()). +If [structured logging is enabled](logging.html#using-structured-logging) this will +output via the structured log writer function (see [func@GLib.log_set_writer_func]). - the log domain, usually %G_LOG_DOMAIN, or %NULL + the log domain, usually `G_LOG_DOMAIN`, or `NULL` for the default - the log level, either from #GLogLevelFlags + the log level, either from [type@GLib.LogLevelFlags] or a user-defined level @@ -46419,39 +47832,41 @@ output via the structured log writer function (see g_log_set_writer_func()). - The default log handler set up by GLib; g_log_set_default_handler() + The default log handler set up by GLib; [func@GLib.log_set_default_handler] allows to install an alternate default log handler. + This is used if no log handler has been set for the particular log -domain and log level combination. It outputs the message to stderr -or stdout and if the log level is fatal it calls G_BREAKPOINT(). It automatically +domain and log level combination. It outputs the message to `stderr` +or `stdout` and if the log level is fatal it calls [func@GLib.BREAKPOINT]. It automatically prints a new-line character after the message, so one does not need to be manually included in @message. The behavior of this log handler can be influenced by a number of environment variables: -- `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which - messages should be prefixed by the program name and PID of the - application. - -- `G_MESSAGES_DEBUG`: A space-separated list of log domains for - which debug and informational messages are printed. By default - these messages are not printed. + - `G_MESSAGES_PREFIXED`: A `:`-separated list of log levels for which + messages should be prefixed by the program name and PID of the + application. + - `G_MESSAGES_DEBUG`: A space-separated list of log domains for + which debug and informational messages are printed. By default + these messages are not printed. If you need to set the allowed + domains at runtime, use [func@GLib.log_writer_default_set_debug_domains]. -stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL, -%G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for -the rest, unless stderr was requested by -g_log_writer_default_set_use_stderr(). +`stderr` is used for levels [flags@GLib.LogLevelFlags.ERROR], +[flags@GLib.LogLevelFlags.CRITICAL], [flags@GLib.LogLevelFlags.WARNING] and +[flags@GLib.LogLevelFlags.MESSAGE]. `stdout` is used for +the rest, unless `stderr` was requested by +[func@GLib.log_writer_default_set_use_stderr]. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). - the log domain of the message, or %NULL for the -default "" application domain + the log domain of the message, or `NULL` for the + default `""` application domain @@ -46463,7 +47878,7 @@ default "" application domain - data passed from g_log() which is unused + data passed from [func@GLib.log] which is unused @@ -46471,14 +47886,14 @@ default "" application domain Return whether debug output from the GLib logging system is enabled. -Note that this should not be used to conditionalise calls to g_debug() or -other logging functions; it should only be used from %GLogWriterFunc +Note that this should not be used to conditionalise calls to [func@GLib.debug] or +other logging functions; it should only be used from [type@GLib.LogWriterFunc] implementations. -Note also that the value of this does not depend on `G_MESSAGES_DEBUG`; see -the docs for g_log_set_debug_enabled(). +Note also that the value of this does not depend on `G_MESSAGES_DEBUG`, nor +[func@GLib.log_writer_default_set_debug_domains]; see the docs for [func@GLib.log_set_debug_enabled]. - %TRUE if debug output is enabled, %FALSE otherwise + `TRUE` if debug output is enabled, `FALSE` otherwise @@ -46486,7 +47901,7 @@ the docs for g_log_set_debug_enabled(). Removes the log handler. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). @@ -46496,17 +47911,18 @@ This has no effect if structured logging is enabled; see - the id of the handler, which was returned - in g_log_set_handler() + the ID of the handler, which was returned + in [func@GLib.log_set_handler] Sets the message levels which are always fatal, in any log domain. + When a message with any of these levels is logged the program terminates. You can only set the levels defined by GLib to be fatal. -%G_LOG_LEVEL_ERROR is always fatal. +[flags@GLib.LogLevelFlags.ERROR] is always fatal. You can also make some message levels fatal at runtime by setting the `G_DEBUG` environment variable (see @@ -46515,26 +47931,28 @@ the `G_DEBUG` environment variable (see Libraries should not call this function, as it affects all messages logged by a process, including those from other libraries. -Structured log messages (using g_log_structured() and -g_log_structured_array()) are fatal only if the default log writer is used; +Structured log messages (using [func@GLib.log_structured] and +[func@GLib.log_structured_array]) are fatal only if the default log writer is used; otherwise it is up to the writer function to determine which log messages -are fatal. See [Using Structured Logging][using-structured-logging]. +are fatal. See [Using Structured Logging](logging.html#using-structured-logging). the old fatal mask - the mask containing bits set for each level - of error which is to be fatal + the mask containing bits set for each level of error which is + to be fatal Enable or disable debug output from the GLib logging system for all domains. -This value interacts disjunctively with `G_MESSAGES_DEBUG` — if either of -them would allow a debug message to be outputted, it will be. + +This value interacts disjunctively with `G_MESSAGES_DEBUG` and +[func@GLib.log_writer_default_set_debug_domains] — if any of them would allow +a debug message to be outputted, it will be. Note that this should not be used from within library code to enable debug output — it is intended for external use. @@ -46543,7 +47961,7 @@ output — it is intended for external use. - %TRUE to enable debug output, %FALSE otherwise + `TRUE` to enable debug output, `FALSE` otherwise @@ -46551,11 +47969,12 @@ output — it is intended for external use. Installs a default log handler which is used if no log handler has been set for the particular log domain -and log level combination. By default, GLib uses -g_log_default_handler() as default log handler. +and log level combination. + +By default, GLib uses [func@GLib.log_default_handler] as default log handler. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). the previous default log handler @@ -46573,18 +47992,19 @@ This has no effect if structured logging is enabled; see Sets the log levels which are fatal in the given domain. -%G_LOG_LEVEL_ERROR is always fatal. -This has no effect on structured log messages (using g_log_structured() or -g_log_structured_array()). To change the fatal behaviour for specific log +[flags@GLib.LogLevelFlags.ERROR] is always fatal. + +This has no effect on structured log messages (using [func@GLib.log_structured] or +[func@GLib.log_structured_array]). To change the fatal behaviour for specific log messages, programs must install a custom log writer function using -g_log_set_writer_func(). See -[Using Structured Logging][using-structured-logging]. +[func@GLib.log_set_writer_func]. See +[Using Structured Logging](logging.html#using-structured-logging). This function is mostly intended to be used with -%G_LOG_LEVEL_CRITICAL. You should typically not set -%G_LOG_LEVEL_WARNING, %G_LOG_LEVEL_MESSAGE, %G_LOG_LEVEL_INFO or -%G_LOG_LEVEL_DEBUG as fatal except inside of test programs. +[flags@GLib.LogLevelFlags.CRITICAL]. You should typically not set +[flags@GLib.LogLevelFlags.WARNING], [flags@GLib.LogLevelFlags.MESSAGE], [flags@GLib.LogLevelFlags.INFO] or +[flags@GLib.LogLevelFlags.DEBUG] as fatal except inside of test programs. the old fatal mask for the log domain @@ -46604,52 +48024,52 @@ This function is mostly intended to be used with Sets the log handler for a domain and a set of log levels. To handle fatal and recursive messages the @log_levels parameter -must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION +must be combined with the [flags@GLib.LogLevelFlags.FATAL] and [flags@GLib.LogLevelFlags.RECURSION] bit flags. -Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if +Note that since the [flags@GLib.LogLevelFlags.ERROR] log level is always fatal, if you want to set a handler for this log level you must combine it with -%G_LOG_FLAG_FATAL. +[flags@GLib.LogLevelFlags.FATAL]. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). Here is an example for adding a log handler for all warning messages in the default domain: -|[<!-- language="C" --> +```c g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| +``` This example adds a log handler for all critical messages from GTK: -|[<!-- language="C" --> +```c g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| +``` This example adds a log handler for all messages from GLib: -|[<!-- language="C" --> +```c g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); -]| +``` the id of the new handler - the log domain, or %NULL for the default "" + the log domain, or `NULL` for the default `""` application domain the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine - the log levels with the %G_LOG_FLAG_FATAL and - %G_LOG_FLAG_RECURSION bit flags. + the log levels with the [flags@GLib.LogLevelFlags.FATAL] and + [flags@GLib.LogLevelFlags.RECURSION] bit flags. @@ -46663,25 +48083,25 @@ g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL - Like g_log_set_handler(), but takes a destroy notify for the @user_data. + Like [func@GLib.log_set_handler], but takes a destroy notify for the @user_data. This has no effect if structured logging is enabled; see -[Using Structured Logging][using-structured-logging]. +[Using Structured Logging](logging.html#using-structured-logging). - the id of the new handler + the ID of the new handler - the log domain, or %NULL for the default "" + the log domain, or `NULL` for the default `""` application domain the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine - the log levels with the %G_LOG_FLAG_FATAL and - %G_LOG_FLAG_RECURSION bit flags. + the log levels with the [flags@GLib.LogLevelFlags.FATAL] and + [flags@GLib.LogLevelFlags.RECURSION] bit flags. @@ -46693,15 +48113,17 @@ This has no effect if structured logging is enabled; see - destroy notify for @user_data, or %NULL + destroy notify for @user_data, or `NULL` Set a writer function which will be called to format and write out each log -message. Each program should set a writer function, or the default writer -(g_log_writer_default()) will be used. +message. + +Each program should set a writer function, or the default writer +([func@GLib.log_writer_default]) will be used. Libraries **must not** call this function — only programs are allowed to install a writer function, as there must be a single, central point where @@ -46713,7 +48135,7 @@ There can only be one writer function. It is an error to set more than one. - log writer function, which must not be %NULL + log writer function, which must not be `NULL` @@ -46722,7 +48144,7 @@ There can only be one writer function. It is an error to set more than one. function to free @user_data once it’s - finished with, if non-%NULL + finished with, if non-`NULL` @@ -46731,17 +48153,17 @@ There can only be one writer function. It is an error to set more than one.Log a message with structured data. The message will be passed through to the log writer set by the application -using g_log_set_writer_func(). If the message is fatal (i.e. its log level -is %G_LOG_LEVEL_ERROR), the program will be aborted by calling -G_BREAKPOINT() at the end of this function. If the log writer returns -%G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. -See the documentation for #GLogWriterFunc for information on chaining +using [func@GLib.log_set_writer_func]. If the message is fatal (i.e. its log level +is [flags@GLib.LogLevelFlags.ERROR]), the program will be aborted by calling +[func@GLib.BREAKPOINT] at the end of this function. If the log writer returns +[enum@GLib.LogWriterOutput.UNHANDLED] (failure), no other fallback writers will be tried. +See the documentation for [type@GLib.LogWriterFunc] for information on chaining writers. The structured data is provided as key–value pairs, where keys are UTF-8 strings, and values are arbitrary pointers — typically pointing to UTF-8 strings, but that is not a requirement. To pass binary (non-nul-terminated) -structured data, use g_log_structured_array(). The keys for structured data +structured data, use [func@GLib.log_structured_array]. The keys for structured data should follow the [systemd journal fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) specification. It is suggested that custom keys are namespaced according to @@ -46749,10 +48171,10 @@ the code which sets them. For example, custom keys from GLib all have a `GLIB_` prefix. Note that keys that expect UTF-8 strings (specifically `"MESSAGE"` and -`"GLIB_DOMAIN"`) must be passed as NUL-terminated UTF-8 strings until GLib +`"GLIB_DOMAIN"`) must be passed as nul-terminated UTF-8 strings until GLib version 2.74.1 because the default log handler did not consider the length of the `GLogField`. Starting with GLib 2.74.1 this is fixed and -non-NUL-terminated UTF-8 strings can be passed with their correct length. +non-nul-terminated UTF-8 strings can be passed with their correct length. The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will be converted into a @@ -46771,19 +48193,19 @@ Other fields you may commonly want to pass into this function: * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=) Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by -the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), -g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including +the logging macros, [func@GLib.DEBUG_HERE], [func@GLib.message], [func@GLib.warning], [func@GLib.critical], +[func@GLib.error], etc, if the symbol `G_LOG_USE_STRUCTURED` is defined before including `glib.h`. For example: -|[<!-- language="C" --> +```c g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", "MY_APPLICATION_CUSTOM_FIELD", "some debug string", "MESSAGE", "This is a debug message about pointer %p and integer %u.", some_pointer, some_integer); -]| +``` Note that each `MESSAGE_ID` must be [uniquely and randomly generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=). @@ -46792,13 +48214,13 @@ catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with your software. To pass a user data pointer to the log writer function which is specific to -this logging call, you must use g_log_structured_array() and pass the pointer -as a field with #GLogField.length set to zero, otherwise it will be +this logging call, you must use [func@GLib.log_structured_array] and pass the pointer +as a field with `GLogField.length` set to zero, otherwise it will be interpreted as a string. For example: -|[<!-- language="C" --> +```c const GLogField fields[] = { { "MESSAGE", "This is a debug message.", -1 }, { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 }, @@ -46806,12 +48228,12 @@ const GLogField fields[] = { { "MY_APPLICATION_STATE", state_object, 0 }, }; g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields)); -]| +``` Note also that, even if no other structured fields are specified, there must always be a `MESSAGE` key before the format string. The `MESSAGE`-format pair has to be the last of the key-value pairs, and `MESSAGE` is the only -field for which printf()-style formatting is supported. +field for which `printf()`-style formatting is supported. The default writer function for `stdout` and `stderr` will automatically append a new-line character after the message, so you should not add one @@ -46821,29 +48243,31 @@ manually to the format string. - log domain, usually %G_LOG_DOMAIN + log domain, usually `G_LOG_DOMAIN` - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level key-value pairs of structured data to add to the log entry, followed - by the key "MESSAGE", followed by a printf()-style message format, + by the key `MESSAGE`, followed by a `printf()`-style message format, followed by parameters to insert in the format string - Log a message with structured data. The message will be passed through to the -log writer set by the application using g_log_set_writer_func(). If the -message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will + Log a message with structured data. + +The message will be passed through to the log writer set by the application +using [func@GLib.log_set_writer_func]. If the +message is fatal (i.e. its log level is [flags@GLib.LogLevelFlags.ERROR]), the program will be aborted at the end of this function. -See g_log_structured() for more documentation. +See [func@GLib.log_structured] for more documentation. This assumes that @log_level is already present in @fields (typically as the `PRIORITY` field). @@ -46852,7 +48276,7 @@ This assumes that @log_level is already present in @fields (typically as the - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -46898,35 +48322,36 @@ This assumes that @log_level is already present in @fields (typically as the - Log a message with structured data, accepting the data within a #GVariant. This -version is especially useful for use in other languages, via introspection. + Log a message with structured data, accepting the data within a [type@GLib.Variant]. + +This version is especially useful for use in other languages, via introspection. -The only mandatory item in the @fields dictionary is the "MESSAGE" which must +The only mandatory item in the @fields dictionary is the `"MESSAGE"` which must contain the text shown to the user. -The values in the @fields dictionary are likely to be of type String -(%G_VARIANT_TYPE_STRING). Array of bytes (%G_VARIANT_TYPE_BYTESTRING) is also +The values in the @fields dictionary are likely to be of type `G_VARIANT_TYPE_STRING`. +Array of bytes (`G_VARIANT_TYPE_BYTESTRING`) is also supported. In this case the message is handled as binary and will be forwarded to the log writer as such. The size of the array should not be higher than -%G_MAXSSIZE. Otherwise it will be truncated to this size. For other types -g_variant_print() will be used to convert the value into a string. +`G_MAXSSIZE`. Otherwise it will be truncated to this size. For other types +[method@GLib.Variant.print] will be used to convert the value into a string. -For more details on its usage and about the parameters, see g_log_structured(). +For more details on its usage and about the parameters, see [func@GLib.log_structured]. - log domain, usually %G_LOG_DOMAIN + log domain, usually `G_LOG_DOMAIN` - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level - a dictionary (#GVariant of the type %G_VARIANT_TYPE_VARDICT) + a dictionary ([type@GLib.Variant] of the type `G_VARIANT_TYPE_VARDICT`) containing the key-value pairs of message data. @@ -46934,7 +48359,9 @@ containing the key-value pairs of message data. Format a structured log message and output it to the default log destination -for the platform. On Linux, this is typically the systemd journal, falling +for the platform. + +On Linux, this is typically the systemd journal, falling back to `stdout` or `stderr` if running from the terminal or if output is being redirected to a file. @@ -46942,23 +48369,24 @@ Support for other platform-specific logging mechanisms may be added in future. Distributors of GLib may modify this function to impose their own (documented) platform-specific log writing policies. -This is suitable for use as a #GLogWriterFunc, and is the default writer used -if no other is set using g_log_set_writer_func(). +This is suitable for use as a [type@GLib.LogWriterFunc], and is the default writer used +if no other is set using [func@GLib.log_set_writer_func]. -As with g_log_default_handler(), this function drops debug and informational +As with [func@GLib.log_default_handler], this function drops debug and informational messages unless their log domain (or `all`) is listed in the space-separated -`G_MESSAGES_DEBUG` environment variable. +`G_MESSAGES_DEBUG` environment variable, or set at runtime by [func@GLib.log_writer_default_set_debug_domains]. -g_log_writer_default() uses the mask set by g_log_set_always_fatal() to -determine which messages are fatal. When using a custom writer func instead it is +[func@GLib.log_writer_default] uses the mask set by [func@GLib.log_set_always_fatal] to +determine which messages are fatal. When using a custom writer function instead it is up to the writer function to determine which log messages are fatal. - %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + [enum@GLib.LogWriterOutput.HANDLED] on success, + [enum@GLib.LogWriterOutput.UNHANDLED] otherwise - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -46974,19 +48402,37 @@ up to the writer function to determine which log messages are fatal. - user data passed to g_log_set_writer_func() + user data passed to [func@GLib.log_set_writer_func] + + Reset the list of domains to be logged, that might be initially set by the +`G_MESSAGES_DEBUG` environment variable. + +This function is thread-safe. + + + + + + `NULL`-terminated array with domains to be printed. + `NULL` or an array with no values means none. Array with a single value `"all"` means all. + + + + - Configure whether the built-in log functions -(g_log_default_handler() for the old-style API, and both -g_log_writer_default() and g_log_writer_standard_streams() for the -structured API) will output all log messages to `stderr`. + Configure whether the built-in log functions will output all log messages to +`stderr`. + +The built-in log functions are [func@GLib.log_default_handler] for the +old-style API, and both [func@GLib.log_writer_default] and +[func@GLib.log_writer_standard_streams] for the structured API. -By default, log messages of levels %G_LOG_LEVEL_INFO and -%G_LOG_LEVEL_DEBUG are sent to `stdout`, and other log messages are +By default, log messages of levels [flags@GLib.LogLevelFlags.INFO] and +[flags@GLib.LogLevelFlags.DEBUG] are sent to `stdout`, and other log messages are sent to `stderr`. This is problematic for applications that intend to reserve `stdout` for structured output such as JSON or XML. @@ -46998,48 +48444,47 @@ or creating objects that could create worker threads of their own. - If %TRUE, use `stderr` for log messages that would + If `TRUE`, use `stderr` for log messages that would normally have appeared on `stdout` - Check whether g_log_writer_default() and g_log_default_handler() would + Check whether [func@GLib.log_writer_default] and [func@GLib.log_default_handler] would ignore a message with the given domain and level. -As with g_log_default_handler(), this function drops debug and informational +As with [func@GLib.log_default_handler], this function drops debug and informational messages unless their log domain (or `all`) is listed in the space-separated -`G_MESSAGES_DEBUG` environment variable. +`G_MESSAGES_DEBUG` environment variable, or by [func@GLib.log_writer_default_set_debug_domains]. This can be used when implementing log writers with the same filtering behaviour as the default, but a different destination or output format: -|[<!-- language="C" --> - if (g_log_writer_default_would_drop (log_level, log_domain)) - return G_LOG_WRITER_HANDLED; +```c +if (g_log_writer_default_would_drop (log_level, log_domain)) + return G_LOG_WRITER_HANDLED; ]| or to skip an expensive computation if it is only needed for a debugging message, and `G_MESSAGES_DEBUG` is not set: -|[<!-- language="C" --> - if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) - { - gchar *result = expensive_computation (my_object); +```c +if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) + { + g_autofree gchar *result = expensive_computation (my_object); - g_debug ("my_object result: %s", result); - g_free (result); - } -]| + g_debug ("my_object result: %s", result); + } +``` - %TRUE if the log message would be dropped by GLib's - default log handlers + `TRUE` if the log message would be dropped by GLib’s + default log handlers - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -47051,9 +48496,11 @@ message, and `G_MESSAGES_DEBUG` is not set: Format a structured log message as a string suitable for outputting to the -terminal (or elsewhere). This will include the values of all fields it knows +terminal (or elsewhere). + +This will include the values of all fields it knows how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the -documentation for g_log_structured()). It does not include values from +documentation for [func@GLib.log_structured]). It does not include values from unknown fields. The returned string does **not** have a trailing new-line character. It is @@ -47066,7 +48513,7 @@ UTF-8. - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -47082,8 +48529,9 @@ UTF-8. - %TRUE to use ANSI color escape sequences when formatting the - message, %FALSE to not + `TRUE` to use + [ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code) + when formatting the message, `FALSE` to not @@ -47093,13 +48541,13 @@ UTF-8. systemd journal, or something else (like a log file or `stdout` or `stderr`). -Invalid file descriptors are accepted and return %FALSE, which allows for +Invalid file descriptors are accepted and return `FALSE`, which allows for the following construct without needing any additional error handling: -|[<!-- language="C" --> - is_journald = g_log_writer_is_journald (fileno (stderr)); -]| +```c +is_journald = g_log_writer_is_journald (fileno (stderr)); +``` - %TRUE if @output_fd points to the journal, %FALSE otherwise + `TRUE` if @output_fd points to the journal, `FALSE` otherwise @@ -47111,21 +48559,23 @@ the following construct without needing any additional error handling: Format a structured log message and send it to the systemd journal as a set -of key–value pairs. All fields are sent to the journal, but if a field has +of key–value pairs. + +All fields are sent to the journal, but if a field has length zero (indicating program-specific data) then only its key will be sent. -This is suitable for use as a #GLogWriterFunc. +This is suitable for use as a [type@GLib.LogWriterFunc]. If GLib has been compiled without systemd support, this function is still -defined, but will always return %G_LOG_WRITER_UNHANDLED. +defined, but will always return [enum@GLib.LogWriterOutput.UNHANDLED]. - %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -47141,33 +48591,37 @@ defined, but will always return %G_LOG_WRITER_UNHANDLED. - user data passed to g_log_set_writer_func() + user data passed to [func@GLib.log_set_writer_func] Format a structured log message and print it to either `stdout` or `stderr`, -depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages +depending on its log level. + +[flags@GLib.LogLevelFlags.INFO] and [flags@GLib.LogLevelFlags.DEBUG] messages are sent to `stdout`, or to `stderr` if requested by -g_log_writer_default_set_use_stderr(); +[func@GLib.log_writer_default_set_use_stderr]; all other log levels are sent to `stderr`. Only fields which are understood by this function are included in the formatted string which is printed. -If the output stream supports ANSI color escape sequences, they will be used -in the output. +If the output stream supports +[ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code), +they will be used in the output. A trailing new-line character is added to the log message when it is printed. -This is suitable for use as a #GLogWriterFunc. +This is suitable for use as a [type@GLib.LogWriterFunc]. - %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise + [enum@GLib.LogWriterOutput.HANDLED] on success, + [enum@GLib.LogWriterOutput.UNHANDLED] otherwise - log level, either from #GLogLevelFlags, or a user-defined + log level, either from [type@GLib.LogLevelFlags], or a user-defined level @@ -47183,17 +48637,18 @@ This is suitable for use as a #GLogWriterFunc. - user data passed to g_log_set_writer_func() + user data passed to [func@GLib.log_set_writer_func] - Check whether the given @output_fd file descriptor supports ANSI color -escape sequences. If so, they can safely be used when formatting log -messages. + Check whether the given @output_fd file descriptor supports +[ANSI color escape sequences](https://en.wikipedia.org/wiki/ANSI_escape_code). + +If so, they can safely be used when formatting log messages. - %TRUE if ANSI color escapes are supported, %FALSE otherwise + `TRUE` if ANSI color escapes are supported, `FALSE` otherwise @@ -47203,26 +48658,66 @@ messages. + + Format a structured log message and send it to the syslog daemon. Only fields +which are understood by this function are included in the formatted string +which is printed. + +Log facility will be defined via the SYSLOG_FACILITY field and accepts the following +values: "auth", "daemon", and "user". If SYSLOG_FACILITY is not specified, LOG_USER +facility will be used. + +This is suitable for use as a [type@GLib.LogWriterFunc]. + +If syslog is not supported, this function is still defined, but will always +return [enum@GLib.LogWriterOutput.UNHANDLED]. + + [enum@GLib.LogWriterOutput.HANDLED] on success, [enum@GLib.LogWriterOutput.UNHANDLED] otherwise + + + + + log level, either from [type@GLib.LogLevelFlags], or a user-defined + level + + + + key–value pairs of structured data forming + the log message + + + + + + number of elements in the @fields array + + + + user data passed to [func@GLib.log_set_writer_func] + + + + Logs an error or debugging message. -If the log level has been set as fatal, G_BREAKPOINT() is called -to terminate the program. See the documentation for G_BREAKPOINT() for +If the log level has been set as fatal, [func@GLib.BREAKPOINT] is called +to terminate the program. See the documentation for [func@GLib.BREAKPOINT] for details of the debugging options this provides. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If [structured logging is enabled][using-structured-logging] this will -output via the structured log writer function (see g_log_set_writer_func()). +If [structured logging is enabled](logging.html#using-structured-logging) this will +output via the structured log writer function (see [func@GLib.log_set_writer_func]). - the log domain, or %NULL for the default "" -application domain + the log domain, or `NULL` for the default `""` + application domain @@ -47230,7 +48725,7 @@ application domain - the message format. See the printf() documentation + the message format. See the `printf()` documentation @@ -47239,6 +48734,32 @@ application domain + + A wrapper for the POSIX lstat() function. The lstat() function is +like stat() except that in the case of symbolic links, it returns +information about the symbolic link itself and not the file that it +refers to. If the system does not support symbolic links g_lstat() +is identical to g_stat(). + +See your C library manual for more details about lstat(). + + 0 if the information was successfully retrieved, + -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pointer to a stat struct, which will be filled with the file + information + + + + @@ -47266,136 +48787,6 @@ application domain - - These macros provide a few commonly-used features. - - - These macros provide more specialized features which are not -needed so often by application programmers. - - - The main event loop manages all the available sources of events for -GLib and GTK applications. These events can come from any number of -different types of sources such as file descriptors (plain files, -pipes or sockets) and timeouts. New types of event sources can also -be added using g_source_attach(). - -To allow multiple independent sets of sources to be handled in -different threads, each source is associated with a #GMainContext. -A #GMainContext can only be running in a single thread, but -sources can be added to it and removed from it from other threads. All -functions which operate on a #GMainContext or a built-in #GSource are -thread-safe. - -Each event source is assigned a priority. The default priority, -%G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. -Values greater than 0 denote lower priorities. Events from high priority -sources are always processed before events from lower priority sources: if -several sources are ready to dispatch, the ones with equal-highest priority -will be dispatched on the current #GMainContext iteration, and the rest wait -until a subsequent #GMainContext iteration when they have the highest -priority of the sources which are ready for dispatch. - -Idle functions can also be added, and assigned a priority. These will -be run whenever no events with a higher priority are ready to be dispatched. - -The #GMainLoop data type represents a main event loop. A GMainLoop is -created with g_main_loop_new(). After adding the initial event sources, -g_main_loop_run() is called. This continuously checks for new events from -each of the event sources and dispatches them. Finally, the processing of -an event from one of the sources leads to a call to g_main_loop_quit() to -exit the main loop, and g_main_loop_run() returns. - -It is possible to create new instances of #GMainLoop recursively. -This is often used in GTK applications when showing modal dialog -boxes. Note that event sources are associated with a particular -#GMainContext, and will be checked and dispatched for all main -loops associated with that GMainContext. - -GTK contains wrappers of some of these functions, e.g. gtk_main(), -gtk_main_quit() and gtk_events_pending(). - -## Creating new source types - -One of the unusual features of the #GMainLoop functionality -is that new types of event source can be created and used in -addition to the builtin type of event source. A new event source -type is used for handling GDK events. A new source type is created -by "deriving" from the #GSource structure. The derived type of -source is represented by a structure that has the #GSource structure -as a first element, and other elements specific to the new source -type. To create an instance of the new source type, call -g_source_new() passing in the size of the derived structure and -a table of functions. These #GSourceFuncs determine the behavior of -the new source type. - -New source types basically interact with the main context -in two ways. Their prepare function in #GSourceFuncs can set a timeout -to determine the maximum amount of time that the main loop will sleep -before checking the source again. In addition, or as well, the source -can add file descriptors to the set that the main context checks using -g_source_add_poll(). - -## Customizing the main loop iteration - -Single iterations of a #GMainContext can be run with -g_main_context_iteration(). In some cases, more detailed control -of exactly how the details of the main loop work is desired, for -instance, when integrating the #GMainLoop with an external main loop. -In such cases, you can call the component functions of -g_main_context_iteration() directly. These functions are -g_main_context_prepare(), g_main_context_query(), -g_main_context_check() and g_main_context_dispatch(). - -If the event loop thread releases #GMainContext ownership until the results -required by g_main_context_check() are ready you must create a context with -the flag %G_MAIN_CONTEXT_FLAGS_OWNERLESS_POLLING or else you'll lose -g_source_attach() notifications. This happens for instance when you integrate -the GLib event loop into implementations that follow the proactor pattern -(i.e. in these contexts the `poll()` implementation will reclaim the thread for -other tasks until the results are ready). One example of the proactor pattern -is the Boost.Asio library. - -## State of a Main Context # {#mainloop-states} - -The operation of these functions can best be seen in terms -of a state diagram, as shown in this image. - -![](mainloop-states.gif) - -On UNIX, the GLib mainloop is incompatible with fork(). Any program -using the mainloop must either exec() or exit() from the child -without returning to the mainloop. - -## Memory management of sources # {#mainloop-memory-management} - -There are two options for memory management of the user data passed to a -#GSource to be passed to its callback on invocation. This data is provided -in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and -more generally, using g_source_set_callback(). This data is typically an -object which ‘owns’ the timeout or idle callback, such as a widget or a -network protocol implementation. In many cases, it is an error for the -callback to be invoked after this owning object has been destroyed, as that -results in use of freed memory. - -The first, and preferred, option is to store the source ID returned by -functions such as g_timeout_add() or g_source_attach(), and explicitly -remove that source from the main context using g_source_remove() when the -owning object is finalized. This ensures that the callback can only be -invoked while the object is still alive. - -The second option is to hold a strong reference to the object in the -callback, and to release it in the callback’s #GDestroyNotify. This ensures -that the object is kept alive until after the source is finalized, which is -guaranteed to be after it is invoked for the final time. The #GDestroyNotify -is another callback passed to the ‘full’ variants of #GSource functions (for -example, g_timeout_add_full()). It is called when the source is finalized, -and is designed for releasing references like this. - -One important caveat of this second approach is that it will keep the object -alive indefinitely if the main loop is stopped before the #GSource is -invoked, which may be undesirable. - Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly @@ -47551,6 +48942,81 @@ following techniques: + + Frees the memory allocated for the #GMainLoop. + Use g_main_loop_unref() instead + + + a #GMainLoop + + + + + Checks if the main loop is running. + Use g_main_loop_is_running() instead + + + a #GMainLoop + + + + + Runs a single iteration for the default #GMainContext. + Use g_main_context_iteration() instead. + + + set to %TRUE if it should block (i.e. wait) until an event + source becomes ready. It will return after an event source has been + processed. If set to %FALSE it will return immediately if no event + source is ready to be processed. + + + + + Creates a new #GMainLoop for th default main context. + Use g_main_loop_new() instead + + + set to %TRUE to indicate that the loop is running. This + is not very important since calling g_main_run() will set this + to %TRUE anyway. + + + + + Checks if any events are pending for the default #GMainContext +(i.e. ready to be processed). + Use g_main_context_pending() instead. + + + Stops the #GMainLoop. +If g_main_run() was called to run the #GMainLoop, it will now return. + Use g_main_loop_quit() instead + + + a #GMainLoop + + + + + Runs a main loop until it stops running. + Use g_main_loop_run() instead + + + a #GMainLoop + + + + + Sets the function to use for the handle polling of file descriptors +for the default main context. + Use g_main_context_set_poll_func() again + + + the function to call to poll all file descriptors + + + Allocates @n_bytes bytes of memory. If @n_bytes is 0 it returns %NULL. @@ -47627,54 +49093,6 @@ the program is terminated. - - The "GMarkup" parser is intended to parse a simple markup format -that's a subset of XML. This is a small, efficient, easy-to-use -parser. It should not be used if you expect to interoperate with -other applications generating full-scale XML, and must not be used if you -expect to parse untrusted input. However, it's very -useful for application data files, config files, etc. where you -know your application will be the only one writing the file. -Full-scale XML parsers should be able to parse the subset used by -GMarkup, so you can easily migrate to full-scale XML at a later -time if the need arises. - -GMarkup is not guaranteed to signal an error on all invalid XML; -the parser may accept documents that an XML parser would not. -However, XML documents which are not well-formed (which is a -weaker condition than being valid. See the -[XML specification](http://www.w3.org/TR/REC-xml/) -for definitions of these terms.) are not considered valid GMarkup -documents. - -Simplifications to XML include: - -- Only UTF-8 encoding is allowed - -- No user-defined entities - -- Processing instructions, comments and the doctype declaration - are "passed through" but are not interpreted in any way - -- No DTD or validation - -The markup format does support: - -- Elements - -- Attributes - -- 5 standard entities: &amp; &lt; &gt; &quot; &apos; - -- Character references - -- Sections marked as CDATA - -## An example parser # {#example} - -Here is an example for a markup parser: -[markup-example.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/markup-example.c) - Collects the attributes of the element from the data passed to the #GMarkupParser start_element function, dealing with common error @@ -47835,6 +49253,21 @@ of g_markup_escape_text(). See g_markup_printf_escaped(). + + + + + + + + + + + + + + + Checks whether the allocator used by g_malloc() is the system's malloc implementation. If it returns %TRUE memory allocated with @@ -47934,240 +49367,46 @@ The source and destination areas may overlap. - - These functions provide support for allocating and freeing memory. - -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, the `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. - -As all GLib functions and data structures use `g_malloc()` internally, unless -otherwise specified, any allocation failure will result in the application -being terminated. - -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 -g_slice_free(), plain malloc() with free(), and (if you're using C++) -new with delete and new[] with delete[]. Otherwise bad things can happen, -since these allocators may use different memory pools (and new/delete call -constructors and destructors). - -Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc -implementation. - - - GSlice was a space-efficient and multi-processing scalable way to allocate -equal sized pieces of memory. Since GLib 2.76, its implementation has been -removed and it calls g_malloc() and g_free_sized(), because the performance -of the system-default allocators has improved on all platforms since GSlice -was written. - -The GSlice APIs have not been deprecated, as they are widely in use and doing -so would be very disruptive for little benefit. - -New code should be written using g_new()/g_malloc() and g_free_sized() or -g_free(). There is no particular benefit in porting existing code away from -g_slice_new()/g_slice_free() unless it’s being rewritten anyway. - -Here is an example for using the slice allocator: -|[<!-- language="C" --> -gchar *mem[10000]; -gint i; - -// Allocate 10000 blocks. -for (i = 0; i < 10000; i++) - { - mem[i] = g_slice_alloc (50); - - // Fill in the memory with some junk. - for (j = 0; j < 50; j++) - mem[i][j] = i * j; - } - -// Now free all of the blocks. -for (i = 0; i < 10000; i++) - g_slice_free1 (50, mem[i]); -]| - -And here is an example for using the using the slice allocator -with data structures: -|[<!-- language="C" --> -GRealArray *array; - -// Allocate one block, using the g_slice_new() macro. -array = g_slice_new (GRealArray); - -// We can now use array just like a normal pointer to a structure. -array->data = NULL; -array->len = 0; -array->alloc = 0; -array->zero_terminated = (zero_terminated ? 1 : 0); -array->clear = (clear ? 1 : 0); -array->elt_size = elt_size; - -// We can free the block, so it can be reused. -g_slice_free (GRealArray, array); -]| - A convenience function/macro to log a normal message. -If g_log_default_handler() is used as the log handler function, a new-line +If [func@GLib.log_default_handler] is used as the log handler function, a new-line character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). - format string, followed by parameters to insert - into the format string (as with printf()) + format string, followed by parameters to insert into the format string + (as with `printf()`) - - These functions provide support for outputting messages. - -The g_return family of macros (g_return_if_fail(), -g_return_val_if_fail(), g_return_if_reached(), -g_return_val_if_reached()) should only be used for programming -errors, a typical use case is checking for invalid parameters at -the beginning of a public function. They should not be used if -you just mean "if (error) return", they should only be used if -you mean "if (bug in program) return". The program behavior is -generally considered undefined after one of these checks fails. -They are not intended for normal control flow, only to give a -perhaps-helpful warning before giving up. - -Structured logging output is supported using g_log_structured(). This differs -from the traditional g_log() API in that log messages are handled as a -collection of key–value pairs representing individual pieces of information, -rather than as a single string containing all the information in an arbitrary -format. - -The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() -will use the traditional g_log() API unless you define the symbol -%G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages -logged through the traditional g_log() API are ultimatively passed to -g_log_structured(), so that all log messages end up in same destination. -If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become -ineffective for the wrapper macros g_warning() and friends (see -[Testing for Messages][testing-for-messages]). - -The support for structured logging was motivated by the following needs (some -of which were supported previously; others weren’t): - * Support for multiple logging levels. - * Structured log support with the ability to add `MESSAGE_ID`s (see - g_log_structured()). - * Moving the responsibility for filtering log messages from the program to - the log viewer — instead of libraries and programs installing log handlers - (with g_log_set_handler()) which filter messages before output, all log - messages are outputted, and the log viewer program (such as `journalctl`) - must filter them. This is based on the idea that bugs are sometimes hard - to reproduce, so it is better to log everything possible and then use - tools to analyse the logs than it is to not be able to reproduce a bug to - get additional log data. Code which uses logging in performance-critical - sections should compile out the g_log_structured() calls in - release builds, and compile them in in debugging builds. - * A single writer function which handles all log messages in a process, from - all libraries and program code; rather than multiple log handlers with - poorly defined interactions between them. This allows a program to easily - change its logging policy by changing the writer function, for example to - log to an additional location or to change what logging output fallbacks - are used. The log writer functions provided by GLib are exposed publicly - so they can be used from programs’ log writers. This allows log writer - policy and implementation to be kept separate. - * If a library wants to add standard information to all of its log messages - (such as library state) or to redact private data (such as passwords or - network credentials), it should use a wrapper function around its - g_log_structured() calls or implement that in the single log writer - function. - * If a program wants to pass context data from a g_log_structured() call to - its log writer function so that, for example, it can use the correct - server connection to submit logs to, that user data can be passed as a - zero-length #GLogField to g_log_structured_array(). - * Color output needed to be supported on the terminal, to make reading - through logs easier. - -## Using Structured Logging ## {#using-structured-logging} - -To use structured logging (rather than the old-style logging), either use -the g_log_structured() and g_log_structured_array() functions; or define -`G_LOG_USE_STRUCTURED` before including any GLib header, and use the -g_message(), g_debug(), g_error() (etc.) macros. - -You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), -but it is a good idea to avoid confusion. - -## Log Domains ## {#log-domains} - -Log domains may be used to broadly split up the origins of log messages. -Typically, there are one or a few log domains per application or library. -%G_LOG_DOMAIN should be used to define the default log domain for the current -compilation unit — it is typically defined at the top of a source file, or in -the preprocessor flags for a group of source files. + + A wrapper for the POSIX mkdir() function. The mkdir() function +attempts to create a directory with the given name and permissions. +The mode argument is ignored on Windows. -Log domains must be unique, and it is recommended that they are the -application or library name, optionally followed by a hyphen and a sub-domain -name. For example, `bloatpad` or `bloatpad-io`. - -## Debug Message Output ## {#debug-message-output} - -The default log functions (g_log_default_handler() for the old-style API and -g_log_writer_default() for the structured API) both drop debug and -informational messages by default, unless the log domains of those messages -are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to -`all`). - -It is recommended that custom log writer functions re-use the -`G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, -so that developers can re-use the same debugging techniques and tools across -projects. Since GLib 2.68, this can be implemented by dropping messages -for which g_log_writer_default_would_drop() returns %TRUE. - -## Testing for Messages ## {#testing-for-messages} - -With the old g_log() API, g_test_expect_message() and -g_test_assert_expected_messages() could be used in simple cases to check -whether some code under test had emitted a given log message. These -functions have been deprecated with the structured logging API, for several -reasons: - * They relied on an internal queue which was too inflexible for many use - cases, where messages might be emitted in several orders, some - messages might not be emitted deterministically, or messages might be - emitted by unrelated log domains. - * They do not support structured log fields. - * Examining the log output of code is a bad approach to testing it, and - while it might be necessary for legacy code which uses g_log(), it should - be avoided for new code using g_log_structured(). - -They will continue to work as before if g_log() is in use (and -%G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the -structured logging API. - -Examining the log output of code is discouraged: libraries should not emit to -`stderr` during defined behaviour, and hence this should not be tested. If -the log emissions of a library during undefined behaviour need to be tested, -they should be limited to asserting that the library aborts and prints a -suitable error message before aborting. This should be done with -g_test_trap_assert_stderr(). - -If it is really necessary to test the structured log messages emitted by a -particular piece of code – and the code cannot be restructured to be more -suitable to more conventional unit testing – you should write a custom log -writer function (see g_log_set_writer_func()) which appends all log messages -to a queue. When you want to check the log messages, examine and clear the -queue, ignoring irrelevant log messages (for example, from log domains other -than the one under test). - - - These are portable utility functions. - +See your C library manual for more details about mkdir(). + + 0 if the directory was successfully created, -1 if an error + occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + permissions to use for the newly created directory + + + + Create a directory if it doesn't already exist. Create intermediate parent directories as needed, too. @@ -48310,6 +49549,15 @@ on Windows it should be in UTF-8. + + Allocates and initializes a new #GMutex. + GMutex can now be statically allocated, or embedded +in structures and initialised with g_mutex_init(). + + a newly allocated #GMutex. Use g_mutex_free() to free + + + Allocates @n_structs elements of type @struct_type. The returned pointer is cast to a pointer to the given type. @@ -48455,6 +49703,11 @@ vulnerability. + + + + + Inserts a new #GNode as the first child of the given parent. @@ -48474,19 +49727,25 @@ vulnerability. + + + + + + + + + + - Converts a 32-bit integer value from network to host byte order. - a 32-bit integer value in network byte order - Converts a 16-bit integer value from network to host byte order. - a 16-bit integer value in network byte order @@ -48507,18 +49766,6 @@ vulnerability. - - GLib offers mathematical constants such as %G_PI for the value of pi; -many platforms have these in the C library, but some don't, the GLib -versions always exist. - -The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the -sign, mantissa and exponent of IEEE floats and doubles. These unions are -defined as appropriate for a given platform. IEEE floats and doubles are -supported (used for storage) by at least Intel, PPC and Sparc. See -[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) -for more information about IEEE number formats. - Prompts the user with `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. @@ -48675,13 +49922,52 @@ the pointer passed to it should not be `volatile`. - + location of a static initializable variable containing 0 + + + + + + + + + + + + This functions behaves in the same way as g_once_init_enter(), but can +can be used to initialize pointers (or #guintptr) instead of #gsize. + +|[<!-- language="C" --> + static MyStruct *interesting_struct = NULL; + + if (g_once_init_enter_pointer (&interesting_struct)) + { + MyStruct *setup_value = allocate_my_struct (); // initialization code here + + g_once_init_leave_pointer (&interesting_struct, g_steal_pointer (&setup_value)); + } + + // use interesting_struct here +]| + + %TRUE if the initialization section should be entered, + %FALSE and blocks otherwise + + + + + location of a static initializable variable + containing `NULL` + + + + Counterpart to g_once_init_enter(). Expects a location of a static 0-initialized initialization variable, and an initialization value @@ -48695,7 +49981,7 @@ the pointer passed to it should not be `volatile`. - + location of a static initializable variable containing 0 @@ -48706,6 +49992,71 @@ the pointer passed to it should not be `volatile`. + + Counterpart to g_once_init_enter_pointer(). Expects a location of a static +`NULL`-initialized initialization variable, and an initialization value +other than `NULL`. Sets the variable to the initialization value, and +releases concurrent threads blocking in g_once_init_enter_pointer() on this +initialization variable. + +This functions behaves in the same way as g_once_init_leave(), but +can be used to initialize pointers (or #guintptr) instead of #gsize. + + + + + + location of a static initializable variable + containing `NULL` + + + + new non-`NULL` value for `*location` + + + + + + A wrapper for the POSIX open() function. The open() function is +used to convert a pathname into a file descriptor. + +On POSIX systems file descriptors are implemented by the operating +system. On Windows, it's the C library that implements open() and +file descriptors. The actual Win32 API for opening files is quite +different, see MSDN documentation for CreateFile(). The Win32 API +uses file handles, which are more randomish integers, not small +integers like file descriptors. + +Because file descriptors are specific to the C library on Windows, +the file descriptor returned by this function makes sense only to +functions in the same C library. Thus if the GLib-using code uses a +different C library than GLib does, the file descriptor returned by +this function cannot be passed to C library functions like write() +or read(). + +See your C library manual for more details about open(). + + a new file descriptor, or -1 if an error occurred. + The return value can be used exactly like the return value + from open(). + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + as in open() + + + + as in open() + + + + @@ -48945,22 +50296,6 @@ g_pattern_match() instead while supplying the reversed string. - - The g_pattern_match* functions match a string -against a pattern containing '*' and '?' wildcards with similar -semantics as the standard glob() function: '*' matches an arbitrary, -possibly empty, string, '?' matches an arbitrary character. - -Note that in contrast to glob(), the '/' character can be matched by -the wildcards, there are no '[...]' character ranges and '*' and '?' -can not be escaped to include them literally in a pattern. - -When multiple strings must be matched against the same pattern, it -is better to compile the pattern to a #GPatternSpec using -g_pattern_spec_new() and use g_pattern_match_string() instead of -g_pattern_match_simple(). This avoids the overhead of repeated -pattern compilation. - This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). @@ -48984,6 +50319,70 @@ artifact and the argument passed to it should not be `volatile`. + + This is equivalent to g_bit_lock, but working on pointers (or other +pointer-sized values). + +For portability reasons, you may only lock on the bottom 32 bits of +the pointer. + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + returns the set pointer atomically. + This is the value after setting the lock, it thus always has the + lock bit set, while previously @address had the lockbit unset. + You may also use g_pointer_bit_lock_mask_ptr() to clear the lock bit. + + + + + + This mangles @ptr as g_pointer_bit_lock() and g_pointer_bit_unlock() +do. + + the mangled pointer. + + + + + the pointer to mask + + + + the bit to set/clear. If set to `G_MAXUINT`, the + lockbit is taken from @preserve_ptr or @ptr (depending on @preserve_mask). + + + + whether to set (lock) the bit or unset (unlock). This + has no effect, if @lock_bit is set to `G_MAXUINT`. + + + + if non-zero, a bit-mask for @preserve_ptr. The + @preserve_mask bits from @preserve_ptr are set in the result. + Note that the @lock_bit bit will be always set according to @set, + regardless of @preserve_mask and @preserve_ptr (unless @lock_bit is + `G_MAXUINT`). + + + + if @preserve_mask is non-zero, the bits + from this pointer are set in the result. + + + + This is equivalent to g_bit_trylock(), but working on pointers (or other pointer-sized values). @@ -49031,6 +50430,39 @@ artifact and the argument passed to it should not be `volatile`. + + This is equivalent to g_pointer_bit_unlock() and atomically setting +the pointer value. + +Note that the lock bit will be cleared from the pointer. If the unlocked +pointer that was set is not identical to @ptr, an assertion fails. In other +words, @ptr must have @lock_bit unset. This also means, you usually can +only use this on the lowest bits. + + + + + + a pointer to a #gpointer-sized value + + + + a bit value between 0 and 31 + + + + the new pointer value to set + + + + if non-zero, those bits of the current pointer in @address + are preserved. + Note that the @lock_bit bit will be always set according to @set, + regardless of @preserve_mask and the currently set value in @address. + + + + Polls @fds, as with the poll() system call, but portably. (On systems that don't have poll(), it is emulated using select().) @@ -49102,7 +50534,7 @@ error condition) then also do nothing. - + a return location for a #GError, or %NULL @@ -49114,21 +50546,22 @@ error condition) then also do nothing. Outputs a formatted message via the print handler. -The default print handler outputs the encoded message to stdout, without + +The default print handler outputs the encoded message to `stdout`, without appending a trailing new-line character. Typically, @format should end with its own new-line character. -g_print() should not be used from within libraries for debugging +This function should not be used from within libraries for debugging messages, since it may be redirected by applications to special purpose message windows or even files. Instead, libraries should -use g_log(), g_log_structured(), or the convenience macros g_message(), -g_warning() and g_error(). +use [func@GLib.log], [func@GLib.log_structured], or the convenience macros +[func@GLib.message], [func@GLib.warning] and [func@GLib.error]. - the message format. See the printf() documentation + the message format. See the `printf()` documentation @@ -49139,19 +50572,20 @@ g_warning() and g_error(). Outputs a formatted message via the error message handler. -The default handler outputs the encoded message to stderr, without appending + +The default handler outputs the encoded message to `stderr`, without appending a trailing new-line character. Typically, @format should end with its own new-line character. -g_printerr() should not be used from within libraries. -Instead g_log() or g_log_structured() should be used, or the convenience -macros g_message(), g_warning() and g_error(). +This function should not be used from within libraries. +Instead [func@GLib.log] or [func@GLib.log_structured] should be used, or the convenience +macros [func@GLib.message], [func@GLib.warning] and [func@GLib.error]. - the message format. See the printf() documentation + the message format. See the `printf()` documentation @@ -49176,7 +50610,7 @@ own new-line character. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -49187,14 +50621,22 @@ own new-line character. Calculates the maximum space needed to store the output -of the sprintf() function. +of the `sprintf()` function. + +If @format or @args are invalid, `0` is returned. This could happen if, for +example, @format contains an `%lc` or `%ls` placeholder and @args contains a +wide character which cannot be represented in multibyte encoding. `0` +can also be returned legitimately if, for example, @format is `%s` and @args +is an empty string. The caller is responsible for differentiating these two +return cases if necessary. It is recommended to not use `%lc` or `%ls` +placeholders in any case, as their behaviour is locale-dependent. - the maximum space needed to store the formatted string + the maximum space needed to store the formatted string, or `0` on error - the format string. See the printf() documentation + the format string. See the `printf()` documentation @@ -49203,6 +50645,21 @@ of the sprintf() function. + + Creates a new #GPrivate. + dynamic allocation of #GPrivate is a bad idea. Use + static storage and G_PRIVATE_INIT() instead. + + a newly allocated #GPrivate (which can never be destroyed) + + + + + a #GDestroyNotify + + + + If @dest is %NULL, free @src; otherwise, moves @src into *@dest. The error variable @dest points to must be %NULL. @@ -49509,7 +50966,7 @@ stores the length of its data in #guint, which may be shorter than - + This is just like the standard C qsort() function, but the comparison routine accepts a user data argument. @@ -49530,7 +50987,7 @@ This is guaranteed to be a stable sort since version 2.32. size of each element - + function to compare elements @@ -49621,55 +51078,6 @@ running. - - Quarks are associations between strings and integer identifiers. -Given either the string or the #GQuark identifier it is possible to -retrieve the other. - -Quarks are used for both [datasets][glib-Datasets] and -[keyed data lists][glib-Keyed-Data-Lists]. - -To create a new quark from a string, use g_quark_from_string() or -g_quark_from_static_string(). - -To find the string corresponding to a given #GQuark, use -g_quark_to_string(). - -To find the #GQuark corresponding to a given string, use -g_quark_try_string(). - -Another use for the string pool maintained for the quark functions -is string interning, using g_intern_string() or -g_intern_static_string(). An interned string is a canonical -representation for a string. One important advantage of interned -strings is that they can be compared for equality by a simple -pointer comparison, rather than using strcmp(). - - - The #GQueue structure and its associated functions provide a standard -queue data structure. Internally, GQueue uses the same data structure -as #GList to store elements with the same complexity over -insertion/deletion (O(1)) and access/search (O(n)) operations. - -The data contained in each element can be either integer values, by -using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], -or simply pointers to any type of data. - -As with all other GLib data structures, #GQueue is not thread-safe. -For a thread-safe queue, use #GAsyncQueue. - -To create a new GQueue, use g_queue_new(). - -To initialize a statically-allocated GQueue, use %G_QUEUE_INIT or -g_queue_init(). - -To add elements, use g_queue_push_head(), g_queue_push_head_link(), -g_queue_push_tail() and g_queue_push_tail_link(). - -To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). - -To free the entire queue, use g_queue_free(). - Returns a random #gboolean from @rand_. This corresponds to an unbiased coin toss. @@ -49734,52 +51142,6 @@ This corresponds to an unbiased coin toss. - - The following functions allow you to use a portable, fast and good -pseudo-random number generator (PRNG). - -Do not use this API for cryptographic purposes such as key -generation, nonces, salts or one-time pads. - -This PRNG is suitable for non-cryptographic use such as in games -(shuffling a card deck, generating levels), generating data for -a test suite, etc. If you need random data for cryptographic -purposes, it is recommended to use platform-specific APIs such -as `/dev/random` on UNIX, or CryptGenRandom() on Windows. - -GRand uses the Mersenne Twister PRNG, which was originally -developed by Makoto Matsumoto and Takuji Nishimura. Further -information can be found at -[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). - -If you just need a random number, you simply call the g_random_* -functions, which will create a globally used #GRand and use the -according g_rand_* functions internally. Whenever you need a -stream of reproducible random numbers, you better create a -#GRand yourself and use the g_rand_* functions directly, which -will also be slightly faster. Initializing a #GRand with a -certain seed will produce exactly the same series of random -numbers on all platforms. This can thus be used as a seed for -e.g. games. - -The g_rand*_range functions will return high quality equally -distributed random numbers, whereas for example the -`(g_random_int()%max)` approach often -doesn't yield equally distributed numbers. - -GLib changed the seeding algorithm for the pseudo-random number -generator Mersenne Twister, as used by #GRand. This was necessary, -because some seeds would yield very bad pseudo-random streams. -Also the pseudo-random integers generated by g_rand*_int_range() -will have a slightly better equal distribution with the new -version of GLib. - -The original seeding and generation algorithms, as found in -GLib 2.0.x, can be used instead of the new ones by setting the -environment variable `G_RANDOM_VERSION` to the value of '2.0'. -Use the GLib-2.0 algorithms only if you have sequences of numbers -generated with Glib-2.0 that you need to reproduce exactly. - Sets the seed for the global random number generator, which is used by the g_random_* functions, to @seed. @@ -49943,129 +51305,6 @@ resources allocated for @mem_block. - - A "reference counted box", or "RcBox", is an opaque wrapper data type -that is guaranteed to be as big as the size of a given data type, and -which augments the given data type with reference counting semantics -for its memory management. - -RcBox is useful if you have a plain old data type, like a structure -typically placed on the stack, and you wish to provide additional API -to use it on the heap; or if you want to implement a new type to be -passed around by reference without necessarily implementing copy/free -semantics or your own reference counting. - -The typical use is: - -|[<!-- language="C" --> -typedef struct { - char *name; - char *address; - char *city; - char *state; - int age; -} Person; - -Person * -person_new (void) -{ - return g_rc_box_new0 (Person); -} -]| - -Every time you wish to acquire a reference on the memory, you should -call g_rc_box_acquire(); similarly, when you wish to release a reference -you should call g_rc_box_release(): - -|[<!-- language="C" --> -// Add a Person to the Database; the Database acquires ownership -// of the Person instance -void -add_person_to_database (Database *db, Person *p) -{ - db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p)); -} - -// Removes a Person from the Database; the reference acquired by -// add_person_to_database() is released here -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_rc_box_release (p); -} -]| - -If you have additional memory allocated inside the structure, you can -use g_rc_box_release_full(), which takes a function pointer, which -will be called if the reference released was the last: - -|[<!-- language="C" --> -void -person_clear (Person *p) -{ - g_free (p->name); - g_free (p->address); - g_free (p->city); - g_free (p->state); -} - -void -remove_person_from_database (Database *db, Person *p) -{ - db->persons = g_list_remove (db->persons, p); - g_rc_box_release_full (p, (GDestroyNotify) person_clear); -} -]| - -If you wish to transfer the ownership of a reference counted data -type without increasing the reference count, you can use g_steal_pointer(): - -|[<!-- language="C" --> - Person *p = g_rc_box_new (Person); - - // fill_person_details() is defined elsewhere - fill_person_details (p); - - // add_person_to_database_no_ref() is defined elsewhere; it adds - // a Person to the Database without taking a reference - add_person_to_database_no_ref (db, g_steal_pointer (&p)); -]| - -## Thread safety - -The reference counting operations on data allocated using g_rc_box_alloc(), -g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's -responsibility to ensure that references are acquired are released on the -same thread. - -If you need thread safe reference counting, see the [atomic reference counted -data][arcbox] API. - -## Automatic pointer clean up - -If you want to add g_autoptr() support to your plain old data type through -reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and -g_rc_box_release(): - -|[<!-- language="C" --> -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release) -]| - -If you need to clear the contents of the data, you will need to use an -ancillary function that calls g_rc_box_release_full(): - -|[<!-- language="C" --> -static void -my_data_struct_release (MyDataStruct *data) -{ - // my_data_struct_clear() is defined elsewhere - g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); -} - -G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) -]| - Reallocates the memory pointed to by @mem, so that it now has space for @n_bytes bytes of memory. It returns the new address of the memory, which may @@ -50267,83 +51506,6 @@ resources allocated by the string are freed as well. - - Reference counting is a garbage collection mechanism that is based on -assigning a counter to a data type, or any memory area; the counter is -increased whenever a new reference to that data type is acquired, and -decreased whenever the reference is released. Once the last reference -is released, the resources associated to that data type are freed. - -GLib uses reference counting in many of its data types, and provides -the #grefcount and #gatomicrefcount types to implement safe and atomic -reference counting semantics in new data types. - -It is important to note that #grefcount and #gatomicrefcount should be -considered completely opaque types; you should always use the provided -API to increase and decrease the counters, and you should never check -their content directly, or compare their content with other values. - - - Reference counted strings are normal C strings that have been augmented -with a reference counter to manage their resources. You allocate a new -reference counted string and acquire and release references as needed, -instead of copying the string among callers; when the last reference on -the string is released, the resources allocated for it are freed. - -Typically, reference counted strings can be used when parsing data from -files and storing them into data structures that are passed to various -callers: - -|[<!-- language="C" --> -PersonDetails * -person_details_from_data (const char *data) -{ - // Use g_autoptr() to simplify error cases - g_autoptr(GRefString) full_name = NULL; - g_autoptr(GRefString) address = NULL; - g_autoptr(GRefString) city = NULL; - g_autoptr(GRefString) state = NULL; - g_autoptr(GRefString) zip_code = NULL; - - // parse_person_details() is defined elsewhere; returns refcounted strings - if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code)) - return NULL; - - if (!validate_zip_code (zip_code)) - return NULL; - - // add_address_to_cache() and add_full_name_to_cache() are defined - // elsewhere; they add strings to various caches, using refcounted - // strings to avoid copying data over and over again - add_address_to_cache (address, city, state, zip_code); - add_full_name_to_cache (full_name); - - // person_details_new() is defined elsewhere; it takes a reference - // on each string - PersonDetails *res = person_details_new (full_name, - address, - city, - state, - zip_code); - - return res; -} -]| - -In the example above, we have multiple functions taking the same strings -for different uses; with typical C strings, we'd have to copy the strings -every time the life time rules of the data differ from the life time of -the string parsed from the original buffer. With reference counted strings, -each caller can take a reference on the data, and keep it as long as it -needs to own the string. - -Reference counted strings can also be "interned" inside a global table -owned by GLib; while an interned string has at least a reference, creating -a new interned reference counted string with the same contents will return -a reference to the existing string instead of creating a new reference -counted string instance. Once the string loses its last reference, it will -be automatically removed from the global interned strings table. - Checks whether @replacement is a valid replacement string (see g_regex_replace()), i.e. that all escape sequences in @@ -50520,6 +51682,59 @@ the directories that actually changed value though. + + A wrapper for the POSIX remove() function. The remove() function +deletes a name from the filesystem. + +See your C library manual for more details about how remove() works +on your system. On Unix, remove() removes also directories, as it +calls unlink() for files and rmdir() for directories. On Windows, +although remove() in the C library only works for files, this +function tries first remove() and then if that fails rmdir(), and +thus works for both files and directories. Note however, that on +Windows, it is in general not possible to remove a file that is +open to some process, or mapped into memory. + +If this function fails on Windows you can't infer too much from the +errno value. rmdir() is tried regardless of what caused remove() to +fail. Any errno value set by remove() will be overwritten by that +set by rmdir(). + + 0 if the file was successfully removed, -1 if an error + occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + + + A wrapper for the POSIX rename() function. The rename() function +renames a file, moving it between directories if required. + +See your C library manual for more details about how rename() works +on your system. It is not possible in general on Windows to rename +a file that is open to some process. + + 0 if the renaming succeeded, -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pathname in the GLib file name encoding + + + + Reallocates the memory pointed to by @mem, so that it now has space for @n_structs elements of type @struct_type. It returns the new address of @@ -50544,8 +51759,8 @@ Care is taken to avoid overflow when calculating the size of the allocated block - Internal function used to print messages from the public g_return_if_fail() -and g_return_val_if_fail() macros. + Internal function used to print messages from the public [func@GLib.return_if_fail] +and [func@GLib.return_val_if_fail] macros. @@ -50598,10 +51813,6 @@ on your system. - - The #GScanner and its associated functions provide a -general purpose lexical scanner. - Adds a symbol to the default scope. Use g_scanner_scope_add_symbol() instead. @@ -50662,50 +51873,32 @@ general purpose lexical scanner. - - The #GSequence data structure has the API of a list, but is -implemented internally with a balanced binary tree. This means that -most of the operations (access, search, insertion, deletion, ...) on -#GSequence are O(log(n)) in average and O(n) in worst case for time -complexity. But, note that maintaining a balanced sorted list of n -elements is done in time O(n log(n)). -The data contained in each element can be either integer values, by using -of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply -pointers to any type of data. - -A #GSequence is accessed through "iterators", represented by a -#GSequenceIter. An iterator represents a position between two -elements of the sequence. For example, the "begin" iterator -represents the gap immediately before the first element of the -sequence, and the "end" iterator represents the gap immediately -after the last element. In an empty sequence, the begin and end -iterators are the same. - -Some methods on #GSequence operate on ranges of items. For example -g_sequence_foreach_range() will call a user-specified function on -each element with the given range. The range is delimited by the -gaps represented by the passed-in iterators, so if you pass in the -begin and end iterators, the range in question is the entire -sequence. - -The function g_sequence_get() is used with an iterator to access the -element immediately following the gap that the iterator represents. -The iterator is said to "point" to that element. - -Iterators are stable across most operations on a #GSequence. For -example an iterator pointing to some element of a sequence will -continue to point to that element even after the sequence is sorted. -Even moving an element to another sequence using for example -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. - + + Calls @func for each item in the range (@begin, @end) passing +@user_data to the function. @func must not modify the sequence +itself. + + + + + + a #GSequenceIter + + + + a #GSequenceIter + + + + a #GFunc + + + + user data passed to @func + + + + Returns the data that @iter points to. @@ -50859,6 +52052,63 @@ function is called on the existing data that @iter pointed to. + + Moves the data pointed to by @iter to a new position as indicated by +@cmp_func. This +function should be called for items in a sequence already sorted according +to @cmp_func whenever some aspect of an item changes so that @cmp_func +may return different values for that item. + +@cmp_func is called with two items of the @seq, and @cmp_data. +It should return 0 if the items are equal, a negative value if +the first item comes before the second, and a positive value if +the second item comes before the first. + + + + + + A #GSequenceIter + + + + the function used to compare items in the sequence + + + + user data passed to @cmp_func. + + + + + + Like g_sequence_sort_changed(), but uses +a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as +the compare function. + +@iter_cmp is called with two iterators pointing into the #GSequence that +@iter points into. It should +return 0 if the iterators are equal, a negative value if the first +iterator comes before the second, and a positive value if the second +iterator comes before the first. + + + + + + a #GSequenceIter + + + + the function used to compare iterators in the sequence + + + + user data passed to @cmp_func + + + + Swaps the items pointed to by @a and @b. It is allowed for @a and @b to point into difference sequences. @@ -50978,29 +52228,44 @@ could only be called once per process. + + If g_get_prgname() is not set, this is the same as setting +the name via g_set_prgname() and %TRUE is returned. Otherwise, +does nothing and returns %FALSE. This is thread-safe. + + whether g_prgname was initialized by the call. + + + + + the name of the program. + + + + Sets the print handler to @func, or resets it to the -default GLib handler if %NULL. +default GLib handler if `NULL`. -Any messages passed to g_print() will be output via +Any messages passed to [func@GLib.print] will be output via the new handler. The default handler outputs -the encoded message to stdout. By providing your own handler +the encoded message to `stdout`. By providing your own handler you can redirect the output, to a GTK widget or a log file for example. Since 2.76 this functions always returns a valid -#GPrintFunc, and never returns %NULL. If no custom +[type@GLib.PrintFunc], and never returns `NULL`. If no custom print handler was set, it will return the GLib default print handler and that can be re-used to -decorate its output and/or to write to stderr -in all platforms. Before GLib 2.76, this was %NULL. +decorate its output and/or to write to `stderr` +in all platforms. Before GLib 2.76, this was `NULL`. the old print handler - the new print handler or %NULL to + the new print handler or `NULL` to reset to the default @@ -51008,32 +52273,45 @@ in all platforms. Before GLib 2.76, this was %NULL. Sets the handler for printing error messages to @func, -or resets it to the default GLib handler if %NULL. +or resets it to the default GLib handler if `NULL`. -Any messages passed to g_printerr() will be output via +Any messages passed to [func@GLib.printerr] will be output via the new handler. The default handler outputs the encoded -message to stderr. By providing your own handler you can +message to `stderr`. By providing your own handler you can redirect the output, to a GTK widget or a log file for example. Since 2.76 this functions always returns a valid -#GPrintFunc, and never returns %NULL. If no custom error +[type@GLib.PrintFunc], and never returns `NULL`. If no custom error print handler was set, it will return the GLib default error print handler and that can be re-used to decorate -its output and/or to write to stderr in all platforms. -Before GLib 2.76, this was %NULL. +its output and/or to write to `stderr` in all platforms. +Before GLib 2.76, this was `NULL`. the old error message handler - he new error message handler or %NULL - to reset to the default + he new error message handler or `NULL` + to reset to the default + + + + + + + + + + + + + Sets an environment variable. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name @@ -51074,15 +52352,6 @@ array directly to execvpe(), g_spawn_async(), or the like. - - GLib provides the functions g_shell_quote() and g_shell_unquote() -to handle shell-like quoting in strings. The function g_shell_parse_argv() -parses a string similar to the way a POSIX shell (/bin/sh) would. - -Note that string handling in shells has many obscure and historical -corner-cases which these functions do not necessarily reproduce. They -are good enough in practice, though. - @@ -51190,41 +52459,23 @@ preserve things literally. - - Performs a checked addition of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. + - a pointer to the #gsize destination - the #gsize left operand - the #gsize right operand - - Performs a checked multiplication of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. + - a pointer to the #gsize destination - the #gsize left operand - the #gsize right operand @@ -51290,6 +52541,11 @@ internally. + + + + + A convenience macro to duplicate a block of memory using the slice allocator. @@ -51503,6 +52759,21 @@ Note that it is considered perfectly acceptable to access + + + + + + + + + + + + + + + A safer form of the standard sprintf() function. The output is guaranteed to not exceed @n characters (including the terminating nul character), so @@ -51538,7 +52809,7 @@ the Single Unix Specification. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -51662,61 +52933,6 @@ each prime is approximately 1.5-2 times the previous prime. - - GLib supports spawning of processes with an API that is more -convenient than the bare UNIX fork() and exec(). - -The g_spawn family of functions has synchronous (g_spawn_sync()) -and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), -as well as convenience variants that take a complete shell-like -commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). - -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_wait_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); -} -]| - Executes a child program asynchronously. @@ -52455,7 +53671,7 @@ See also g_strdup_printf(). a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -52464,6 +53680,72 @@ See also g_strdup_printf(). + + A wrapper for the POSIX stat() function. The stat() function +returns information about a file. On Windows the stat() function in +the C library checks only the FAT-style READONLY attribute and does +not look at the ACL at all. Thus on Windows the protection bits in +the @st_mode field are a fabrication of little use. + +On Windows the Microsoft C libraries have several variants of the +stat struct and stat() function with names like _stat(), _stat32(), +_stat32i64() and _stat64i32(). The one used here is for 32-bit code +the one with 32-bit size and time fields, specifically called _stat32(). + +In Microsoft's compiler, by default struct stat means one with +64-bit time fields while in MinGW struct stat is the legacy one +with 32-bit fields. To hopefully clear up this messs, the gstdio.h +header defines a type #GStatBuf which is the appropriate struct type +depending on the platform and/or compiler being used. On POSIX it +is just struct stat, but note that even on POSIX platforms, stat() +might be a macro. + +See your C library manual for more details about stat(). + + 0 if the information was successfully retrieved, + -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pointer to a stat struct, which will be filled with the file + information + + + + + + Works like g_mutex_lock(), but for a #GStaticMutex. + Use g_mutex_lock() + + + a #GStaticMutex. + + + + + Works like g_mutex_trylock(), but for a #GStaticMutex. + Use g_mutex_trylock() + + + a #GStaticMutex. + + + + + Works like g_mutex_unlock(), but for a #GStaticMutex. + Use g_mutex_unlock() + + + a #GStaticMutex. + + + Sets @pp to %NULL, returning the value that was there before. @@ -52995,14 +54277,14 @@ longer needed. The returned string is guaranteed to be non-NULL, unless @format contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character. - + a newly-allocated string holding the result a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -53023,14 +54305,14 @@ representation is available for the given character. See also g_vasprintf(), which offers the same functionality, but additionally returns the length of the allocated string. - + a newly-allocated string holding the result a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -53039,12 +54321,12 @@ additionally returns the length of the allocated string. - + Copies %NULL-terminated array of strings. The copy is a deep copy; the new array should be freed by first freeing each string, then the array itself. g_strfreev() does this for you. If called on a %NULL value, g_strdupv() simply returns %NULL. - + a new %NULL-terminated array of strings. @@ -53123,82 +54405,12 @@ If @str_array is %NULL, this function simply returns. - + a %NULL-terminated array of strings to free - - String chunks are used to store groups of strings. Memory is -allocated in blocks, and as strings are added to the #GStringChunk -they are copied into the next free position in a block. When a block -is full a new block is allocated. - -When storing a large number of strings, string chunks are more -efficient than using g_strdup() since fewer calls to malloc() are -needed, and less memory is wasted in memory allocation overheads. - -By adding strings with g_string_chunk_insert_const() it is also -possible to remove duplicates. - -To create a new #GStringChunk use g_string_chunk_new(). - -To add strings to a #GStringChunk use g_string_chunk_insert(). - -To add strings to a #GStringChunk, but without duplicating strings -which are already in the #GStringChunk, use -g_string_chunk_insert_const(). - -To free the entire #GStringChunk use g_string_chunk_free(). It is -not possible to free individual strings. - - - This section describes a number of utility functions for creating, -duplicating, and manipulating strings. - -Note that the functions g_printf(), g_fprintf(), g_sprintf(), -g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() -are declared in the header `gprintf.h` which is not included in `glib.h` -(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to -explicitly include `<glib/gprintf.h>` in order to use the GLib -printf() functions. - -## String precision pitfalls # {#string-precision} - -While you may use the printf() functions to format UTF-8 strings, -notice that the precision of a \%Ns parameter is interpreted -as the number of bytes, not characters to print. On top of that, -the GNU libc implementation of the printf() functions has the -"feature" that it checks that the string given for the \%Ns -parameter consists of a whole number of characters in the current -encoding. So, unless you are sure you are always going to be in an -UTF-8 locale or your know your text is restricted to ASCII, avoid -using \%Ns. If your intention is to format strings for a -certain number of columns, then \%Ns is not a correct solution -anyway, since it fails to take wide characters (see g_unichar_iswide()) -into account. - -Note also that there are various printf() parameters which are platform -dependent. GLib provides platform independent macros for these parameters -which should be used instead. A common example is %G_GUINT64_FORMAT, which -should be used instead of `%llu` or similar parameters for formatting -64-bit integers. These macros are all named `G_*_FORMAT`; see -[Basic Types][glib-Basic-Types]. - - - A #GString is an object that handles the memory management of a C -string for you. The emphasis of #GString is on text, typically -UTF-8. Crucially, the "str" member of a #GString is guaranteed to -have a trailing nul character, and it is therefore always safe to -call functions such as strchr() or g_strdup() on it. - -However, a #GString can also hold arbitrary binary data, because it -has a "len" member, which includes any possible embedded nul -characters in the data. Conceptually then, #GString is like a -#GByteArray with the addition of many convenience methods for text, -and a guaranteed nul terminator. - An auxiliary function for gettext() support (see Q_()). @@ -53858,14 +55070,14 @@ do so even if it isn’t. Asserts that all messages previously indicated via -g_test_expect_message() have been seen and suppressed. +[func@GLib.test_expect_message] have been seen and suppressed. -This API may only be used with the old logging API (g_log() without -%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging -API. See [Testing for Messages][testing-for-messages]. +This API may only be used with the old logging API ([func@GLib.log] without +`G_LOG_USE_STRUCTURED` defined). It will not work with the structured logging +API. See [Testing for Messages](logging.html#testing-for-messages). -If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly -expected via g_test_expect_message() then they will be ignored. +If messages at [flags@GLib.LogLevelFlags.DEBUG] are emitted, but not explicitly +expected via [func@GLib.test_expect_message] then they will be ignored. @@ -54050,39 +55262,40 @@ crash collection infrastructure such as systemd-coredump or abrt. Indicates that a message with the given @log_domain and @log_level, -with text matching @pattern, is expected to be logged. When this -message is logged, it will not be printed, and the test case will +with text matching @pattern, is expected to be logged. + +When this message is logged, it will not be printed, and the test case will not abort. -This API may only be used with the old logging API (g_log() without -%G_LOG_USE_STRUCTURED defined). It will not work with the structured logging -API. See [Testing for Messages][testing-for-messages]. +This API may only be used with the old logging API ([func@GLib.log] without +`G_LOG_USE_STRUCTURED` defined). It will not work with the structured logging +API. See [Testing for Messages](logging.html#testing-for-messages). -Use g_test_assert_expected_messages() to assert that all +Use [func@GLib.test_assert_expected_messages] to assert that all previously-expected messages have been seen and suppressed. You can call this multiple times in a row, if multiple messages are expected as a result of a single call. (The messages must appear in -the same order as the calls to g_test_expect_message().) +the same order as the calls to [func@GLib.test_expect_message].) For example: -|[<!-- language="C" --> - // g_main_context_push_thread_default() should fail if the - // context is already owned by another thread. - g_test_expect_message (G_LOG_DOMAIN, - G_LOG_LEVEL_CRITICAL, - "assertion*acquired_context*failed"); - g_main_context_push_thread_default (bad_context); - g_test_assert_expected_messages (); -]| +```c +// g_main_context_push_thread_default() should fail if the +// context is already owned by another thread. +g_test_expect_message (G_LOG_DOMAIN, + G_LOG_LEVEL_CRITICAL, + "assertion*acquired_context*failed"); +g_main_context_push_thread_default (bad_context); +g_test_assert_expected_messages (); +``` -Note that you cannot use this to test g_error() messages, since -g_error() intentionally never returns even if the program doesn't -abort; use g_test_trap_subprocess() in this case. +Note that you cannot use this to test [func@GLib.error] messages, since +[func@GLib.error] intentionally never returns even if the program doesn’t +abort; use [func@GLib.test_trap_subprocess] in this case. -If messages at %G_LOG_LEVEL_DEBUG are emitted, but not explicitly -expected via g_test_expect_message() then they will be ignored. +If messages at [flags@GLib.LogLevelFlags.DEBUG] are emitted, but not explicitly +expected via [func@GLib.test_expect_message] then they will be ignored. @@ -54096,7 +55309,7 @@ expected via g_test_expect_message() then they will be ignored. - a glob-style [pattern][glib-Glob-style-pattern-matching] + a glob-style pattern (see [type@GLib.PatternSpec]) @@ -54355,10 +55568,10 @@ function which needs the special behavior. This handler has no effect on g_error messages. This handler also has no effect on structured log messages (using -g_log_structured() or g_log_structured_array()). To change the fatal +[func@GLib.log_structured] or [func@GLib.log_structured_array]). To change the fatal behaviour for specific log messages, programs must install a custom log -writer function using g_log_set_writer_func().See -[Using Structured Logging][using-structured-logging]. +writer function using [func@GLib.log_set_writer_func].See +[Using Structured Logging](logging.html#using-structured-logging). @@ -54915,6 +56128,31 @@ Use g_test_trap_subprocess() instead. Respawns the test program to run only @test_path in a subprocess. + +This is equivalent to calling g_test_trap_subprocess_with_envp() with `envp` +set to %NULL. See the documentation for that function for full details. + + + + + + Test to run in a subprocess + + + + Timeout for the subprocess test in micro seconds. + + + + Flags to modify subprocess behaviour. + + + + + + Respawns the test program to run only @test_path in a subprocess with the +given @envp environment. + This can be used for a test case that might not return, or that might abort. @@ -54928,6 +56166,8 @@ ending with "`/subprocess`" if the test only has one child test); tests with names of this form will automatically be skipped in the parent process. +If @envp is %NULL, the parent process’ environment will be inherited. + If @usec_timeout is non-0, the test subprocess is aborted and considered failing if its run time exceeds it. @@ -54970,13 +56210,33 @@ message. g_test_trap_assert_stderr ("*ERROR*too large*"); } + static void + test_different_username (void) + { + if (g_test_subprocess ()) + { + // Code under test goes here + g_message ("Username is now simulated as %s", g_getenv ("USER")); + return; + } + + // Reruns this same test in a subprocess + g_autoptr(GStrv) envp = g_get_environ (); + envp = g_environ_setenv (g_steal_pointer (&envp), "USER", "charlie", TRUE); + g_test_trap_subprocess_with_envp (NULL, envp, 0, G_TEST_SUBPROCESS_DEFAULT); + g_test_trap_assert_passed (); + g_test_trap_assert_stdout ("Username is now simulated as charlie"); + } + int main (int argc, char **argv) { g_test_init (&argc, &argv, NULL); - g_test_add_func ("/myobject/create_large_object", + g_test_add_func ("/myobject/create-large-object", test_create_large_object); + g_test_add_func ("/myobject/different-username", + test_different_username); return g_test_run (); } ]| @@ -54988,6 +56248,14 @@ message. Test to run in a subprocess + + Environment + to run the test in, or %NULL to inherit the parent’s environment. This must + be in the GLib filename encoding. + + + + Timeout for the subprocess test in micro seconds. @@ -55016,188 +56284,74 @@ In tests that use g_test_init(), the option `--verbose` enables this, while `-q` or `--quiet` disables it. The default is neither g_test_verbose() nor g_test_quiet(). - - GLib provides a framework for writing and maintaining unit tests -in parallel to the code they are testing. The API is designed according -to established concepts found in the other test frameworks (JUnit, NUnit, -RUnit), which in turn is based on smalltalk unit testing concepts. - -- Test case: Tests (test methods) are grouped together with their - fixture into test cases. - -- Fixture: A test fixture consists of fixture data and setup and - teardown methods to establish the environment for the test - functions. We use fresh fixtures, i.e. fixtures are newly set - up and torn down around each test invocation to avoid dependencies - between tests. - -- Test suite: Test cases can be grouped into test suites, to allow - subsets of the available tests to be run. Test suites can be - grouped into other test suites as well. - -The API is designed to handle creation and registration of test suites -and test cases implicitly. A simple call like -|[<!-- language="C" --> - g_test_init (&argc, &argv, G_TEST_OPTION_ISOLATE_DIRS, NULL); - - g_test_add_func ("/misc/assertions", test_assertions); -]| -creates a test suite called "misc" with a single test case named -"assertions", which consists of running the test_assertions function. - -g_test_init() should be called before calling any other test functions. - -In addition to the traditional g_assert_true(), the test framework provides -an extended set of assertions for comparisons: g_assert_cmpfloat(), -g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(), -g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and -g_assert_cmpvariant(). The -advantage of these variants over plain g_assert_true() is that the assertion -messages can be more elaborate, and include the values of the compared -entities. - -Note that g_assert() should not be used in unit tests, since it is a no-op -when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code, -and g_assert_true() in unit tests. - -A full example of creating a test suite with two tests using fixtures: -|[<!-- language="C" --> -#include <glib.h> -#include <locale.h> - -typedef struct { - MyObject *obj; - OtherObject *helper; -} MyObjectFixture; - -static void -my_object_fixture_set_up (MyObjectFixture *fixture, - gconstpointer user_data) -{ - fixture->obj = my_object_new (); - my_object_set_prop1 (fixture->obj, "some-value"); - my_object_do_some_complex_setup (fixture->obj, user_data); - - fixture->helper = other_object_new (); -} - -static void -my_object_fixture_tear_down (MyObjectFixture *fixture, - gconstpointer user_data) -{ - g_clear_object (&fixture->helper); - g_clear_object (&fixture->obj); -} - -static void -test_my_object_test1 (MyObjectFixture *fixture, - gconstpointer user_data) -{ - g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value"); -} - -static void -test_my_object_test2 (MyObjectFixture *fixture, - gconstpointer user_data) -{ - my_object_do_some_work_using_helper (fixture->obj, fixture->helper); - g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value"); -} - -int -main (int argc, char *argv[]) -{ - setlocale (LC_ALL, ""); - - g_test_init (&argc, &argv, NULL); - - // Define the tests. - g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data", - my_object_fixture_set_up, test_my_object_test1, - my_object_fixture_tear_down); - g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data", - my_object_fixture_set_up, test_my_object_test2, - my_object_fixture_tear_down); + + This function creates a new thread. - return g_test_run (); -} -]| - -## Integrating GTest in your project - -If you are using the [Meson](http://mesonbuild.com) build system, you will -typically use the provided `test()` primitive to call the test binaries, -e.g.: - -|[<!-- language="plain" --> - test( - 'foo', - executable('foo', 'foo.c', dependencies: deps), - env: [ - 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), - 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), - ], - ) - - test( - 'bar', - executable('bar', 'bar.c', dependencies: deps), - env: [ - 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), - 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), - ], - ) -]| - -If you are using Autotools, you're strongly encouraged to use the Automake -[TAP](https://testanything.org/) harness; GLib provides template files for -easily integrating with it: - - - [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk) - - [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test) - - [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh) - -You can copy these files in your own project's root directory, and then -set up your `Makefile.am` file to reference them, for instance: - -|[<!-- language="plain" --> -include $(top_srcdir)/glib-tap.mk - -# test binaries -test_programs = \ - foo \ - bar - -# data distributed in the tarball -dist_test_data = \ - foo.data.txt \ - bar.data.txt - -# data not distributed in the tarball -test_data = \ - blah.data.txt -]| +The new thread executes the function @func with the argument @data. +If the thread was created successfully, it is returned. -Make sure to distribute the TAP files, using something like the following -in your top-level `Makefile.am`: - -|[<!-- language="plain" --> -EXTRA_DIST += \ - tap-driver.sh \ - tap-test -]| +@error can be %NULL to ignore errors, or non-%NULL to report errors. +The error is set, if and only if the function returns %NULL. -`glib-tap.mk` will be distributed implicitly due to being included in a -`Makefile.am`. All three files should be added to version control. - -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. 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. - +This function returns a reference to the created thread only if +@joinable is %TRUE. In that case, you must free this reference by +calling g_thread_unref() or g_thread_join(). If @joinable is %FALSE +then you should probably not touch the return value. + Use g_thread_new() instead + + the new #GThread on success + + + + + a function to execute in the new thread + + + + an argument to supply to the new thread + + + + should this thread be joinable? + + + + + + This function creates a new thread. + The @bound and @priority arguments are now ignored. +Use g_thread_new(). + + the new #GThread on success. + + + + + a function to execute in the new thread. + + + + an argument to supply to the new thread. + + + + a stack size for the new thread. + + + + should this thread be joinable? + + + + ignored + + + + ignored + + + + @@ -55227,6 +56381,86 @@ or or from within a #GThreadPool. + + Call @thread_func on all #GThreads that have been +created with g_thread_create(). + +Note that threads may decide to exit while @thread_func is +running, so without intimate knowledge about the lifetime of +foreign threads, @thread_func shouldn't access the GThread* +pointer passed in as first argument. However, @thread_func will +not be called for threads which are known to have exited already. + +Due to thread lifetime checks, this function has an execution complexity +which is quadratic in the number of existing threads. + There aren't many things you can do with a #GThread, + except comparing it with one that was returned from g_thread_create(). + There are better ways to find out if your thread is still alive. + + + + + + function to call for all #GThread structures + + + + second argument to @thread_func + + + + + + Indicates if g_thread_init() has been called. + + %TRUE if threads have been initialized. + + + + + If you use GLib from more than one thread, you must initialize the +thread system by calling g_thread_init(). + +Since version 2.24, calling g_thread_init() multiple times is allowed, +but nothing happens except for the first call. + +Since version 2.32, GLib does not support custom thread implementations +anymore and the @vtable parameter is ignored and you should pass %NULL. + +<note><para>g_thread_init() must not be called directly or indirectly +in a callback from GLib. Also no mutexes may be currently locked while +calling g_thread_init().</para></note> + +<note><para>To use g_thread_init() in your program, you have to link +with the libraries that the command <command>pkg-config --libs +gthread-2.0</command> outputs. This is not the case for all the +other thread-related functions of GLib. Those can be used without +having to link with the thread libraries.</para></note> + This function is no longer necessary. The GLib + threading system is automatically initialized at the start + of your program. + + + + + + a function table of type #GThreadFunctions, that provides + the entry points to the thread system to be used. Since 2.32, + this parameter is ignored and should always be %NULL + + + + + + + + + + + + + + This function will return the maximum @interval that a thread will wait in the thread pool for new tasks before @@ -55300,37 +56534,6 @@ regularly stop all unused threads e.g. from g_timeout_add(). - - Sometimes you wish to asynchronously fork out the execution of work -and continue working in your own thread. If that will happen often, -the overhead of starting and destroying a thread each time might be -too high. In such cases reusing already started threads seems like a -good idea. And it indeed is, but implementing this can be tedious -and error-prone. - -Therefore GLib provides thread pools for your convenience. An added -advantage is, that the threads can be shared between the different -subsystems of your program, when they are using GLib. - -To create a new thread pool, you use g_thread_pool_new(). -It is destroyed by g_thread_pool_free(). - -If you want to execute a certain task within a thread pool, -you call g_thread_pool_push(). - -To get the current number of running threads you call -g_thread_pool_get_num_threads(). To get the number of still -unprocessed tasks you call g_thread_pool_unprocessed(). To control -the maximal number of threads for a thread pool, you use -g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). - -Finally you can control the number of unused threads, that are kept -alive by GLib for future use. The current number can be fetched with -g_thread_pool_get_num_unused_threads(). The maximal number can be -controlled by g_thread_pool_get_max_unused_threads() and -g_thread_pool_set_max_unused_threads(). All currently unused threads -can be stopped by calling g_thread_pool_stop_unused_threads(). - This function returns the #GThread corresponding to the current thread. Note that this function does not increase @@ -55346,6 +56549,13 @@ as g_thread_join()) on these threads. + + This macro returns %TRUE if the thread system is initialized, +and %FALSE if it is not. + +For language bindings, g_thread_get_initialized() provides +the same functionality as a function. + Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run. @@ -55355,97 +56565,6 @@ This function is often used as a method to make busy wait less evil. - - Threads act almost like processes, but unlike processes all threads -of one process share the same memory. This is good, as it provides -easy communication between the involved threads via this shared -memory, and it is bad, because strange things (so called -"Heisenbugs") might happen if the program is not carefully designed. -In particular, due to the concurrent nature of threads, no -assumptions on the order of execution of code running in different -threads can be made, unless order is explicitly forced by the -programmer through synchronization primitives. - -The aim of the thread-related functions in GLib is to provide a -portable means for writing multi-threaded software. There are -primitives for mutexes to protect the access to portions of memory -(#GMutex, #GRecMutex and #GRWLock). There is a facility to use -individual bits for locks (g_bit_lock()). There are primitives -for condition variables to allow synchronization of threads (#GCond). -There are primitives for thread-private data - data that every -thread has a private instance of (#GPrivate). There are facilities -for one-time initialization (#GOnce, g_once_init_enter()). Finally, -there are primitives to create and manage threads (#GThread). - -The GLib threading system used to be initialized with g_thread_init(). -This is no longer necessary. Since version 2.32, the GLib threading -system is automatically initialized at the start of your program, -and all thread-creation functions and synchronization primitives -are available right away. - -Note that it is not safe to assume that your program has no threads -even if you don't call g_thread_new() yourself. GLib and GIO can -and will create threads for their own purposes in some cases, such -as when using g_unix_signal_source_new() or when using GDBus. - -Originally, UNIX did not have threads, and therefore some traditional -UNIX APIs are problematic in threaded programs. Some notable examples -are - -- C library functions that return data in statically allocated - buffers, such as strtok() or strerror(). For many of these, - there are thread-safe variants with a _r suffix, or you can - look at corresponding GLib APIs (like g_strsplit() or g_strerror()). - -- The functions setenv() and unsetenv() manipulate the process - environment in a not thread-safe way, and may interfere with getenv() - calls in other threads. Note that getenv() calls may be hidden behind - other APIs. For example, GNU gettext() calls getenv() under the - covers. In general, it is best to treat the environment as readonly. - If you absolutely have to modify the environment, do it early in - main(), when no other threads are around yet. - -- The setlocale() function changes the locale for the entire process, - affecting all threads. Temporary changes to the locale are often made - to change the behavior of string scanning or formatting functions - like scanf() or printf(). GLib offers a number of string APIs - (like g_ascii_formatd() or g_ascii_strtod()) that can often be - used as an alternative. Or you can use the uselocale() function - to change the locale only for the current thread. - -- The fork() function only takes the calling thread into the child's - copy of the process image. If other threads were executing in critical - sections they could have left mutexes locked which could easily - cause deadlocks in the new child. For this reason, you should - call exit() or exec() as soon as possible in the child and only - make signal-safe library calls before that. - -- The daemon() function uses fork() in a way contrary to what is - described above. It should not be used with GLib programs. - -GLib itself is internally completely thread-safe (all global data is -automatically locked), but individual data structure instances are -not automatically locked for performance reasons. For example, -you must coordinate accesses to the same #GHashTable from multiple -threads. The two notable exceptions from this rule are #GMainLoop -and #GAsyncQueue, which are thread-safe and need no further -application-level locking to be accessed from multiple threads. -Most refcounting functions such as g_object_ref() are also thread-safe. - -A common use for #GThreads is to move a long-running blocking operation out -of the main thread and into a worker thread. For GLib functions, such as -single GIO operations, this is not necessary, and complicates the code. -Instead, the `…_async()` version of the function should be used from the main -thread, eliminating the need for locking and synchronisation between multiple -threads. If an operation does need to be moved to a worker thread, consider -using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a -better choice than #GThread, as it handles thread reuse and task queueing; -#GTask uses this internally. - -However, if multiple blocking operations need to be performed in sequence, -and it is not possible to use #GTask for them, moving them to a worker thread -can clarify the code. - Converts a string containing an ISO 8601 encoded date and time to a #GTimeVal and puts it into @time_. @@ -55791,53 +56910,60 @@ See g_get_monotonic_time(). - - #GTimer records a start time, and counts microseconds elapsed since -that time. This is done somewhat differently on different platforms, -and can be tricky to get exactly right, so #GTimer provides a -portable/convenient interface. - - - #GTimeZone is a structure that represents a time zone, at no -particular point in time. It is refcounted and immutable. - -Each time zone has an identifier (for example, ‘Europe/London’) which is -platform dependent. See g_time_zone_new() for information on the identifier -formats. The identifier of a time zone can be retrieved using -g_time_zone_get_identifier(). - -A time zone contains a number of intervals. Each interval has -an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a -flag indicating if the daylight savings time is in effect during that -interval. A time zone always has at least one interval — interval 0. Note -that interval abbreviations are not the same as time zone identifiers -(apart from ‘UTC’), and cannot be passed to g_time_zone_new(). - -Every UTC time is contained within exactly one interval, but a given -local time may be contained within zero, one or two intervals (due to -incontinuities associated with daylight savings time). - -An interval may refer to a specific period of time (eg: the duration -of daylight savings time during 2010) or it may refer to many periods -of time that share the same properties (eg: all periods of daylight -savings time). It is also possible (usually for political reasons) -that some properties (like the abbreviation) change between intervals -without other properties changing. - -#GTimeZone is available since GLib 2.26. - - - A #GTrashStack is an efficient way to keep a stack of unused allocated -memory chunks. Each memory chunk is required to be large enough to hold -a #gpointer. This allows the stack to be maintained without any space -overhead, since the stack pointers can be stored inside the memory chunks. - -There is no function to create a #GTrashStack. A %NULL #GTrashStack* -is a perfectly valid empty stack. - -There is no longer any good reason to use #GTrashStack. If you have -extra pieces of memory, free() them and allocate them again later. - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Returns the height of a #GTrashStack. @@ -55901,64 +57027,6 @@ which may be %NULL. - - The #GTree structure and its associated functions provide a sorted -collection of key/value pairs optimized for searching and traversing -in order. This means that most of the operations (access, search, -insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n) -in worst case for time complexity. But, note that maintaining a -balanced sorted #GTree of n elements is done in time O(n log(n)). - -To create a new #GTree use g_tree_new(). - -To insert a key/value pair into a #GTree use g_tree_insert() -(O(n log(n))). - -To remove a key/value pair use g_tree_remove() (O(n log(n))). - -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 -get the height of a #GTree, use g_tree_height(). - -To traverse a #GTree, calling a function for each node visited in -the traversal, use g_tree_foreach(). - -To destroy a #GTree, use g_tree_destroy(). - - - The #GNode struct and its associated functions provide a N-ary tree -data structure, where nodes in the tree can contain arbitrary data. - -To create a new tree use g_node_new(). - -To insert a node into a tree use g_node_insert(), -g_node_insert_before(), g_node_append() and g_node_prepend(). - -To create a new node and insert it into a tree use -g_node_insert_data(), g_node_insert_data_after(), -g_node_insert_data_before(), g_node_append_data() -and g_node_prepend_data(). - -To reverse the children of a node use g_node_reverse_children(). - -To find a node use g_node_get_root(), g_node_find(), -g_node_find_child(), g_node_child_index(), g_node_child_position(), -g_node_first_child(), g_node_last_child(), g_node_nth_child(), -g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() -or g_node_last_sibling(). - -To get information about a node or tree use G_NODE_IS_LEAF(), -G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), -g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). - -To traverse a tree, calling a function for each node visited in the -traversal, use g_node_traverse() or g_node_children_foreach(). - -To remove a node or subtree from a tree use g_node_unlink() or -g_node_destroy(). - Attempts to allocate @n_bytes, and returns %NULL on failure. Contrast with g_malloc(), which aborts the program on failure. @@ -56113,76 +57181,12 @@ The function returns %NULL if an overflow occurs. - - Many times GLib, GTK, and other libraries allow you to pass "user -data" to a callback, in the form of a void pointer. From time to time -you want to pass an integer instead of a pointer. You could allocate -an integer, with something like: -|[<!-- language="C" --> - int *ip = g_new (int, 1); - *ip = 42; -]| -But this is inconvenient, and it's annoying to have to free the -memory at some later time. - -Pointers are always at least 32 bits in size (on all platforms GLib -intends to support). Thus you can store at least 32-bit integer values -in a pointer value. Naively, you might try this, but it's incorrect: -|[<!-- language="C" --> - gpointer p; - int i; - p = (void*) 42; - i = (int) p; -]| -Again, that example was not correct, don't copy it. -The problem is that on some systems you need to do this: -|[<!-- language="C" --> - gpointer p; - int i; - p = (void*) (long) 42; - i = (int) (long) p; -]| -The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care -to do the right thing on every platform. - -Warning: You may not store pointers in integers. This is not -portable in any way, shape or form. These macros only allow storing -integers in pointers, and only preserve 32 bits of the integer; values -outside the range of a 32-bit integer will be mangled. - - - GLib defines a number of commonly used types, which can be divided -into several groups: -- New types which are not part of standard C (but are defined in - various C standard library header files) — #gboolean, #gssize. -- Integer types which are guaranteed to be the same size across - all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, - #guint32, #gint64, #guint64. -- Types which are easier to use than their standard C counterparts - - #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. -- Types which correspond exactly to standard C types, but are - included for completeness — #gchar, #gint, #gshort, #glong, - #gfloat, #gdouble. -- Types which correspond exactly to standard C99 types, but are available - to use even if your compiler does not support C99 — #gsize, #goffset, - #gintptr, #guintptr. - -GLib also defines macros for the limits of some of the standard -integer and floating point types, as well as macros for suitable -printf() formats for these types. - -Note that depending on the platform and build configuration, the format -macros might not be compatible with the system provided printf() function, -because GLib might use a different printf() implementation internally. -The format macros will always work with GLib API (like g_print()), and with -any C99 compatible printf() implementation. - Convert a string from UCS-4 to UTF-16. A 0 character will be added to the result after the converted text. @@ -56253,79 +57257,43 @@ to UTF-8. The result will be terminated with a 0 byte. - - Performs a checked addition of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. + - a pointer to the #guint64 destination - the #guint64 left operand - the #guint64 right operand - - Performs a checked multiplication of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. + - a pointer to the #guint64 destination - the #guint64 left operand - the #guint64 right operand - - Performs a checked addition of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. + - a pointer to the #guint destination - the #guint left operand - the #guint right operand - - Performs a checked multiplication of @a and @b, storing the result in -@dest. - -If the operation is successful, %TRUE is returned. If the operation -overflows then the state of @dest is undefined and %FALSE is -returned. + - a pointer to the #guint destination - the #guint left operand - the #guint right operand @@ -56926,36 +57894,6 @@ g_unichar_isxdigit()), its numeric value. Otherwise, -1. - - This section describes a number of functions for dealing with -Unicode characters and strings. There are analogues of the -traditional `ctype.h` character classification and case conversion -functions, UTF-8 analogues of some string utility functions, -functions to perform normalization, case conversion and collation -on UTF-8 strings and finally functions to convert between the UTF-8, -UTF-16 and UCS-4 encodings of Unicode. - -The implementations of the Unicode functions in GLib are based -on the Unicode Character Data tables, which are available from -[www.unicode.org](http://www.unicode.org/). - - * Unicode 4.0 was added in GLib 2.8 - * Unicode 4.1 was added in GLib 2.10 - * Unicode 5.0 was added in GLib 2.12 - * Unicode 5.1 was added in GLib 2.16.3 - * Unicode 6.0 was added in GLib 2.30 - * Unicode 6.1 was added in GLib 2.32 - * Unicode 6.2 was added in GLib 2.36 - * Unicode 6.3 was added in GLib 2.40 - * Unicode 7.0 was added in GLib 2.42 - * Unicode 8.0 was added in GLib 2.48 - * Unicode 9.0 was added in GLib 2.50.1 - * Unicode 10.0 was added in GLib 2.54 - * Unicode 11.10 was added in GLib 2.58 - * Unicode 12.0 was added in GLib 2.62 - * Unicode 12.1 was added in GLib 2.62 - * Unicode 13.0 was added in GLib 2.66 - Computes the canonical decomposition of a Unicode character. Use the more flexible g_unichar_fully_decompose() @@ -56997,7 +57935,7 @@ manual for more information. - + Looks up the Unicode script for @iso15924. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. This function accepts four letter codes encoded as a @guint32 in a @@ -57020,7 +57958,7 @@ for details. - + Looks up the ISO 15924 code for @script. ISO 15924 assigns four-letter codes to scripts. For example, the code for Arabic is 'Arab'. The four letter codes are encoded as a @guint32 by this function in a @@ -57180,6 +58118,9 @@ and `O_NONBLOCK`. Prior to GLib 2.78, only `FD_CLOEXEC` was supported — i you wanted to configure `O_NONBLOCK` then that had to be done separately with `fcntl()`. +Since GLib 2.80, the constants %G_UNIX_PIPE_END_READ and +%G_UNIX_PIPE_END_WRITE can be used as mnemonic indexes in @fds. + It is a programmer error to call this function with unsupported flags, and a critical warning will be raised. @@ -57536,7 +58477,7 @@ returned string should be freed when no longer needed. Parses @uri_string according to @flags, to determine whether it is a valid -[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved +[absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved relative to another URI using g_uri_parse_relative(). If it’s not a valid URI, an error is returned explaining how it’s invalid. @@ -57692,7 +58633,7 @@ discarding any comments. The URIs are not validated. Parses @uri_string according to @flags. If the result is not a -valid [absolute URI][relative-absolute-uris], it will be discarded, and an +valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an error returned. a new #GUri, or NULL on error. @@ -57813,7 +58754,7 @@ all-lowercase and does not need to be freed. Parses @uri_ref according to @flags and, if it is a -[relative URI][relative-absolute-uris], resolves it relative to +[relative URI](#relative-and-absolute-uris), resolves it relative to @base_uri_string. If the result is not a valid absolute URI, it will be discarded, and an error returned. @@ -57841,7 +58782,7 @@ or NULL on error. Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -57908,7 +58849,7 @@ g_uri_split_with_user() if you want it split up. - Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) + Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces relevant to connecting to a host. See the documentation for g_uri_split() for more details; this is mostly a wrapper around that function with simpler arguments. @@ -57947,7 +58888,7 @@ or does not contain a hostname component. Parses @uri_ref (which can be an -[absolute or relative URI][relative-absolute-uris]) according to @flags, and +[absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and returns the pieces. Any component that doesn't appear in @uri_ref will be returned as %NULL (but note that all URIs always have a path component, though it may be the empty string). @@ -58961,21 +59902,28 @@ will always return %FALSE if any of the bytes of @str are nul. - - A UUID, or Universally unique identifier, is intended to uniquely -identify information in a distributed environment. For the -definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). - -The creation of UUIDs does not require a centralized authority. - -UUIDs are of relatively small size (128 bits, or 16 bytes). The -common string representation (ex: -1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. + + A wrapper for the POSIX utime() function. The utime() function +sets the access and modification timestamps of a file. -The UUID specification defines 5 versions, and calling -g_uuid_string_random() will generate a unique (or rather random) -UUID of the most common version, version 4. - +See your C library manual for more details about how utime() works +on your system. + + 0 if the operation was successful, -1 if an error occurred + + + + + a pathname in the GLib file name encoding + (UTF-8 on Windows) + + + + a pointer to a struct utimbuf. + + + + Parses the string @str and verify if it is a UUID. @@ -59053,7 +60001,7 @@ strings in sequence. A single #GVariant is parsed from the content of @text. -The format is described [here][gvariant-text]. +The format is described [here](gvariant-text-format.html). The memory at @limit will never be accessed and the parser behaves as if the character at @limit is the nul terminator. This has the @@ -59073,13 +60021,14 @@ with empty arrays). In the event that the parsing is successful, the resulting #GVariant is returned. It is never floating, and must be freed with -g_variant_unref(). +[method@GLib.Variant.unref]. In case of any error, %NULL will be returned. If @error is non-%NULL then it will be set to reflect the error that occurred. -Officially, the language understood by the parser is "any string -produced by g_variant_print()". +Officially, the language understood by the parser is “any string +produced by [method@GLib.Variant.print]”. This explicitly includes +`g_variant_print()`’s annotated types like `int64 -1000`. There may be implementation specific restrictions on deeply nested values, which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is @@ -59169,7 +60118,7 @@ function. - + @@ -59258,7 +60207,7 @@ multibyte representation is available for the given character. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -59267,23 +60216,6 @@ multibyte representation is available for the given character. - - GLib provides version information, primarily useful in configure -checks for builds that have a configure script. Applications will -not typically use the features described here. - -The GLib headers annotate deprecated APIs in a way that produces -compiler warnings if these deprecated APIs are used. The warnings -can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS -before including the glib.h header. - -GLib also provides support for building applications against -defined subsets of deprecated or new GLib APIs. Define the macro -%GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib -you want to receive warnings about deprecated APIs. Define the -macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of -GLib whose API you want to use. - An implementation of the standard fprintf() function which supports positional parameters, as specified in the Single Unix Specification. @@ -59300,7 +60232,7 @@ positional parameters, as specified in the Single Unix Specification. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -59321,7 +60253,7 @@ positional parameters, as specified in the Single Unix Specification. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -59365,7 +60297,7 @@ the Single Unix Specification. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -59390,7 +60322,7 @@ positional parameters, as specified in the Single Unix Specification. a standard printf() format string, but notice - [string precision pitfalls][string-precision] + [string precision pitfalls](string-utils.html#string-precision-pitfalls) @@ -59411,8 +60343,8 @@ positional parameters, as specified in the Single Unix Specification. Logs a warning. - Internal function used to print messages from the public g_warn_if_reached() -and g_warn_if_fail() macros. + Internal function used to print messages from the public [func@GLib.warn_if_reached] +and [func@GLib.warn_if_fail] macros. @@ -59440,10 +60372,11 @@ and g_warn_if_fail() macros. - A convenience function/macro to log a warning message. The message should -typically *not* be translated to the user's language. + A convenience function/macro to log a warning message. + +The message should typically *not* be translated to the user’s language. -This is not intended for end user error reporting. Use of #GError is +This is not intended for end user error reporting. Use of [type@GLib.Error] is preferred for that instead, as it allows calling functions to perform actions conditional on the type of error. @@ -59453,32 +60386,32 @@ other trusted programs violating protocol, invalid contents in trusted files, etc.) If attempting to deal with programmer errors (for example, incorrect function -parameters) then you should use %G_LOG_LEVEL_CRITICAL instead. +parameters) then you should use [flags@GLib.LogLevelFlags.CRITICAL] instead. -g_warn_if_reached() and g_warn_if_fail() log at %G_LOG_LEVEL_WARNING. +[func@GLib.warn_if_reached] and func@GLib.warn_if_fail] log at [flags@GLib.LogLevelFlags.WARNING]. You can make warnings fatal at runtime by setting the `G_DEBUG` environment variable (see [Running GLib Applications](glib-running.html)): -|[ - G_DEBUG=fatal-warnings gdb ./my-program -]| +``` +G_DEBUG=fatal-warnings gdb ./my-program +``` Any unrelated failures can be skipped over in [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. -If g_log_default_handler() is used as the log handler function, +If [func@GLib.log_default_handler] is used as the log handler function, a newline character will automatically be appended to @..., and need not be entered manually. -If structured logging is enabled, this will use g_log_structured(); -otherwise it will use g_log(). See -[Using Structured Logging][using-structured-logging]. +If structured logging is enabled, this will use [func@GLib.log_structured]; +otherwise it will use [func@GLib.log]. See +[Using Structured Logging](logging.html#using-structured-logging). - format string, followed by parameters to insert - into the format string (as with printf()) + format string, followed by parameters to insert into the format string + (as with `printf()`) @@ -59497,58 +60430,113 @@ warning is printed each time instead of only once. - - GLib defines several warning functions and assertions which can be used to -warn of programmer errors when calling functions, and print error messages -from command line programs. - -The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and -g_return_val_if_reached() macros are intended as pre-condition assertions, to -be used at the top of a public function to check that the function’s -arguments are acceptable. Any failure of such a pre-condition assertion is -considered a programming error on the part of the caller of the public API, -and the program is considered to be in an undefined state afterwards. They -are similar to the libc assert() function, but provide more context on -failures. - -For example: -|[<!-- language="C" --> -gboolean -g_dtls_connection_shutdown (GDtlsConnection *conn, - gboolean shutdown_read, - gboolean shutdown_write, - GCancellable *cancellable, - GError **error) -{ - // local variable declarations - - g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE); - g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); - g_return_val_if_fail (error == NULL || *error == NULL, FALSE); - - // function body - - return return_val; -} -]| - -g_print() and g_printerr() are intended to be used for -output from command line applications, since they output to standard output -and standard error by default — whereas functions like g_message() and -g_log() may be redirected to special purpose message windows, files, or the -system journal. - -If the console encoding is not UTF-8 (as specified by g_get_console_charset()) -then these functions convert the message first. Any Unicode -characters not defined by that charset are replaced by `'?'`. On Linux, -setlocale() must be called early in main() to load the encoding. This behaviour -can be changed by providing custom handlers to g_set_print_handler(), -g_set_printerr_handler() and g_log_set_handler(). - - - These functions provide some level of UNIX emulation on the -Windows platform. If your application really needs the POSIX -APIs, we suggest you try the Cygwin project. - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/GModule-2.0.gir b/GModule-2.0.gir index 11de9985..b8a64187 100644 --- a/GModule-2.0.gir +++ b/GModule-2.0.gir @@ -6,7 +6,697 @@ and/or use gtk-doc annotations. --> - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The #GModule struct is an opaque data structure to represent a [dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. @@ -141,7 +831,9 @@ basename of the file_name argument. See %G_MODULE_SUFFIX for why. Opens a module. If the module has already been opened, its reference count -is incremented. If not, the module is searched in the following order: +is incremented. If not, the module is searched using @file_name. + +Since 2.76, the search order/behavior is as follows: 1. If @file_name exists as a regular file, it is used as-is; else 2. If @file_name doesn't have the correct suffix and/or prefix for the @@ -152,10 +844,15 @@ is incremented. If not, the module is searched in the following order: libtool archive is parsed to find the actual file name, and that is used. -At the end of all this, we would have a file path that we can access on -disk, and it is opened as a module. If not, @file_name is opened as -a module verbatim in the hopes that the system implementation will somehow -be able to access it. +If, at the end of all this, we have a file path that we can access on disk, +it is opened as a module. If not, @file_name is attempted to be opened as a +module verbatim in the hopes that the system implementation will somehow be +able to access it. If that is not possible, %NULL is returned. + +Note that this behaviour was different prior to 2.76, but there is some +overlap in functionality. If backwards compatibility is an issue, kindly +consult earlier #GModule documentation for the prior search order/behavior +of @file_name. a #GModule on success, or %NULL on failure @@ -240,6 +937,22 @@ It is passed the #GModule structure. + + + + + + + + + + + + + + + + A portable way to build the filename of a module. The platform-specific prefix and suffix are added to the filename, if needed, and the result @@ -293,79 +1006,5 @@ basename of the file_name argument. See %G_MODULE_SUFFIX for why. - - These functions provide a portable way to dynamically load object files -(commonly known as 'plug-ins'). The current implementation supports all -systems that provide an implementation of dlopen() (e.g. Linux/Sun), as -well as Windows platforms via DLLs. - -A program which wants to use these functions must be linked to the -libraries output by the command `pkg-config --libs gmodule-2.0`. - -To use them you must first determine whether dynamic loading -is supported on the platform by calling g_module_supported(). -If it is, you can open a module with g_module_open(), -find the module's symbols (e.g. function names) with g_module_symbol(), -and later close the module with g_module_close(). -g_module_name() will return the file name of a currently opened module. - -If any of the above functions fail, the error status can be found with -g_module_error(). - -The #GModule implementation features reference counting for opened modules, -and supports hook functions within a module which are called when the -module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). - -If your module introduces static data to common subsystems in the running -program, e.g. through calling -`g_quark_from_static_string ("my-module-stuff")`, -it must ensure that it is never unloaded, by calling g_module_make_resident(). - -Example: Calling a function defined in a GModule -|[<!-- language="C" --> -// the function signature for 'say_hello' -typedef void (* SayHelloFunc) (const char *message); - -gboolean -just_say_hello (const char *filename, GError **error) -{ - SayHelloFunc say_hello; - GModule *module; - - module = g_module_open (filename, G_MODULE_BIND_LAZY); - if (!module) - { - g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH, - "%s", g_module_error ()); - return FALSE; - } - - if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello)) - { - g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, - "%s: %s", filename, g_module_error ()); - if (!g_module_close (module)) - g_warning ("%s: %s", filename, g_module_error ()); - return FALSE; - } - - if (say_hello == NULL) - { - g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, - "symbol say_hello is NULL"); - if (!g_module_close (module)) - g_warning ("%s: %s", filename, g_module_error ()); - return FALSE; - } - - // call our function in the module - say_hello ("Hello world!"); - - if (!g_module_close (module)) - g_warning ("%s: %s", filename, g_module_error ()); - return TRUE; - } -]| - diff --git a/GObject-2.0.gir b/GObject-2.0.gir index 007f7ff7..382cae0a 100644 --- a/GObject-2.0.gir +++ b/GObject-2.0.gir @@ -6,7 +6,7 @@ and/or use gtk-doc annotations. --> - + This is the signature of marshaller functions, required to marshall arrays of parameter values to signal emissions into C language callback @@ -115,6 +115,8 @@ names from that macro. + + @@ -169,32 +171,31 @@ initialization process. - #GBinding is the representation of a binding between a property on a -#GObject instance (or source) and another property on another #GObject + `GObject` instance (or source) and another property on another `GObject` instance (or target). Whenever the source property changes, the same value is applied to the target property; for instance, the following binding: -|[<!-- language="C" --> +```c g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_DEFAULT); -]| +``` will cause the property named "property-b" of @object2 to be updated -every time g_object_set() or the specific accessor changes the value of +every time [method@GObject.set] or the specific accessor changes the value of the property "property-a" of @object1. It is possible to create a bidirectional binding between two properties -of two #GObject instances, so that if either property changes, the +of two `GObject` instances, so that if either property changes, the other is updated as well, for instance: -|[<!-- language="C" --> +```c g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_BIDIRECTIONAL); -]| +``` will keep the two properties in sync. @@ -203,14 +204,14 @@ directions, in case of a bidirectional binding) to apply a custom transformation from the source value to the target value before applying it; for instance, the following binding: -|[<!-- language="C" --> +```c g_object_bind_property_full (adjustment1, "value", adjustment2, "value", G_BINDING_BIDIRECTIONAL, celsius_to_fahrenheit, fahrenheit_to_celsius, NULL, NULL); -]| +``` will keep the "value" property of the two adjustments in sync; the @celsius_to_fahrenheit function will be called whenever the "value" @@ -224,29 +225,27 @@ of @adjustment1. Note that #GBinding does not resolve cycles by itself; a cycle like -|[ +``` object1:propertyA -> object2:propertyB object2:propertyB -> object3:propertyC object3:propertyC -> object1:propertyA -]| +``` might lead to an infinite loop. The loop, in this particular case, -can be avoided if the objects emit the #GObject::notify signal only +can be avoided if the objects emit the `GObject::notify` signal only if the value has effectively been changed. A binding is implemented -using the #GObject::notify signal, so it is susceptible to all the -various ways of blocking a signal emission, like g_signal_stop_emission() -or g_signal_handler_block(). +using the `GObject::notify` signal, so it is susceptible to all the +various ways of blocking a signal emission, like [func@GObject.signal_stop_emission] +or [func@GObject.signal_handler_block]. A binding will be severed, and the resources it allocates freed, whenever -either one of the #GObject instances it refers to are finalized, or when +either one of the `GObject` instances it refers to are finalized, or when the #GBinding instance loses its last reference. Bindings for languages with garbage collection can use -g_binding_unbind() to explicitly release a binding between the source +[method@GObject.Binding.unbind] to explicitly release a binding between the source and target properties, instead of relying on the last reference on the -binding, source, and target instances to drop. - -#GBinding is available since GObject 2.26 +binding, source, and target instances to drop. Retrieves the #GObject instance used as the source of the binding. @@ -451,13 +450,13 @@ This enumeration can be extended at later date. - The #GBindingGroup can be used to bind multiple properties + `GBindingGroup` can be used to bind multiple properties from an object collectively. Use the various methods to bind properties from a single source object to multiple destination objects. Properties can be bound bidirectionally and are connected when the source object is set -with g_binding_group_set_source(). +with [method@GObject.BindingGroup.set_source]. Creates a new #GBindingGroup. @@ -671,6 +670,8 @@ then those roles are reversed. + + This function is provided by the user and should produce a copy of the passed in boxed structure. @@ -698,6 +699,10 @@ structure passed. + + + + Cast a function pointer to a #GCallback. @@ -809,36 +814,41 @@ accumulator, such as g_signal_accumulator_true_handled(). - A marshaller for a #GCClosure with a callback of type -`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter -denotes a flags type. + A #GClosureMarshal function for use with signals with handlers that +take a flags type as an argument and return a boolean. If you have +such a signal, you will probably also need to use an accumulator, +such as g_signal_accumulator_true_handled(). - the #GClosure to which the marshaller belongs + A #GClosure. - a #GValue which can store the returned #gboolean + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding instance and arg1 + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -887,35 +897,40 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + A #GClosureMarshal function for use with signals with handlers that +take a #GObject and a pointer and produce a string. It is highly +unlikely that your signal handler fits this description. - the #GClosure to which the marshaller belongs + A #GClosure. - a #GValue, which can store the returned string + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 3 + The length of the @param_values array. - a #GValue array holding instance, arg1 and arg2 + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -964,35 +979,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +boolean argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gboolean parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1041,35 +1060,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +argument which is any boxed pointer type. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GBoxed* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1118,35 +1141,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +character argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gchar parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1195,35 +1222,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with one +double-precision floating point argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gdouble parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1272,35 +1303,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + A #GClosureMarshal function for use with signals with a single +argument with an enumerated type. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the enumeration parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1349,35 +1384,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + A #GClosureMarshal function for use with signals with a single +argument with a flags types. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the flags parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1426,35 +1465,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with one +single-precision floating point argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gfloat parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1503,35 +1546,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gint parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1580,35 +1627,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with with a single +long integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #glong parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1657,35 +1708,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +#GObject argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GObject* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1734,35 +1789,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +argument of type #GParamSpec. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GParamSpec* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1811,35 +1870,43 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single raw +pointer argument type. + +If it is possible, it is better to use one of the more specific +functions such as g_cclosure_marshal_VOID__OBJECT() or +g_cclosure_marshal_VOID__OBJECT(). - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gpointer parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1888,35 +1955,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single string +argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gchar* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -1965,35 +2036,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +unsigned character argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #guchar parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2042,69 +2117,77 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with with a single +unsigned integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #guint parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + A #GClosureMarshal function for use with signals with an unsigned int +and a pointer as arguments. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 3 + The length of the @param_values array. - a #GValue array holding instance, arg1 and arg2 + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2196,35 +2279,39 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +unsigned long integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gulong parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2272,36 +2359,40 @@ denotes a flags type. - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + + A #GClosureMarshal function for use with signals with a single +#GVariant argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GVariant* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2350,35 +2441,38 @@ denotes a flags type. - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer user_data)`. + A #GClosureMarshal function for use with signals with no arguments. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 1 + The length of the @param_values array. - a #GValue array holding only the instance + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -2517,7 +2611,7 @@ but used automatically by GLib when specifying a %NULL marshaller. the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - + a floating reference to a new #GCClosure @@ -2542,7 +2636,7 @@ calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - + a new #GCClosure @@ -2563,7 +2657,7 @@ and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - + a new #GCClosure @@ -2583,7 +2677,7 @@ after the object is is freed. the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - + a floating reference to a new #GCClosure @@ -2637,6 +2731,8 @@ Use G_CALLBACK() to cast the callback function to a #GCallback. + + A callback function used by the type system to finalize a class. @@ -2774,7 +2870,7 @@ time. - A #GClosure represents a callback supplied by the programmer. + A `GClosure` represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to @@ -2844,12 +2940,12 @@ callback function/data pointer combination: Indicates whether the closure is currently being invoked with - g_closure_invoke() + g_closure_invoke() Indicates whether the closure has been invalidated by - g_closure_invalidate() + g_closure_invalidate() @@ -2890,7 +2986,7 @@ callback function/data pointer combination: @data field of the closure and calls g_object_watch_closure() on @object and the created closure. This function is mainly useful when implementing new types of closures. - + a newly allocated #GClosure @@ -2945,7 +3041,7 @@ MyClosure *my_closure_new (gpointer data) return my_closure; } ]| - + a floating reference to a new #GClosure @@ -4184,8 +4280,8 @@ static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) GType gtk_gadget_get_type (void) { - static gsize static_g_define_type_id = 0; - if (g_once_init_enter (&static_g_define_type_id)) + static GType static_g_define_type_id = 0; + if (g_once_init_enter_pointer (&static_g_define_type_id)) { GType g_define_type_id = g_type_register_static_simple (GTK_TYPE_WIDGET, @@ -4205,7 +4301,7 @@ gtk_gadget_get_type (void) }; g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); } - g_once_init_leave (&static_g_define_type_id, g_define_type_id); + g_once_init_leave_pointer (&static_g_define_type_id, g_define_type_id); } return static_g_define_type_id; } @@ -4271,18 +4367,702 @@ getter function `t_n_get_instance_private()`. See also: G_ADD_PRIVATE() - - The name of the new type, in Camel case. + + The name of the new type, in Camel case. + + + The name of the new type, in lowercase, with words + separated by `_`. + + + The #GType of the parent type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - The name of the new type, in lowercase, with words - separated by `_`. + + + + + - - The #GType of the parent type. + + + + + + + + + + + Casts a derived #GEnumClass structure into a #GEnumClass structure. @@ -4348,6 +5128,8 @@ nickname. + + Casts a derived #GFlagsClass structure into a #GFlagsClass structure. @@ -4409,6 +5191,10 @@ nickname. + + + + A convenience macro to ease interface addition in the `_C_` section of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). @@ -4472,6 +5258,22 @@ certain runtime checks to identify invalid casts. + + + + + + + + + + + + + + + + @@ -5038,6 +5840,18 @@ zeros before this function is called. + + + + + + + + + + + + Casts a #GObject or derived pointer into a (GObject*) pointer. @@ -5127,16 +5941,26 @@ properties in set_property() and get_property() implementations. The base object type. -All the fields in the `GObject` structure are private to the implementation -and should never be accessed directly. +`GObject` is the fundamental type providing the common attributes and +methods for all object types in GTK, Pango and other libraries +based on GObject. The `GObject` class provides methods for object +construction and destruction, property access methods, and signal +support. Signals are described in detail [here][gobject-Signals]. -Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the -alignment of the largest basic GLib type (typically this is #guint64 or -#gdouble). If you need larger alignment for an element in a #GObject, you -should allocate it on the heap (aligned), or arrange for your #GObject to be -appropriately padded. This guarantee applies to the #GObject (or derived) -struct, the #GObjectClass (or derived) struct, and any private data allocated -by G_ADD_PRIVATE(). +For a tutorial on implementing a new `GObject` class, see [How to define and +implement a new GObject](tutorial.html#how-to-define-and-implement-a-new-gobject). +For a list of naming conventions for GObjects and their methods, see the +[GType conventions](concepts.html#conventions). For the high-level concepts +behind GObject, read +[Instantiatable classed types: Objects](concepts.html#instantiatable-classed-types-objects). + +Since GLib 2.72, all `GObject`s are guaranteed to be aligned to at least the +alignment of the largest basic GLib type (typically this is `guint64` or +`gdouble`). If you need larger alignment for an element in a `GObject`, you +should allocate it on the heap (aligned), or arrange for your `GObject` to be +appropriately padded. This guarantee applies to the `GObject` (or derived) +struct, the `GObjectClass` (or derived) struct, and any private data allocated +by `G_ADD_PRIVATE()`. Creates a new instance of a #GObject subtype and sets its properties. @@ -5351,10 +6175,10 @@ g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). a - pointer to an array of pointers to #GParamSpec - structures. The paramspecs are owned by GLib, but the - array should be freed with g_free() when you are done with - it. + pointer to an array of pointers to #GParamSpec + structures. The paramspecs are owned by GLib, but the + array should be freed with g_free() when you are done with + it. @@ -5507,7 +6331,14 @@ Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there -is important state in the proxy object. +is important state in the proxy object. + +Note that if you unref the object on another thread, then @notify might +still be invoked after g_object_remove_toggle_ref(), and the object argument +might be a dangling pointer. If the object is destroyed on other threads, +you must take care of that yourself. + +A g_object_add_toggle_ref() must be released with g_object_remove_toggle_ref(). @@ -6161,7 +6992,7 @@ g_object_class_install_property() inside a static array, e.g.: static void my_object_class_init (MyObjectClass *klass) { - properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", + properties[PROP_FOO] = g_param_spec_int ("foo", NULL, NULL, 0, 100, 50, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -6233,7 +7064,12 @@ under the same conditions as for g_object_ref(). Removes a reference added with g_object_add_toggle_ref(). The -reference count of the object is decreased by one. +reference count of the object is decreased by one. + +Note that if you unref the object on another thread, then @notify might +still be invoked after g_object_remove_toggle_ref(), and the object argument +might be a dangling pointer. If the object is destroyed on other threads, +you must take care of that yourself. @@ -7107,13 +7943,13 @@ my_object_class_init (MyObjectClass *klass) GObjectClass *gobject_class = G_OBJECT_CLASS (klass); obj_properties[PROP_FOO] = - g_param_spec_int ("foo", "Foo", "Foo", + g_param_spec_int ("foo", NULL, NULL, -1, G_MAXINT, 0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); obj_properties[PROP_BAR] = - g_param_spec_string ("bar", "Bar", "Bar", + g_param_spec_string ("bar", NULL, NULL, NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); @@ -7319,6 +8155,8 @@ g_param_spec_get_redirect_target(). + + Mask containing the bits of #GParamSpec.flags which are reserved for GLib. @@ -7690,17 +8528,16 @@ See also: %G_PARAM_STATIC_STRINGS - #GParamSpec is an object structure that encapsulates the metadata -required to specify parameters, such as e.g. #GObject properties. + `GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties. -## Parameter names # {#canonical-parameter-names} +## Parameter names A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first character of a property name must be a letter. These are the same rules as -for signal naming (see g_signal_new()). +for signal naming (see [func@GObject.signal_new]). -When creating and looking up a #GParamSpec, either separator can be +When creating and looking up a `GParamSpec`, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient, and is the ‘canonical form’. Using `_` is discouraged. @@ -8065,7 +8902,7 @@ required to update user data pointers with a destroy notifier. - private #GTypeInstance portion + private `GTypeInstance` portion @@ -8073,15 +8910,15 @@ required to update user data pointers with a destroy notifier. - #GParamFlags flags for this parameter + `GParamFlags` flags for this parameter - the #GValue type for this parameter + the `GValue` type for this parameter - #GType type that uses (introduces) this parameter + `GType` type that uses (introduces) this parameter @@ -8425,6 +9262,18 @@ quickly accessed by owner and name. The implementation of the #GObject property system uses such a pool to store the #GParamSpecs of the properties all object types. + + Frees the resources allocated by a #GParamSpecPool. + + + + + + a #GParamSpecPool + + + + Inserts a #GParamSpec in the pool. @@ -8822,6 +9671,16 @@ to hand parameter name/value pairs to g_object_newv(). + + + + + + + + + + A mask for all #GSignalFlags bits. @@ -8956,9 +9815,10 @@ You may not attach these to signals created with the %G_SIGNAL_NO_HOOKS flag. - #GSignalGroup manages to simplify the process of connecting -many signals to a #GObject as a group. As such there is no API -to disconnect a signal from the group. + `GSignalGroup` manages a collection of signals on a `GObject`. + +`GSignalGroup` simplifies the process of connecting many signals to a `GObject` +as a group. As such there is no API to disconnect a signal from the group. In particular, this allows you to: @@ -8967,12 +9827,12 @@ In particular, this allows you to: - Block and unblock signals as a group - Ensuring that blocked state transfers across target instances. -One place you might want to use such a structure is with #GtkTextView and -#GtkTextBuffer. Often times, you'll need to connect to many signals on -#GtkTextBuffer from a #GtkTextView subclass. This allows you to create a +One place you might want to use such a structure is with `GtkTextView` and +`GtkTextBuffer`. Often times, you'll need to connect to many signals on +`GtkTextBuffer` from a `GtkTextView` subclass. This allows you to create a signal group during instance construction, simply bind the -#GtkTextView:buffer property to #GSignalGroup:target and connect -all the signals you need. When the #GtkTextView:buffer property changes +`GtkTextView:buffer` property to `GSignalGroup:target` and connect +all the signals you need. When the `GtkTextView:buffer` property changes all of the signals will be transitioned correctly. Creates a new #GSignalGroup for target instances of @target_type. @@ -9354,6 +10214,55 @@ See also: g_signal_query() + + + Set the callback for a source as a #GClosure. + +If the source is not one of the standard GLib types, the @closure_callback +and @closure_marshal fields of the #GSourceFuncs structure must have been +filled in with pointers to appropriate functions. + + + + + + the source + + + + a #GClosure + + + + + + Sets a dummy callback for @source. The callback will do nothing, and +if the source expects a #gboolean return value, it will return %TRUE. +(If the source expects any other type of return value, it will return +a 0/%NULL value; whatever g_value_init() initializes a #GValue to for +that type.) + +If the source is not one of the standard GLib types, the +@closure_callback and @closure_marshal fields of the #GSourceFuncs +structure must have been filled in with pointers to appropriate +functions. + + + + + + the source + + + + + + + + + + + Checks that @g_class is a class structure of the type identified by @g_type and issues a warning if this is not the case. Returns @g_class casted @@ -9492,7 +10401,7 @@ This macro should only be used in type implementations. A bit in the type number that's supposed to be left untouched. - + Get the type identifier from a given @class structure. @@ -9535,7 +10444,7 @@ thus they are the roots of distinct inheritance hierarchies. - + An integer constant that represents the number of identifiers reserved for types that are assigned at compile-time. @@ -9851,6 +10760,10 @@ G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. type id with G_TYPE_MAKE_FUNDAMENTAL(). + + + + A callback function used for notification when the state of a toggle reference changes. @@ -9877,7 +10790,31 @@ See also: g_object_add_toggle_ref() - + + + + A union holding one collected value. + + the field for holding integer values + + + + the field for holding long integer values + + + + the field for holding 64 bit integer values + + + + the field for holding floating point values + + + + the field for holding pointers + + + An opaque structure used as the base of all classes. @@ -10439,36 +11376,37 @@ See g_type_add_interface_check(). - #GTypeModule provides a simple implementation of the #GTypePlugin + `GTypeModule` provides a simple implementation of the `GTypePlugin` interface. -The model of #GTypeModule is a dynamically loaded module which +The model of `GTypeModule` is a dynamically loaded module which implements some number of types and interface implementations. When the module is loaded, it registers its types and interfaces -using g_type_module_register_type() and g_type_module_add_interface(). +using [method@GObject.TypeModule.register_type] and +[method@GObject.TypeModule.add_interface]. As long as any instances of these types and interface implementations are in use, the module is kept loaded. When the types and interfaces are gone, the module may be unloaded. If the types and interfaces become used again, the module will be reloaded. Note that the last reference cannot be released from within the module code, since that -would lead to the caller's code being unloaded before g_object_unref() +would lead to the caller's code being unloaded before `g_object_unref()` returns to it. Keeping track of whether the module should be loaded or not is done by using a use count - it starts at zero, and whenever it is greater than zero, the module is loaded. The use count is maintained internally by the type system, but also can be explicitly controlled by -g_type_module_use() and g_type_module_unuse(). Typically, when loading -a module for the first type, g_type_module_use() will be used to load -it so that it can initialize its types. At some later point, when the -module no longer needs to be loaded except for the type -implementations it contains, g_type_module_unuse() is called. +[method@GObject.TypeModule.use] and [method@GObject.TypeModule.unuse]. +Typically, when loading a module for the first type, `g_type_module_use()` +will be used to load it so that it can initialize its types. At some later +point, when the module no longer needs to be loaded except for the type +implementations it contains, `g_type_module_unuse()` is called. -#GTypeModule does not actually provide any implementation of module +`GTypeModule` does not actually provide any implementation of module loading and unloading. To create a particular module type you must -derive from #GTypeModule and implement the load and unload functions -in #GTypeModuleClass. +derive from `GTypeModule` and implement the load and unload functions +in `GTypeModuleClass`. @@ -10769,45 +11707,45 @@ It goes as follows: 1. The type is initially introduced (usually upon loading the module the first time, or by your main application that knows what modules introduces what types), like this: - |[<!-- language="C" --> + ```c new_type_id = g_type_register_dynamic (parent_type_id, "TypeName", new_type_plugin, type_flags); - ]| - where @new_type_plugin is an implementation of the - #GTypePlugin interface. + ``` + where `new_type_plugin` is an implementation of the + `GTypePlugin` interface. 2. The type's implementation is referenced, e.g. through - g_type_class_ref() or through g_type_create_instance() (this is - being called by g_object_new()) or through one of the above done on - a type derived from @new_type_id. + [func@GObject.TypeClass.ref] or through [func@GObject.type_create_instance] + (this is being called by [ctor@GObject.Object.new]) or through one of the above + done on a type derived from `new_type_id`. -3. This causes the type system to load the type's implementation by - calling g_type_plugin_use() and g_type_plugin_complete_type_info() - on @new_type_plugin. +3. This causes the type system to load the type's implementation by calling + [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info] + on `new_type_plugin`. -4. At some point the type's implementation isn't required anymore, - e.g. after g_type_class_unref() or g_type_free_instance() (called - when the reference count of an instance drops to zero). +4. At some point the type's implementation isn't required anymore, e.g. after + [method@GObject.TypeClass.unref] or [func@GObject.type_free_instance] + (called when the reference count of an instance drops to zero). 5. This causes the type system to throw away the information retrieved - from g_type_plugin_complete_type_info() and then it calls - g_type_plugin_unuse() on @new_type_plugin. + from [method@GObject.TypePlugin.complete_type_info] and then it calls + [method@GObject.TypePlugin.unuse] on `new_type_plugin`. 6. Things may repeat from the second step. -So basically, you need to implement a #GTypePlugin type that +So basically, you need to implement a `GTypePlugin` type that carries a use_count, once use_count goes from zero to one, you need to load the implementation to successfully handle the upcoming -g_type_plugin_complete_type_info() call. Later, maybe after +[method@GObject.TypePlugin.complete_type_info] call. Later, maybe after succeeding use/unuse calls, once use_count drops to zero, you can unload the implementation again. The type system makes sure to call -g_type_plugin_use() and g_type_plugin_complete_type_info() again -when the type is needed again. +[method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info] +again when the type is needed again. -#GTypeModule is an implementation of #GTypePlugin that already -implements most of this except for the actual module loading and +[class@GObject.TypeModule] is an implementation of `GTypePlugin` that +already implements most of this except for the actual module loading and unloading. It even handles multiple registered types per module. Calls the @complete_interface_info function from the @@ -11342,6 +12280,119 @@ that implements or has internal knowledge of the implementation of + + + + + + + + + + + + + + + + + + + + Collects a variable argument value from a `va_list`. + +We have to implement the varargs collection as a macro, because on some systems +`va_list` variables cannot be passed by reference. + +Note: If you are creating the @value argument just before calling this macro, +you should use the G_VALUE_COLLECT_INIT() variant and pass the uninitialized +#GValue. That variant is faster than G_VALUE_COLLECT(). + + + a #GValue return location. @value is supposed to be initialized + according to the value type to be collected + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the collect_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error messages if something fails + + + + + The maximal number of #GTypeCValues which can be collected for a +single #GValue. + + + + Collects a variable argument value from a `va_list`. + +We have to implement the varargs collection as a macro, because on some +systems `va_list` variables cannot be passed by reference. + + + a #GValue return location. @value must contain only 0 bytes. + + + the #GType to use for @value. + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the collect_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error messages if something fails + + + + + A variant of G_VALUE_COLLECT_INIT() that provides the #GTypeValueTable +to the caller. + + + a #GValue return location. @value must contain only 0 bytes. + + + a #GTypeValueTable pointer that will be set to the value table + for @_value_type + + + the #GType to use for @value. + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the collect_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error messages if something fails + + + + + Skip an argument of type @_value_type from @var_args. + + + the #GType of the value to skip + + + the va_list variable; it may be evaluated multiple times + + + Checks if @value holds (or contains) a value of @type. This macro will also check for @value != %NULL and issue a @@ -11529,6 +12580,28 @@ exist for the duration of the process. See g_value_set_interned_string(). + + Stores a value’s value into one or more argument locations from a `va_list`. + +This is the inverse of G_VALUE_COLLECT(). + + + a #GValue to store into the @var_args; this must be initialized + and set + + + the va_list variable; it may be evaluated multiple times + + + flags which are passed on to the lcopy_value() function of + the #GTypeValueTable of @value. + + + a #gchar** variable that will be modified to hold a g_new() + allocated error message if something fails + + + If passed to G_VALUE_COLLECT(), allocated data won't be copied but used verbatim. This does not affect ref-counted types like @@ -12558,6 +13631,28 @@ If the variant is floating, it is consumed. + + Steal ownership on contents of a %G_TYPE_STRING #GValue. +As a result of this operation the value's contents will be reset to %NULL. + +The purpose of this call is to provide a way to avoid an extra copy +when some object have been serialized into string through #GValue API. + +NOTE: for safety and compatibility purposes, if #GValue contains +static string, or an interned one, this function will return a copy +of the string. Otherwise the transfer notation would be ambiguous. + + string content of @value; + Should be freed with g_free() when no longer needed. + + + + + a valid #GValue of type %G_TYPE_STRING + + + + Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and takes over the ownership of the caller’s reference to @v_boxed; @@ -12760,8 +13855,32 @@ transformation function must be registered. - - A #GValueArray contains an array of #GValue elements. + + A `GValueArray` is a container structure to hold an array of generic values. + +The prime purpose of a `GValueArray` is for it to be used as an +object property that holds an array of values. A `GValueArray` wraps +an array of `GValue` elements in order for it to be used as a boxed +type through `G_TYPE_VALUE_ARRAY`. + +`GValueArray` is deprecated in favour of `GArray` since GLib 2.32. +It is possible to create a `GArray` that behaves like a `GValueArray` +by using the size of `GValue` as the element size, and by setting +[method@GObject.Value.unset] as the clear function using +[func@GLib.Array.set_clear_func], for instance, the following code: + +```c + GValueArray *array = g_value_array_new (10); +``` + +can be replaced by: + +```c + GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); + g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); +``` + Use `GArray` instead, if possible for the given use case, + as described above. number of values contained in the array @@ -12983,6 +14102,12 @@ g_value_register_transform_func(). + + + + + + A #GWeakNotify function can be added to an object as a callback that gets triggered when the object is finalized. @@ -13202,7 +14327,7 @@ This macro should only be used in regression tests. - + This function creates a new %G_TYPE_BOXED derived type id for a new boxed type with name @name. @@ -13221,11 +14346,11 @@ will create the appropriate `*_get_type()` function for the boxed type. Name of the new boxed type. - + Boxed structure copy function. - + Boxed structure free function. @@ -13272,716 +14397,805 @@ accumulator, such as g_signal_accumulator_true_handled(). - A marshaller for a #GCClosure with a callback of type -`gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter -denotes a flags type. + A #GClosureMarshal function for use with signals with handlers that +take a flags type as an argument and return a boolean. If you have +such a signal, you will probably also need to use an accumulator, +such as g_signal_accumulator_true_handled(). - the #GClosure to which the marshaller belongs + A #GClosure. - a #GValue which can store the returned #gboolean + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding instance and arg1 + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + A #GClosureMarshal function for use with signals with handlers that +take a #GObject and a pointer and produce a string. It is highly +unlikely that your signal handler fits this description. - the #GClosure to which the marshaller belongs + A #GClosure. - a #GValue, which can store the returned string + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 3 + The length of the @param_values array. - a #GValue array holding instance, arg1 and arg2 + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +boolean argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gboolean parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +argument which is any boxed pointer type. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GBoxed* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +character argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gchar parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with one +double-precision floating point argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gdouble parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + A #GClosureMarshal function for use with signals with a single +argument with an enumerated type. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the enumeration parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + A #GClosureMarshal function for use with signals with a single +argument with a flags types. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the flags parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with one +single-precision floating point argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gfloat parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gint parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with with a single +long integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #glong parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +#GObject argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GObject* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +argument of type #GParamSpec. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GParamSpec* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single raw +pointer argument type. + +If it is possible, it is better to use one of the more specific +functions such as g_cclosure_marshal_VOID__OBJECT() or +g_cclosure_marshal_VOID__OBJECT(). - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gpointer parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single string +argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gchar* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +unsigned character argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #guchar parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with with a single +unsigned integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #guint parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + A #GClosureMarshal function for use with signals with an unsigned int +and a pointer as arguments. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 3 + The length of the @param_values array. - a #GValue array holding instance, arg1 and arg2 + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + A #GClosureMarshal function for use with signals with a single +unsigned long integer argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #gulong parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + + A #GClosureMarshal function for use with signals with a single +#GVariant argument. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 2 + The length of the @param_values array. - a #GValue array holding the instance and the #GVariant* parameter + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() - A marshaller for a #GCClosure with a callback of type -`void (*callback) (gpointer instance, gpointer user_data)`. + A #GClosureMarshal function for use with signals with no arguments. - the #GClosure to which the marshaller belongs + A #GClosure. - ignored + A #GValue to store the return value. May be %NULL + if the callback of closure doesn't return a value. - 1 + The length of the @param_values array. - a #GValue array holding only the instance + An array of #GValues holding the arguments + on which to invoke the callback of closure. - the invocation hint given as the last argument - to g_closure_invoke() + The invocation hint given as the last argument to + g_closure_invoke(). - additional data specified when registering the marshaller + Additional data specified when registering the + marshaller, see g_closure_set_marshal() and + g_closure_set_meta_marshal() @@ -14032,7 +15246,7 @@ but used automatically by GLib when specifying a %NULL marshaller. the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - + a floating reference to a new #GCClosure @@ -14057,7 +15271,7 @@ calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - + a new #GCClosure @@ -14078,7 +15292,7 @@ and calls g_object_watch_closure() on @object and the created closure. This function is useful when you have a callback closely associated with a #GObject, and want the callback to no longer run after the object is is freed. - + a new #GCClosure @@ -14098,7 +15312,7 @@ after the object is is freed. the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. - + a floating reference to a new #GCClosure @@ -14321,35 +15535,6 @@ may change in the future. - - The GLib type system provides fundamental types for enumeration and -flags types. (Flags types are like enumerations, but allow their -values to be combined by bitwise or). A registered enumeration or -flags type associates a name and a nickname with each allowed -value, and the methods g_enum_get_value_by_name(), -g_enum_get_value_by_nick(), g_flags_get_value_by_name() and -g_flags_get_value_by_nick() can look up values by their name or -nickname. When an enumeration or flags type is registered with the -GLib type system, it can be used as value type for object -properties, using g_param_spec_enum() or g_param_spec_flags(). - -GObject ships with a utility called [glib-mkenums][glib-mkenums], -that can construct suitable type registration functions from C enumeration -definitions. - -Example of how to get a string representation of an enum value: -|[<!-- language="C" --> -GEnumClass *enum_class; -GEnumValue *enum_value; - -enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); -enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); - -g_print ("Name: %s\n", enum_value->value_name); - -g_type_class_unref (enum_class); -]| - This function is meant to be called from the complete_type_info() function of a #GTypePlugin implementation, see the example for @@ -14472,282 +15657,11 @@ may change in the future. - - #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. 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(). - - - The #GValue structure is basically a variable container that consists -of a type identifier and a specific value of that type. - -The type identifier within a #GValue structure always determines the -type of the associated value. - -To create an undefined #GValue structure, simply create a zero-filled -#GValue structure. To initialize the #GValue, use the g_value_init() -function. A #GValue cannot be used until it is initialized. Before -destruction you must always use g_value_unset() to make sure allocated -memory is freed. - -The basic type operations (such as freeing and copying) are determined -by the #GTypeValueTable associated with the type ID stored in the #GValue. -Other #GValue operations (such as converting values between types) are -provided by this interface. - -The code in the example program below demonstrates #GValue's -features. - -|[<!-- language="C" --> -#include <glib-object.h> - -static void -int2string (const GValue *src_value, - GValue *dest_value) -{ - if (g_value_get_int (src_value) == 42) - g_value_set_static_string (dest_value, "An important number"); - else - g_value_set_static_string (dest_value, "What's that?"); -} - -int -main (int argc, - char *argv[]) -{ - // GValues must be initialized - GValue a = G_VALUE_INIT; - GValue b = G_VALUE_INIT; - const gchar *message; - - // The GValue starts empty - g_assert (!G_VALUE_HOLDS_STRING (&a)); - - // Put a string in it - g_value_init (&a, G_TYPE_STRING); - g_assert (G_VALUE_HOLDS_STRING (&a)); - g_value_set_static_string (&a, "Hello, world!"); - g_printf ("%s\n", g_value_get_string (&a)); - - // Reset it to its pristine state - g_value_unset (&a); - - // It can then be reused for another type - g_value_init (&a, G_TYPE_INT); - g_value_set_int (&a, 42); - - // Attempt to transform it into a GValue of type STRING - g_value_init (&b, G_TYPE_STRING); - - // An INT is transformable to a STRING - g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); - - g_value_transform (&a, &b); - g_printf ("%s\n", g_value_get_string (&b)); - - // Attempt to transform it again using a custom transform function - g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - g_value_transform (&a, &b); - g_printf ("%s\n", g_value_get_string (&b)); - return 0; -} -]| - -See also [gobject-Standard-Parameter-and-Value-Types] for more information on -validation of #GValue. - -For letting a #GValue own (and memory manage) arbitrary types or pointers, -they need to become a [boxed type][gboxed]. The example below shows how -the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed]. - -|[<!-- language="C" --> -typedef struct { ... } MyStruct; -G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) - -// These two lines normally go in a public header. By GObject convention, -// the naming scheme is NAMESPACE_TYPE_NAME: -#define MY_TYPE_STRUCT (my_struct_get_type ()) -GType my_struct_get_type (void); - -void -foo () -{ - GValue *value = g_new0 (GValue, 1); - g_value_init (value, MY_TYPE_STRUCT); - g_value_set_boxed (value, mystruct); - // [... your code ....] - g_value_unset (value); - g_free (value); -} -]| - - - The GType API is the foundation of the GObject system. It provides the -facilities for registering and managing all fundamental data types, -user-defined object and interface types. - -For type creation and registration purposes, all types fall into one of -two categories: static or dynamic. Static types are never loaded or -unloaded at run-time as dynamic types may be. Static types are created -with g_type_register_static() that gets type specific information passed -in via a #GTypeInfo structure. - -Dynamic types are created with g_type_register_dynamic() which takes a -#GTypePlugin structure instead. The remaining type information (the -#GTypeInfo structure) is retrieved during runtime through #GTypePlugin -and the g_type_plugin_*() API. - -These registration functions are usually called only once from a -function whose only purpose is to return the type identifier for a -specific class. Once the type (or class or interface) is registered, -it may be instantiated, inherited, or implemented depending on exactly -what sort of type it is. - -There is also a third registration function for registering fundamental -types called g_type_register_fundamental() which requires both a #GTypeInfo -structure and a #GTypeFundamentalInfo structure but it is seldom used -since most fundamental types are predefined rather than user-defined. - -Type instance and class structs are limited to a total of 64 KiB, -including all parent types. Similarly, type instances' private data -(as created by G_ADD_PRIVATE()) are limited to a total of -64 KiB. If a type instance needs a large static buffer, allocate it -separately (typically by using #GArray or #GPtrArray) and put a pointer -to the buffer in the structure. - -As mentioned in the [GType conventions][gtype-conventions], type names must -be at least three characters long. There is no upper length limit. The first -character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent -characters can be letters, numbers or any of ‘-_+’. - -# Runtime Debugging - -When `G_ENABLE_DEBUG` is defined during compilation, the GObject library -supports an environment variable `GOBJECT_DEBUG` that can be set to a -combination of flags to trigger debugging messages about -object bookkeeping and signal emissions during runtime. - -The currently supported flags are: - - `objects`: Tracks all #GObject instances in a global hash table called - `debug_objects_ht`, and prints the still-alive objects on exit. - - `instance-count`: Tracks the number of instances of every #GType and makes - it available via the g_type_get_instance_count() function. - - `signals`: Currently unused. - - - GObject is the fundamental type providing the common attributes and -methods for all object types in GTK, Pango and other libraries -based on GObject. The GObject class provides methods for object -construction and destruction, property access methods, and signal -support. Signals are described in detail [here][gobject-Signals]. - -For a tutorial on implementing a new GObject class, see [How to define and -implement a new GObject][howto-gobject]. For a list of naming conventions for -GObjects and their methods, see the [GType conventions][gtype-conventions]. -For the high-level concepts behind GObject, read [Instantiatable classed types: -Objects][gtype-instantiatable-classed]. - -## 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 -claimed to be "owned" by any code portion. The main motivation for -providing floating references is C convenience. In particular, it -allows code to be written as: - -|[<!-- language="C" --> -container = create_container (); -container_add_child (container, create_child()); -]| - -If container_add_child() calls g_object_ref_sink() on the passed-in child, -no reference of the newly created child is leaked. Without floating -references, container_add_child() can only g_object_ref() the new child, -so to implement this code without reference leaks, it would have to be -written as: - -|[<!-- language="C" --> -Child *child; -container = create_container (); -child = create_child (); -container_add_child (container, child); -g_object_unref (child); -]| - -The floating reference can be converted into an ordinary reference by -calling g_object_ref_sink(). For already sunken objects (objects that -don't have a floating reference anymore), g_object_ref_sink() is equivalent -to g_object_ref() and returns a new reference. - -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. The best practice for handling -types that have initially floating references is to immediately sink those -references after g_object_new() returns, by checking if the #GType -inherits from #GInitiallyUnowned. For instance: - -|[<!-- language="C" --> -GObject *res = g_object_new_with_properties (gtype, - n_props, - prop_names, - prop_values); - -// or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) -if (G_IS_INITIALLY_UNOWNED (res)) - g_object_ref_sink (res); - -return res; -]| - -Some object implementations may need to save an objects floating state -across certain code portions (an example is #GtkMenu), to achieve this, -the following sequence can be used: - -|[<!-- language="C" --> -// save floating state -gboolean was_floating = g_object_is_floating (object); -g_object_ref_sink (object); -// protected code portion - -... - -// restore floating state -if (was_floating) - g_object_force_floating (object); -else - g_object_unref (object); // release previously acquired reference -]| - Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN property. In many cases, it may be more appropriate to use an enum with @@ -15667,21 +16581,6 @@ set out by @pspec. - - #GValue provides an abstract container structure which can be -copied, transformed and compared while holding a value of any -(derived) type, which is registered as a #GType with a -#GTypeValueTable in its #GTypeInfo structure. Parameter -specifications for most value types can be created as #GParamSpec -derived instances, to implement e.g. #GObject properties which -operate on #GValue containers. - -Parameter names need to start with a letter (a-z or A-Z). Subsequent -characters can be letters, numbers or a '-'. -All other characters are replaced by a '-' during construction. - -See also #GValue for more information. - Ensures that the contents of @value comply with the specifications set out by @pspec. For example, a #GParamSpecInt might require @@ -15961,7 +16860,7 @@ g_signal_override_class_handler(). The handler will be called synchronously, before the default handler of the signal. g_signal_emit() will not return control until all handlers are called. -See [memory management of signal handlers][signal-memory-management] for +See [memory management of signal handlers][signals.html#Memory_management_of_signal_handlers] for details on how to handle the return value and memory management of @data. @@ -16835,7 +17734,7 @@ be used. not associate a class method slot with this signal. - + the accumulator for this signal; may be %NULL. @@ -16900,13 +17799,13 @@ the marshaller for this signal. %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - + a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. - + the accumulator for this signal; may be %NULL. @@ -16965,7 +17864,7 @@ the marshaller for this signal. The closure to invoke on signal emission; may be %NULL. - + the accumulator for this signal; may be %NULL. @@ -16993,7 +17892,7 @@ the marshaller for this signal. - + Creates a new signal. (This is usually done in the class initializer.) See g_signal_new() for details on allowed signal names. @@ -17025,7 +17924,7 @@ the marshaller for this signal. may be %NULL - + the accumulator for this signal; may be %NULL @@ -17084,7 +17983,7 @@ parent class closure from inside the overridden one. - + Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of @instance_type with callback @class_handler. @instance_type must be derived from the @@ -17106,7 +18005,7 @@ parent class closure from inside the overridden one. for the signal. - + the handler. @@ -17253,7 +18152,7 @@ signal id for you. Creates a new closure which invokes the function found at the offset @struct_offset in the class structure of the interface or classed type identified by @itype. - + a floating reference to a new #GCClosure @@ -17269,93 +18168,7 @@ identified by @itype. - - The basic concept of the signal system is that of the emission -of a signal. Signals are introduced per-type and are identified -through strings. Signals introduced for a parent type are available -in derived types as well, so basically they are a per-type facility -that is inherited. - -A signal emission mainly involves invocation of a certain set of -callbacks in precisely defined manner. There are two main categories -of such callbacks, per-object ones and user provided ones. -(Although signals can deal with any kind of instantiatable type, I'm -referring to those types as "object types" in the following, simply -because that is the context most users will encounter signals in.) -The per-object callbacks are most often referred to as "object method -handler" or "default (signal) handler", while user provided callbacks are -usually just called "signal handler". - -The object method handler is provided at signal creation time (this most -frequently happens at the end of an object class' creation), while user -provided handlers are frequently connected and disconnected to/from a -certain signal on certain object instances. - -A signal emission consists of five stages, unless prematurely stopped: - -1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - -2. Invocation of normal user-provided signal handlers (where the @after - flag is not set) - -3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - -4. Invocation of user provided signal handlers (where the @after flag is set) - -5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - -The user-provided signal handlers are called in the order they were -connected in. - -All handlers may prematurely stop a signal emission, and any number of -handlers may be connected, disconnected, blocked or unblocked during -a signal emission. - -There are certain criteria for skipping user handlers in stages 2 and 4 -of a signal emission. - -First, user handlers may be blocked. Blocked handlers are omitted during -callback invocation, to return from the blocked state, a handler has to -get unblocked exactly the same amount of times it has been blocked before. - -Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional -@detail argument passed in to g_signal_emit() has to match the detail -argument of the signal handler currently subject to invocation. -Specification of no detail argument for signal handlers (omission of the -detail part of the signal specification upon connection) serves as a -wildcard and matches any detail argument passed in to emission. - -While the @detail argument is typically used to pass an object property name -(as with #GObject::notify), no specific format is mandated for the detail -string, other than that it must be non-empty. - -## Memory management of signal handlers # {#signal-memory-management} - -If you are connecting handlers to signals and using a #GObject instance as -your signal handler user data, you should remember to pair calls to -g_signal_connect() with calls to g_signal_handler_disconnect() or -g_signal_handlers_disconnect_by_func(). While signal handlers are -automatically disconnected when the object emitting the signal is finalised, -they are not automatically disconnected when the signal handler user data is -destroyed. If this user data is a #GObject instance, using it from a -signal handler after it has been finalised is an error. - -There are two strategies for managing such user data. The first is to -disconnect the signal handler (using g_signal_handler_disconnect() or -g_signal_handlers_disconnect_by_func()) when the user data (object) is -finalised; this has to be implemented manually. For non-threaded programs, -g_signal_connect_object() can be used to implement this automatically. -Currently, however, it is unsafe to use in threaded programs. - -The second is to hold a strong reference on the user data until after the -signal is disconnected for other reasons. This can be implemented -automatically using g_signal_connect_data(). - -The first approach is recommended, as the second approach can result in -effective memory leaks of the user data if the signal handler is never -disconnected for some reason. - - + Set the callback for a source as a #GClosure. If the source is not one of the standard GLib types, the @closure_callback @@ -17375,7 +18188,7 @@ filled in with pointers to appropriate functions. - + Sets a dummy callback for @source. The callback will do nothing, and if the source expects a #gboolean return value, it will return %TRUE. (If the source expects any other type of return value, it will return @@ -18487,29 +19300,6 @@ that implements or has internal knowledge of the implementation of - - The prime purpose of a #GValueArray is for it to be used as an -object property that holds an array of values. A #GValueArray wraps -an array of #GValue elements in order for it to be used as a boxed -type through %G_TYPE_VALUE_ARRAY. - -#GValueArray is deprecated in favour of #GArray since GLib 2.32. It -is possible to create a #GArray that behaves like a #GValueArray by -using the size of #GValue as the element size, and by setting -g_value_unset() as the clear function using g_array_set_clear_func(), -for instance, the following code: - -|[<!-- language="C" --> - GValueArray *array = g_value_array_new (10); -]| - -can be replaced by: - -|[<!-- language="C" --> - GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); - g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); -]| - Registers a value transformation function for use in g_value_transform(). A previously registered transformation function for @src_type and @dest_type @@ -18571,5 +19361,10 @@ transformation function must be registered. + + + + + diff --git a/Gdk-3.0.gir b/Gdk-3.0.gir index 84049e0b..24af73bf 100644 --- a/Gdk-3.0.gir +++ b/Gdk-3.0.gir @@ -14773,7 +14773,7 @@ See gdk_keymap_get_caps_lock_state(). - + diff --git a/Gdk-4.0.gir b/Gdk-4.0.gir index 4f5f88fc..fc9dd9d2 100644 --- a/Gdk-4.0.gir +++ b/Gdk-4.0.gir @@ -846,8 +846,9 @@ lifetime of an application, so this function is typically called on exit. Depending on the platform, the functionality may not be available unless a "clipboard manager" is running. -This function is called automatically when a [class@Gtk.Application] is -shut down, so you likely don't need to call it. +This function is called automatically when a +[GtkApplication](../gtk4/class.Application.html) +is shut down, so you likely don't need to call it. @@ -2460,7 +2461,8 @@ something about it. Cursors by themselves are not very interesting: they must be bound to a window for users to see them. This is done with [method@Gdk.Surface.set_cursor] or [method@Gdk.Surface.set_device_cursor]. Applications will typically -use higher-level GTK functions such as [method@Gtk.Widget.set_cursor] instead. +use higher-level GTK functions such as [gtk_widget_set_cursor()](../gtk4/method.Widget.set_cursor.html) +instead. Cursors are not bound to a given [class@Gdk.Display], so they can be shared. However, the appearance of cursors may vary when used on different @@ -2712,6 +2714,12 @@ The texture will be %NULL if the cursor was created from a name. + + + + + + An event related to drag and drop operations. @@ -3090,7 +3098,7 @@ This is only relevant for keyboard devices. Whether the device is represented by a cursor on the screen. - + The current modifier state of the device. @@ -3581,6 +3589,27 @@ this function will return %NULL. + + Returns the dma-buf formats that are supported on this display. + +GTK may use OpenGL or Vulkan to support some formats. +Calling this function will then initialize them if they aren't yet. + +The formats returned by this function can be used for negotiating +buffer formats with producers such as v4l, pipewire or GStreamer. + +To learn more about dma-bufs, see [class@Gdk.DmabufTextureBuilder]. + + a `GdkDmabufFormats` object + + + + + a `GdkDisplay` + + + + Gets the monitor in which the largest area of @surface resides. @@ -3854,9 +3883,9 @@ The returned array should be freed with g_free(). Indicates to the GUI environment that the application has finished loading, using a given identifier. -GTK will call this function automatically for [class@Gtk.Window] +GTK will call this function automatically for [GtkWindow](../gtk4/class.Window.html) with custom startup-notification identifier unless -[method@Gtk.Window.set_auto_startup_notification] +[gtk_window_set_auto_startup_notification()](../gtk4/method.Window.set_auto_startup_notification.html) is called to disable that feature. Using [method@Gdk.Toplevel.set_startup_id] is sufficient @@ -4023,6 +4052,10 @@ virtualized test environments. %TRUE if the display properly composites the alpha channel. + + The dma-buf formats that are supported on this display + + %TRUE if the display supports input shapes. @@ -4228,6 +4261,733 @@ backends will be used. + + Error enumeration for `GdkDmabufTexture`. + + Dmabuf support is not available, because the OS + is not Linux, or it was explicitly disabled at compile- or runtime + + + The requested format is not supported + + + GTK failed to create the resource for other + reasons + + + + + + + + + The `GdkDmabufFormats` struct provides information about +supported DMA buffer formats. + +You can query whether a given format is supported with +[method@Gdk.DmabufFormats.contains] and you can iterate +over the list of all supported formats with +[method@Gdk.DmabufFormats.get_n_formats] and +[method@Gdk.DmabufFormats.get_format]. + +The list of supported formats is sorted by preference, +with the best formats coming first. + +The list may contains (format, modifier) pairs where the modifier +is `DMA_FORMAT_MOD_INVALID`, indicating that **_implicit modifiers_** +may be used with this format. + +See [class@Gdk.DmabufTextureBuilder] for more information +about DMA buffers. + +Note that DMA buffers only exist on Linux. + + Returns whether a given format is contained in @formats. + + `TRUE` if the format specified by the arguments + is part of @formats + + + + + a `GdkDmabufFormats` + + + + a format code + + + + a format modifier + + + + + + Gets the fourcc code and modifier for a format +that is contained in @formats. + + + + + + a `GdkDmabufFormats` + + + + the index of the format to return + + + + return location for the format code + + + + return location for the format modifier + + + + + + Returns the number of formats that the @formats object +contains. + +Note that DMA buffers are a Linux concept, so on other +platforms, [method@Gdk.DmabufFormats.get_n_formats] will +always return zero. + + the number of formats + + + + + a `GdkDmabufFormats` + + + + + + Increases the reference count of @formats. + + the passed-in object + + + + + a `GdkDmabufFormats` + + + + + + Decreases the reference count of @formats. + +When the reference count reaches zero, +the object is freed. + + + + + + a `GdkDmabufFormats` + + + + + + + A `GdkTexture` representing a dma-buf object. + +To create a `GdkDmabufTexture`, use the auxiliary +[class@Gdk.DmabufTextureBuilder] object. + +Dma-buf textures can only be created on Linux. + + + + + + `GdkDmabufTextureBuilder` is a builder used to construct [class@Gdk.Texture] +objects from DMA buffers. + +DMA buffers are commonly called **_dma-bufs_**. + +DMA buffers are a feature of the Linux kernel to enable efficient buffer and +memory sharing between hardware such as codecs, GPUs, displays, cameras and the +kernel drivers controlling them. For example, a decoder may want its output to +be directly shared with the display server for rendering without a copy. + +Any device driver which participates in DMA buffer sharing, can do so as either +the exporter or importer of buffers (or both). + +The memory that is shared via DMA buffers is usually stored in non-system memory +(maybe in device's local memory or something else not directly accessible by the +CPU), and accessing this memory from the CPU may have higher-than-usual overhead. + +In particular for graphics data, it is not uncommon that data consists of multiple +separate blocks of memory, for example one block for each of the red, green and +blue channels. These blocks are called **_planes_**. DMA buffers can have up to +four planes. Even if the memory is a single block, the data can be organized in +multiple planes, by specifying offsets from the beginning of the data. + +DMA buffers are exposed to user-space as file descriptors allowing to pass them +between processes. If a DMA buffer has multiple planes, there is one file +descriptor per plane. + +The format of the data (for graphics data, essentially its colorspace) is described +by a 32-bit integer. These format identifiers are defined in the header file `drm_fourcc.h` +and commonly referred to as **_fourcc_** values, since they are identified by 4 ASCII +characters. Additionally, each DMA buffer has a **_modifier_**, which is a 64-bit integer +that describes driver-specific details of the memory layout, such as tiling or compression. + +For historical reasons, some producers of dma-bufs don't provide an explicit modifier, but +instead return `DMA_FORMAT_MOD_INVALID` to indicate that their modifier is **_implicit_**. +GTK tries to accommodate this situation by accepting `DMA_FORMAT_MOD_INVALID` as modifier. + +The operation of `GdkDmabufTextureBuilder` is quite simple: Create a texture builder, +set all the necessary properties, and then call [method@Gdk.DmabufTextureBuilder.build] +to create the new texture. + +The required properties for a dma-buf texture are + + * The width and height in pixels + + * The `fourcc` code and `modifier` which identify the format and memory layout of the dma-buf + + * The file descriptor, offset and stride for each of the planes + +`GdkDmabufTextureBuilder` can be used for quick one-shot construction of +textures as well as kept around and reused to construct multiple textures. + +For further information, see + +* The Linux kernel [documentation](https://docs.kernel.org/driver-api/dma-buf.html) + +* The header file [drm_fourcc.h](https://gitlab.freedesktop.org/mesa/drm/-/blob/main/include/drm/drm_fourcc.h) + + Creates a new texture builder. + + the new `GdkTextureBuilder` + + + + + Builds a new `GdkTexture` with the values set up in the builder. + +It is a programming error to call this function if any mandatory +property has not been set. + +If the dmabuf is not supported by GTK, %NULL will be returned and @error will be set. + +The `destroy` function gets called when the returned texture gets released. + +It is possible to call this function multiple times to create multiple textures, +possibly with changing properties in between. + +It is the responsibility of the caller to keep the file descriptors for the planes +open until the created texture is no longer used, and close them afterwards (possibly +using the @destroy notify). + +Not all formats defined in the `drm_fourcc.h` header are supported. You can use +[method@Gdk.Display.get_dmabuf_formats] to get a list of supported formats. + + a newly built `GdkTexture` or `NULL` + if the format is not supported + + + + + a `GdkDmabufTextureBuilder` + + + + destroy function to be called when the texture is + released + + + + user data to pass to the destroy function + + + + + + Returns the display that this texture builder is +associated with. + + the display + + + + + a `GdkDmabufTextureBuilder + + + + + + Gets the file descriptor for a plane. + + the file descriptor + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to get the fd for + + + + + + + Gets the format previously set via gdk_dmabuf_texture_builder_set_fourcc() +or 0 if the format wasn't set. + +The format is specified as a fourcc code. + + The format + + + + + a `GdkDmabufTextureBuilder` + + + + + + + Gets the height previously set via gdk_dmabuf_texture_builder_set_height() or +0 if the height wasn't set. + + The height + + + + + a `GdkDmabufTextureBuilder` + + + + + + Gets the modifier value. + + the modifier + + + + + a `GdkDmabufTextureBuilder` + + + + + + + Gets the number of planes. + + The number of planes + + + + + a `GdkDmabufTextureBuilder` + + + + + + Gets the offset value for a plane. + + the offset + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to get the offset for + + + + + + Whether the data is premultiplied. + + whether the data is premultiplied + + + + + a `GdkDmabufTextureBuilder` + + + + + + Gets the stride value for a plane. + + the stride + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to get the stride for + + + + + + + Gets the region previously set via gdk_dmabuf_texture_builder_set_update_region() or +%NULL if none was set. + + The region + + + + + a `GdkDmabufTextureBuilder` + + + + + + + Gets the texture previously set via gdk_dmabuf_texture_builder_set_update_texture() or +%NULL if none was set. + + The texture + + + + + a `GdkDmabufTextureBuilder` + + + + + + + Gets the width previously set via gdk_dmabuf_texture_builder_set_width() or +0 if the width wasn't set. + + The width + + + + + a `GdkDmabufTextureBuilder` + + + + + + Sets the display that this texture builder is +associated with. + +The display is used to determine the supported +dma-buf formats. + + + + + + a `GdkDmabufTextureBuilder + + + + the display + + + + + + Sets the file descriptor for a plane. + + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to set the fd for + + + + the file descriptor + + + + + + + Sets the format of the texture. + +The format is specified as a fourcc code. + +The format must be set before calling [method@Gdk.GLTextureBuilder.build]. + + + + + + a `GdkDmabufTextureBuilder` + + + + the texture's format or 0 to unset + + + + + + + Sets the height of the texture. + +The height must be set before calling [method@Gdk.GLTextureBuilder.build]. + + + + + + a `GdkDmabufTextureBuilder` + + + + the texture's height or 0 to unset + + + + + + Sets the modifier. + + + + + + a `GdkDmabufTextureBuilder` + + + + the modifier value + + + + + + + Sets the number of planes of the texture. + + + + + + a `GdkDmabufTextureBuilder` + + + + the number of planes + + + + + + Sets the offset for a plane. + + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to set the offset for + + + + the offset value + + + + + + Sets whether the data is premultiplied. + +Unless otherwise specified, all formats including alpha channels are assumed +to be premultiplied. + + + + + + a `GdkDmabufTextureBuilder` + + + + whether the data is premultiplied + + + + + + Sets the stride for a plane. + +The stride must be set for all planes before calling [method@Gdk.GLTextureBuilder.build]. + + + + + + a `GdkDmabufTextureBuilder` + + + + the plane to set the stride for + + + + the stride value + + + + + + + Sets the region to be updated by this texture. Together with +[property@Gdk.DmabufTextureBuilder:update-texture] this describes an +update of a previous texture. + +When rendering animations of large textures, it is possible that +consecutive textures are only updating contents in parts of the texture. +It is then possible to describe this update via these two properties, +so that GTK can avoid rerendering parts that did not change. + +An example would be a screen recording where only the mouse pointer moves. + + + + + + a `GdkDmabufTextureBuilder` + + + + the region to update + + + + + + + Sets the texture to be updated by this texture. See +[method@Gdk.DmabufTextureBuilder.set_update_region] for an explanation. + + + + + + a `GdkDmabufTextureBuilder` + + + + the texture to update + + + + + + + Sets the width of the texture. + +The width must be set before calling [method@Gdk.GLTextureBuilder.build]. + + + + + + a `GdkDmabufTextureBuilder` + + + + The texture's width or 0 to unset + + + + + + + + The display that this texture will be used on. + + + + + + The format of the texture, as a fourcc value. + + + + + + The height of the texture. + + + + The modifier. + + + + + + The number of planes of the texture. + +Note that you can set properties for other planes, +but they will be ignored when constructing the texture. + + + + Whether the alpha channel is premultiplied into the others. + +Only relevant if the format has alpha. + + + + + + The update region for [property@Gdk.GLTextureBuilder:update-texture]. + + + + + + The texture [property@Gdk.DmabufTextureBuilder:update-region] is an update for. + + + + + + The width of the texture. + + + + + The `GdkDrag` object represents the source of an ongoing DND operation. @@ -4670,8 +5430,8 @@ query the region that must be drawn. When using GTK, the widget system automatically places calls to gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the -use of [class@Gsk.Renderer]s, so application code does not need to call -these functions explicitly. +use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code +does not need to call these functions explicitly. @@ -4977,7 +5737,7 @@ See [method@Gdk.Drop.read_async]. a `GAsyncResult` - + return location for the used mime type @@ -5603,9 +6363,9 @@ of related touch events. A tablet pad group mode change. - - A touchpad hold gesture event, the current state - is determined by its phase field. Since: 4.6 + + A touchpad hold gesture event, the current state is determined by its phase +field. marks the end of the GdkEventType enumeration. @@ -5984,7 +6744,8 @@ of the frame. The frame is repainted. GDK normally handles this internally and emits [signal@Gdk.Surface::render] signals which are turned into -[signal@Gtk.Widget::snapshot] signals by GTK. +[GtkWidget::snapshot](../gtk4/signal.Widget.snapshot.html) signals +by GTK. @@ -6004,7 +6765,8 @@ of the frame. Animations should be updated using [method@Gdk.FrameClock.get_frame_time]. Applications can connect directly to this signal, or use -[method@Gtk.Widget.add_tick_callback] as a more convenient interface. +[gtk_widget_add_tick_callback()](../gtk4/method.Widget.add_tick_callback.html) +as a more convenient interface. @@ -6712,7 +7474,7 @@ anymore, this function has been deprecated and now always returns %NULL. Note that the GL texture must not be modified until @destroy is called, which will happen when the GdkTexture object is finalized, or due to an explicit call of [method@Gdk.GLTexture.release]. - [class@Gdk.GLTextureBuilder] supercedes this function + [class@Gdk.GLTextureBuilder] supersedes this function and provides extended functionality for creating GL textures. A newly-created @@ -6765,7 +7527,7 @@ function has been called. - `GdkGLTextureBuilder` is a buider used to construct [class@Gdk.Texture] objects from + `GdkGLTextureBuilder` is a builder used to construct [class@Gdk.Texture] objects from GL textures. The operation is quite simple: Create a texture builder, set all the necessary @@ -6818,7 +7580,7 @@ possibly with changing properties in between. - + Gets the context previously set via gdk_gl_texture_builder_set_context() or %NULL if none was set. @@ -6833,7 +7595,7 @@ possibly with changing properties in between. - + Gets the format previously set via gdk_gl_texture_builder_set_format(). The format @@ -6847,7 +7609,7 @@ possibly with changing properties in between. - + Gets whether the texture has a mipmap. Whether the texture has a mipmap @@ -6861,7 +7623,7 @@ possibly with changing properties in between. - + Gets the height previously set via gdk_gl_texture_builder_set_height() or 0 if the height wasn't set. @@ -6876,7 +7638,7 @@ possibly with changing properties in between. - + Gets the texture id previously set via gdk_gl_texture_builder_set_id() or 0 if the id wasn't set. @@ -6891,7 +7653,7 @@ possibly with changing properties in between. - + Gets the `GLsync` previously set via gdk_gl_texture_builder_set_sync(). the `GLSync` @@ -6905,7 +7667,7 @@ possibly with changing properties in between. - + Gets the region previously set via gdk_gl_texture_builder_set_update_region() or %NULL if none was set. @@ -6920,7 +7682,7 @@ possibly with changing properties in between. - + Gets the texture previously set via gdk_gl_texture_builder_set_update_texture() or %NULL if none was set. @@ -6935,7 +7697,7 @@ possibly with changing properties in between. - + Gets the width previously set via gdk_gl_texture_builder_set_width() or 0 if the width wasn't set. @@ -6950,7 +7712,7 @@ possibly with changing properties in between. - + Sets the context to be used for the texture. This is the context that owns the texture. @@ -6970,7 +7732,7 @@ The context must be set before calling [method@Gdk.GLTextureBuilder.build]. - + Sets the format of the texture. The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. The format is the preferred format the texture data should be downloaded to. The @@ -7002,7 +7764,7 @@ in GSK's shaders. - + Sets whether the texture has a mipmap. This allows the renderer and other users of the generated texture to use a higher quality downscaling. @@ -7022,7 +7784,7 @@ Typically, the `glGenerateMipmap` function is used to generate a mimap. - + Sets the height of the texture. The height must be set before calling [method@Gdk.GLTextureBuilder.build]. @@ -7041,7 +7803,7 @@ The height must be set before calling [method@Gdk.GLTextureBuilder.build]. - + Sets the texture id of the texture. The texture id must remain unmodified until the texture was finalized. See [method@Gdk.GLTextureBuilder.build] for a longer discussion. @@ -7062,7 +7824,7 @@ The id must be set before calling [method@Gdk.GLTextureBuilder.build]. - + Sets the GLSync object to use for the texture. GTK will wait on this object before using the created `GdkTexture`. @@ -7086,7 +7848,7 @@ responsibility to make sure it doesn't leak. - + Sets the region to be updated by this texture. Together with [property@Gdk.GLTextureBuilder:update-texture] this describes an update of a previous texture. @@ -7112,7 +7874,7 @@ An example would be a screen recording where only the mouse pointer moves. - + Sets the texture to be updated by this texture. See [method@Gdk.GLTextureBuilder.set_update_region] for an explanation. @@ -7130,7 +7892,7 @@ An example would be a screen recording where only the mouse pointer moves. - + Sets the width of the texture. The width must be set before calling [method@Gdk.GLTextureBuilder.build]. @@ -7149,58 +7911,58 @@ The width must be set before calling [method@Gdk.GLTextureBuilder.build]. - - + + The context owning the texture. - - + + The format when downloading the texture. - - + + If the texture has a mipmap. - - + + The height of the texture. - - + + The texture ID to use. - - + + An optional `GLSync` object. If this is set, GTK will wait on it before using the texture. - - + + The update region for [property@Gdk.GLTextureBuilder:update-texture]. - - + + The texture [property@Gdk.GLTextureBuilder:update-region] is an update for. - - + + The width of the texture. @@ -7360,6 +8122,12 @@ If this is set, GTK will wait on it before using the texture. + + + + + + @@ -14626,7 +15394,23 @@ for details). - + + 4 bytes; for alpha, blue, green, red, + The color values are premultiplied with the alpha value. Since 4.14 + + + 4 bytes; for blue, green, red, unused. Since 4.14 + + + 4 bytes; for unused, red, green, blue. Since 4.14 + + + 4 bytes; for red, green, blue, unused. Since 4.14 + + + 4 bytes; for unused, blue, green, red. Since 4.14 + + The number of formats. This value will change as more formats get added, so do not rely on its concrete integer. @@ -14680,6 +15464,9 @@ Apple, CapsLock or ShiftLock. Note that GDK may add internal values to events which include values outside of this enumeration. Your code should preserve and ignore them. You can use %GDK_MODIFIER_MASK to remove all private values. + + No modifier. + the Shift key. @@ -15147,7 +15934,8 @@ useful for implementing subclasses and should not be used by applications: This is often useful for implementing the [vfunc@Gdk.Paintable.get_current_image] virtual function when the paintable is in an incomplete state (like a -[class@Gtk.MediaStream] before receiving the first frame). +[GtkMediaStream](../gtk4/class.MediaStream.html) before receiving +the first frame). a `GdkPaintable` @@ -15855,9 +16643,9 @@ and size of the popup. You can learn about the result by calling [method@Gdk.Popup.get_position_x], [method@Gdk.Popup.get_position_y], [method@Gdk.Popup.get_rect_anchor] and [method@Gdk.Popup.get_surface_anchor] after the popup has been presented. This can be used to adjust the rendering. -For example, [class@Gtk.Popover] changes its arrow position accordingly. -But you have to be careful avoid changing the size of the popover, or it -has to be presented again. +For example, [GtkPopover](../gtk4/class.Popover.html) changes its arrow position +accordingly. But you have to be careful avoid changing the size of the popover, +or it has to be presented again. Create a popup layout description. @@ -16818,7 +17606,7 @@ A same tool may be used by several devices. Base type for snapshot operations. -The subclass of `GdkSnapshot` used by GTK is [class@Gtk.Snapshot]. +The subclass of `GdkSnapshot` used by GTK is [GtkSnapshot](../gtk4/class.Snapshot.html). @@ -16847,7 +17635,7 @@ of physical pixels on an output device are laid out. A `GdkSurface` is a rectangular region on the screen. It’s a low-level object, used to implement high-level objects -such as [class@Gtk.Window] or [class@Gtk.Dialog] in GTK. +such as [GtkWindow](../gtk4/class.Window.html). The surfaces you see in practice are either [iface@Gdk.Toplevel] or [iface@Gdk.Popup], and those interfaces provide much of the required @@ -16974,13 +17762,12 @@ or any other error occurs. - - Creates a new `GdkVulkanContext` for rendering on @surface. - -If the creation of the `GdkVulkanContext` failed, @error will be set. + + Sets an error and returns %NULL. + GTK does not expose any Vulkan internals. This + function is a leftover that was accidentally exposed. - the newly created `GdkVulkanContext`, or - %NULL on error + %NULL @@ -17221,7 +18008,7 @@ Surface size is reported in ”application pixels”, not For toplevel surfaces, withdraws them, so they will no longer be known to the window manager; for all surfaces, unmaps them, so they won’t be displayed. Normally done automatically as -part of [method@Gtk.Widget.hide]. +part of [gtk_widget_hide()](../gtk4/method.Widget.hide.html). @@ -17369,7 +18156,7 @@ This function only works for toplevel surfaces. GTK will update this property automatically if the @surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your -[vfunc@Gtk.Widget.css_changed] handler. +[GtkWidgetClass.css_changed](../gtk4/vfunc.Widget.css_changed.html) handler. @@ -17710,7 +18497,7 @@ gdk_texture_download (texture, cairo_surface_mark_dirty (surface); ``` -For more flexible download capabilites, see +For more flexible download capabilities, see [struct@Gdk.TextureDownloader]. @@ -17891,7 +18678,7 @@ use [method@Gdk.Texture.save_to_png_bytes]. [class@Gdk.Texture]. It is intended to be created as a short-term object for a single download, -but can be used for multipe downloads of different textures or with different +but can be used for multiple downloads of different textures or with different settings. `GdkTextureDownloader` can be used to convert data between different formats. @@ -18179,8 +18966,9 @@ You might use this function to implement a “window resize grip.” Sets keyboard focus to @surface. -In most cases, [method@Gtk.Window.present_with_time] should be -used on a [class@Gtk.Window], rather than calling this function. +In most cases, [gtk_window_present_with_time()](../gtk4/method.Window.present_with_time.html) +should be used on a [GtkWindow](../gtk4/class.Window.html), rather than +calling this function. @@ -18417,8 +19205,8 @@ previously called [method@Gdk.Toplevel.set_transient_for]. Sets the startup notification ID. When using GTK, typically you should use -[method@Gtk.Window.set_startup_id] instead of this -low-level function. +[gtk_window_set_startup_id()](../gtk4/method.Window.set_startup_id.html) +instead of this low-level function. @@ -18462,8 +19250,8 @@ dialog associated with the application surface @parent. This allows the window manager to do things like center @surface on @parent and keep @surface above @parent. -See [method@Gtk.Window.set_transient_for] if you’re using -[class@Gtk.Window] or [class@Gtk.Dialog]. +See [gtk_window_set_transient_for()](../gtk4/method.Window.set_transient_for.html) +if you’re using [GtkWindow](../gtk4/class.Window.html). @@ -19505,6 +20293,11 @@ call [func@Gdk.content_serialize_finish] to get the result of the operation. + + + + + Checks if @action represents a single action or includes multiple actions. @@ -19768,7 +20561,8 @@ keyvals, such as %GDK_KEY_KP_Decimal. This is often useful for implementing the [vfunc@Gdk.Paintable.get_current_image] virtual function when the paintable is in an incomplete state (like a -[class@Gtk.MediaStream] before receiving the first frame). +[GtkMediaStream](../gtk4/class.MediaStream.html) before receiving +the first frame). a `GdkPaintable` diff --git a/Gio-2.0.gir b/Gio-2.0.gir index ed02bc75..c45f8980 100644 --- a/Gio-2.0.gir +++ b/Gio-2.0.gir @@ -3,6 +3,8 @@ To affect the contents of this file, edit the original C definitions, and/or use gtk-doc annotations. --> + + @@ -13,7 +15,7 @@ and/or use gtk-doc annotations. --> - + @@ -147,35 +149,35 @@ and/or use gtk-doc annotations. --> - #GAction represents a single named action. + `GAction` represents a single named action. The main interface to an action is that it can be activated with -g_action_activate(). This results in the 'activate' signal being -emitted. An activation has a #GVariant parameter (which may be -%NULL). The correct type for the parameter is determined by a static +[method@Gio.Action.activate]. This results in the 'activate' signal being +emitted. An activation has a `GVariant` parameter (which may be +`NULL`). The correct type for the parameter is determined by a static parameter type (which is given at construction time). An action may optionally have a state, in which case the state may be -set with g_action_change_state(). This call takes a #GVariant. The +set with [method@Gio.Action.change_state]. This call takes a #GVariant. The correct type for the state is determined by a static state type (which is given at construction time). The state may have a hint associated with it, specifying its valid range. -#GAction is merely the interface to the concept of an action, as +`GAction` is merely the interface to the concept of an action, as described above. Various implementations of actions exist, including -#GSimpleAction. +[class@Gio.SimpleAction]. In all cases, the implementing class is responsible for storing the -name of the action, the parameter type, the enabled state, the -optional state type and the state and emitting the appropriate -signals when these change. The implementor is responsible for filtering -calls to g_action_activate() and g_action_change_state() for type -safety and for the state being enabled. - -Probably the only useful thing to do with a #GAction is to put it -inside of a #GSimpleActionGroup. +name of the action, the parameter type, the enabled state, the optional +state type and the state and emitting the appropriate signals when these +change. The implementor is responsible for filtering calls to +[method@Gio.Action.activate] and [method@Gio.Action.change_state] +for type safety and for the state being enabled. + +Probably the only useful thing to do with a `GAction` is to put it +inside of a [class@Gio.SimpleActionGroup]. Checks if @action_name is valid. @@ -712,25 +714,24 @@ See g_action_map_add_action_entries() for an example. - #GActionGroup represents a group of actions. Actions can be used to -expose functionality in a structured way, either from one part of a -program to another, or to the outside world. Action groups are often -used together with a #GMenuModel that provides additional -representation data for displaying the actions to the user, e.g. in -a menu. - -The main way to interact with the actions in a GActionGroup is to -activate them with g_action_group_activate_action(). Activating an -action may require a #GVariant parameter. The required type of the -parameter can be inquired with g_action_group_get_action_parameter_type(). -Actions may be disabled, see g_action_group_get_action_enabled(). + `GActionGroup` represents a group of actions. + +Actions can be used to expose functionality in a structured way, either +from one part of a program to another, or to the outside world. Action +groups are often used together with a `GMenuModel` that provides additional +representation data for displaying the actions to the user, e.g. in a menu. + +The main way to interact with the actions in a `GActionGroup` is to +activate them with [method@Gio.ActionGroup.activate_action]. Activating an +action may require a `GVariant` parameter. The required type of the +parameter can be inquired with [method@Gio.ActionGroup.get_action_parameter_type]. +Actions may be disabled, see [method@Gio.ActionGroup.get_action_enabled]. Activating a disabled action has no effect. -Actions may optionally have a state in the form of a #GVariant. The -current state of an action can be inquired with -g_action_group_get_action_state(). Activating a stateful action may -change its state, but it is also possible to set the state by calling -g_action_group_change_action_state(). +Actions may optionally have a state in the form of a #GVariant. The current +state of an action can be inquired with [method@Gio.ActionGroup.get_action_state]. +Activating a stateful action may change its state, but it is also possible to +set the state by calling [method@Gio.ActionGroup.change_action_state]. As typical example, consider a text editing application which has an option to change the current font to 'bold'. A good way to represent @@ -738,25 +739,25 @@ this would be a stateful action, with a boolean state. Activating the action would toggle the state. Each action in the group has a unique name (which is a string). All -method calls, except g_action_group_list_actions() take the name of +method calls, except [method@Gio.ActionGroup.list_actions] take the name of an action as an argument. -The #GActionGroup API is meant to be the 'public' API to the action -group. The calls here are exactly the interaction that 'external +The `GActionGroup` API is meant to be the 'public' API to the action +group. The calls here are exactly the interaction that 'external forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have -with actions. 'Internal' APIs (ie: ones meant only to be accessed by -the action group implementation) are found on subclasses. This is -why you will find - for example - g_action_group_get_action_enabled() +with actions. 'Internal' APIs (ie: ones meant only to be accessed by +the action group implementation) are found on subclasses. This is +why you will find - for example - [method@Gio.ActionGroup.get_action_enabled] but not an equivalent set() call. Signals are emitted on the action group in response to state changes on individual actions. -Implementations of #GActionGroup should provide implementations for -the virtual functions g_action_group_list_actions() and -g_action_group_query_action(). The other virtual functions should +Implementations of `GActionGroup` should provide implementations for +the virtual functions [method@Gio.ActionGroup.list_actions] and +[method@Gio.ActionGroup.query_action]. The other virtual functions should not be implemented - their "wrappers" are actually implemented with -calls to g_action_group_query_action(). +calls to [method@Gio.ActionGroup.query_action]. Emits the #GActionGroup::action-added signal on @action_group. @@ -2030,9 +2031,11 @@ actions in the group - The GActionMap interface is implemented by #GActionGroup -implementations that operate by containing a number of -named #GAction instances, such as #GSimpleActionGroup. + `GActionMap` is an interface for action containers. + +The `GActionMap` interface is implemented by [iface@Gio.ActionGroup] +implementations that operate by containing a number of named +[iface@Gio.Action] instances, such as [class@Gio.SimpleActionGroup]. One useful application of this interface is to map the names of actions from various action groups to unique, @@ -2322,32 +2325,35 @@ remove_actions (GActionMap *map) - #GAppInfo and #GAppLaunchContext are used for describing and launching + Information about an installed application and methods to launch +it (with file arguments). + +`GAppInfo` and `GAppLaunchContext` are used for describing and launching applications installed on the system. As of GLib 2.20, URIs will always be converted to POSIX paths -(using g_file_get_path()) when using g_app_info_launch() even if -the application requested an URI and not a POSIX path. For example +(using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch] +even if the application requested an URI and not a POSIX path. For example for a desktop-file based application with Exec key `totem %U` and a single URI, `sftp://foo/file.avi`, then `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will -only work if a set of suitable GIO extensions (such as gvfs 2.26 +only work if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE support), is available and operational; if this is not the case, the URI will be passed unmodified to the application. Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX -path (in gvfs there's no FUSE mount for it); such URIs will be +path (in GVfs there's no FUSE mount for it); such URIs will be passed unmodified to the application. -Specifically for gvfs 2.26 and later, the POSIX URI will be mapped -back to the GIO URI in the #GFile constructors (since gvfs -implements the #GVfs extension point). As such, if the application -needs to examine the URI, it needs to use g_file_get_uri() or -similar on #GFile. In other words, an application cannot assume -that the URI passed to e.g. g_file_new_for_commandline_arg() is -equal to the result of g_file_get_uri(). The following snippet +Specifically for GVfs 2.26 and later, the POSIX URI will be mapped +back to the GIO URI in the [iface@Gio.File] constructors (since GVfs +implements the GVfs extension point). As such, if the application +needs to examine the URI, it needs to use [method@Gio.File.get_uri] +or similar on [iface@Gio.File]. In other words, an application cannot +assume that the URI passed to e.g. [func@Gio.File.new_for_commandline_arg] +is equal to the result of [method@Gio.File.get_uri]. The following snippet illustrates this: -|[ +```c GFile *f; char *uri; @@ -2362,7 +2368,7 @@ if (g_file_has_uri_scheme (file, "cdda")) // do something special with uri } g_object_unref (file); -]| +``` This code will work when both `cdda://sr0/Track 1.wav` and `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the @@ -4094,38 +4100,41 @@ no display name is available. - #GAppInfoMonitor is a very simple object used for monitoring the app + `GAppInfoMonitor` monitors application information for changes. + +`GAppInfoMonitor` is a very simple object used for monitoring the app info database for changes (newly installed or removed applications). -Call g_app_info_monitor_get() to get a #GAppInfoMonitor and connect -to the #GAppInfoMonitor::changed signal. The signal will be emitted once when +Call [func@Gio.AppInfoMonitor.get] to get a `GAppInfoMonitor` and connect +to the [signal@Gio.AppInfoMonitor::changed] signal. The signal will be emitted once when the app info database changes, and will not be emitted again until after the -next call to g_app_info_get_all() or another `g_app_info_*()` function. This -is because monitoring the app info database for changes is expensive. - -The following functions will re-arm the #GAppInfoMonitor::changed signal so -it can be emitted again: - - g_app_info_get_all() - - g_app_info_get_all_for_type() - - g_app_info_get_default_for_type() - - g_app_info_get_fallback_for_type() - - g_app_info_get_recommended_for_type() - - g_desktop_app_info_get_implementations() - - g_desktop_app_info_new() - - g_desktop_app_info_new_from_filename() - - g_desktop_app_info_new_from_keyfile() - - g_desktop_app_info_search() +next call to [func@Gio.AppInfo.get_all] or another `g_app_info_*()` function. +This is because monitoring the app info database for changes is expensive. + +The following functions will re-arm the [signal@Gio.AppInfoMonitor::changed] +signal so it can be emitted again: + + - [func@Gio.AppInfo.get_all] + - [func@Gio.AppInfo.get_all_for_type] + - [func@Gio.AppInfo.get_default_for_type] + - [func@Gio.AppInfo.get_fallback_for_type] + - [func@Gio.AppInfo.get_recommended_for_type] + - [func@Gio.DesktopAppInfo.get_implementations] + - [ctor@Gio.DesktopAppInfo.new] + - [ctor@Gio.DesktopAppInfo.new_from_filename] + - [ctor@Gio.DesktopAppInfo.new_from_keyfile] + - [func@Gio.DesktopAppInfo.search] In the usual case, applications should try to make note of the change -(doing things like invalidating caches) but not act on it. In -particular, applications should avoid making calls to #GAppInfo APIs +(doing things like invalidating caches) but not act on it. In +particular, applications should avoid making calls to `GAppInfo` APIs in response to the change signal, deferring these until the time that -the updated data is actually required. The exception to this case is when +the updated data is actually required. The exception to this case is when application information is actually being displayed on the screen (for example, during a search or when the list of all applications is shown). -The reason for this is that changes to the list of installed -applications often come in groups (like during system updates) and -rescanning the list on every change is pointless and expensive. +The reason for this is that changes to the list of installed applications +often come in groups (like during system updates) and rescanning the list +on every change is pointless and expensive. Gets the #GAppInfoMonitor for the current thread-default main context. @@ -4633,20 +4642,23 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - A #GApplication is the foundation of an application. It wraps some + `GApplication` is the core class for application support. + +A `GApplication` is the foundation of an application. It wraps some low-level platform-specific services and is intended to act as the foundation for higher-level application classes such as -#GtkApplication or #MxApplication. In general, you should not use +`GtkApplication` or `MxApplication`. In general, you should not use this class outside of a higher level framework. -GApplication provides convenient life cycle management by maintaining +`GApplication` provides convenient life-cycle management by maintaining a "use count" for the primary application instance. The use count can -be changed using g_application_hold() and g_application_release(). If -it drops to zero, the application exits. Higher-level classes such as -#GtkApplication employ the use count to ensure that the application -stays alive as long as it has any opened windows. +be changed using [method@Gio.Application.hold] and +[method@Gio.Application.release]. If it drops to zero, the application +exits. Higher-level classes such as `GtkApplication` employ the use count +to ensure that the application stays alive as long as it has any opened +windows. -Another feature that GApplication (optionally) provides is process +Another feature that `GApplication` (optionally) provides is process uniqueness. Applications can make use of this functionality by providing a unique application ID. If given, only one application with this ID can be running at a time per session. The session @@ -4658,17 +4670,17 @@ called the "primary instance"; for non-unique applications this is always the current instance. On Linux, the D-Bus session bus is used for communication. -The use of #GApplication differs from some other commonly-used +The use of `GApplication` differs from some other commonly-used uniqueness libraries (such as libunique) in important ways. The application is not expected to manually register itself and check if it is the primary instance. Instead, the main() function of a -#GApplication should do very little more than instantiating the +`GApplication` should do very little more than instantiating the application instance, possibly connecting signal handlers, then -calling g_application_run(). All checks for uniqueness are done +calling [method@Gio.Application.run]. All checks for uniqueness are done internally. If the application is the primary instance then the startup signal is emitted and the mainloop runs. If the application is not the primary instance then a signal is sent to the primary -instance and g_application_run() promptly returns. See the code +instance and [method@Gio.Application.run] promptly returns. See the code examples below. If used, the expected form of an application identifier is the @@ -4676,35 +4688,36 @@ same as that of a [D-Bus well-known bus name](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus). Examples include: `com.example.MyApp`, `org.example.internal_apps.Calculator`, `org._7_zip.Archiver`. -For details on valid application identifiers, see g_application_id_is_valid(). +For details on valid application identifiers, see [func@Gio.Application.id_is_valid]. On Linux, the application identifier is claimed as a well-known bus name -on the user's session bus. This means that the uniqueness of your -application is scoped to the current session. It also means that your +on the user's session bus. This means that the uniqueness of your +application is scoped to the current session. It also means that your application may provide additional services (through registration of other -object paths) at that bus name. The registration of these object paths -should be done with the shared GDBus session bus. Note that due to the +object paths) at that bus name. The registration of these object paths +should be done with the shared GDBus session bus. Note that due to the internal architecture of GDBus, method calls can be dispatched at any time -(even if a main loop is not running). For this reason, you must ensure that +(even if a main loop is not running). For this reason, you must ensure that any object paths that you wish to register are registered before #GApplication attempts to acquire the bus name of your application (which happens in -g_application_register()). Unfortunately, this means that you cannot use -g_application_get_is_remote() to decide if you want to register object paths. +[method@Gio.Application.register]). Unfortunately, this means that you cannot +use [property@Gio.Application:is-remote] to decide if you want to register +object paths. -GApplication also implements the #GActionGroup and #GActionMap +`GApplication` also implements the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] interfaces and lets you easily export actions by adding them with -g_action_map_add_action(). When invoking an action by calling -g_action_group_activate_action() on the application, it is always +[method@Gio.ActionMap.add_action]. When invoking an action by calling +[method@Gio.ActionGroup.activate_action] on the application, it is always invoked in the primary instance. The actions are also exported on -the session bus, and GIO provides the #GDBusActionGroup wrapper to -conveniently access them remotely. GIO provides a #GDBusMenuModel wrapper -for remote access to exported #GMenuModels. +the session bus, and GIO provides the [class@Gio.DBusActionGroup] wrapper to +conveniently access them remotely. GIO provides a [class@Gio.DBusMenuModel] wrapper +for remote access to exported [class@Gio.MenuModel]s. Note: Due to the fact that actions are exported on the session bus, using `maybe` parameters is not supported, since D-Bus does not support `maybe` types. -There is a number of different entry points into a GApplication: +There is a number of different entry points into a `GApplication`: - via 'Activate' (i.e. just starting the application) @@ -4714,42 +4727,43 @@ There is a number of different entry points into a GApplication: - via activating an action -The #GApplication::startup signal lets you handle the application +The [signal@Gio.Application::startup] signal lets you handle the application initialization for all of these in a single place. Regardless of which of these entry points is used to start the -application, GApplication passes some ‘platform data’ from the +application, `GApplication` passes some ‘platform data’ from the launching instance to the primary instance, in the form of a -#GVariant dictionary mapping strings to variants. To use platform -data, override the @before_emit or @after_emit virtual functions -in your #GApplication subclass. When dealing with -#GApplicationCommandLine objects, the platform data is -directly available via g_application_command_line_get_cwd(), -g_application_command_line_get_environ() and -g_application_command_line_get_platform_data(). +[struct@GLib.Variant] dictionary mapping strings to variants. To use platform +data, override the [vfunc@Gio.Application.before_emit] or +[vfunc@Gio.Application.after_emit] virtual functions +in your `GApplication` subclass. When dealing with +[class@Gio.ApplicationCommandLine] objects, the platform data is +directly available via [method@Gio.ApplicationCommandLine.get_cwd], +[method@Gio.ApplicationCommandLine.get_environ] and +[method@Gio.ApplicationCommandLine.get_platform_data]. As the name indicates, the platform data may vary depending on the operating system, but it always includes the current directory (key -"cwd"), and optionally the environment (ie the set of environment -variables and their values) of the calling process (key "environ"). +`cwd`), and optionally the environment (ie the set of environment +variables and their values) of the calling process (key `environ`). The environment is only added to the platform data if the -%G_APPLICATION_SEND_ENVIRONMENT flag is set. #GApplication subclasses -can add their own platform data by overriding the @add_platform_data -virtual function. For instance, #GtkApplication adds startup notification -data in this way. +`G_APPLICATION_SEND_ENVIRONMENT` flag is set. `GApplication` subclasses +can add their own platform data by overriding the +[vfunc@Gio.Application.add_platform_data] virtual function. For instance, +`GtkApplication` adds startup notification data in this way. To parse commandline arguments you may handle the -#GApplication::command-line signal or override the local_command_line() -vfunc, to parse them in either the primary instance or the local instance, -respectively. +[signal@Gio.Application::command-line] signal or override the +[vfunc@Gio.Application.local_command_line] virtual funcion, to parse them in +either the primary instance or the local instance, respectively. -For an example of opening files with a GApplication, see +For an example of opening files with a `GApplication`, see [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c). -For an example of using actions with GApplication, see +For an example of using actions with `GApplication`, see [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c). -For an example of using extra D-Bus hooks with GApplication, see +For an example of using extra D-Bus hooks with `GApplication`, see [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). @@ -5213,8 +5227,8 @@ the options with g_variant_dict_lookup(): - a - %NULL-terminated list of #GOptionEntrys + the + main options for the application @@ -5739,7 +5753,10 @@ execution of the application, as long as @id is the same string. notifications without an id. If @notification is no longer relevant, it can be withdrawn with -g_application_withdraw_notification(). +g_application_withdraw_notification(). + +It is an error to call this function if @application has no +application ID. @@ -6039,16 +6056,20 @@ there is no need to explicitly withdraw the notification in that case. - + + The group of actions that the application exports. - + + The unique identifier for the application. - + + Flags specifying the behaviour of the application. - + + Time (in milliseconds) to stay alive after becoming idle. @@ -6056,13 +6077,16 @@ there is no need to explicitly withdraw the notification in that case. g_application_mark_busy() or g_application_bind_busy_property(). - + + Whether [method@Gio.Application.register] has been called. - + + Whether this application instance is remote. - + + The base resource path for the application. @@ -6447,30 +6471,33 @@ after registration. See g_application_register(). - #GApplicationCommandLine represents a command-line invocation of -an application. It is created by #GApplication and emitted -in the #GApplication::command-line signal and virtual function. + `GApplicationCommandLine` represents a command-line invocation of +an application. + +It is created by [class@Gio.Application] and emitted +in the [signal@Gio.Application::command-line] signal and virtual function. The class contains the list of arguments that the program was invoked -with. It is also possible to query if the commandline invocation was +with. It is also possible to query if the commandline invocation was local (ie: the current process is running in direct response to the invocation) or remote (ie: some other process forwarded the commandline to this process). -The GApplicationCommandLine object can provide the @argc and @argv -parameters for use with the #GOptionContext command-line parsing API, -with the g_application_command_line_get_arguments() function. See +The `GApplicationCommandLine` object can provide the @argc and @argv +parameters for use with the [struct@Glib.OptionContext] command-line parsing API, +with the [method@Gio.ApplicationCommandLine.get_arguments] function. See [gapplication-example-cmdline3.c][gapplication-example-cmdline3] for an example. The exit status of the originally-invoked process may be set and -messages can be printed to stdout or stderr of that process. The -lifecycle of the originally-invoked process is tied to the lifecycle -of this object (ie: the process exits when the last reference is -dropped). +messages can be printed to stdout or stderr of that process. + +For remote invocation, the originally-invoked process exits when +[method@Gio.ApplicationCommandLine.done] method is called. This method is +also automatically called when the object is disposed. -The main use for #GApplicationCommandLine (and the -#GApplication::command-line signal) is 'Emacs server' like use cases: +The main use for `GApplicationCommandLine` (and the +[signal@Gio.Application::command-line] signal) is 'Emacs server' like use cases: You can set the `EDITOR` environment variable to have e.g. git use your favourite editor to edit commit messages, and if you already have an instance of the editor running, the editing will happen @@ -6479,11 +6506,12 @@ aspect of this use case is that the process that gets started by git does not return until the editing is done. Normally, the commandline is completely handled in the -#GApplication::command-line handler. The launching instance exits +[signal@Gio.Application::command-line] handler. The launching instance exits once the signal handler in the primary instance has returned, and the return value of the signal handler becomes the exit status of the launching instance. -|[<!-- language="C" --> + +```c static int command_line (GApplication *application, GApplicationCommandLine *cmdline) @@ -6505,13 +6533,15 @@ command_line (GApplication *application, return 0; } -]| +``` + The complete example can be found here: [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c) In more complicated cases, the handling of the commandline can be split between the launcher and the primary instance. -|[<!-- language="C" --> + +```c static gboolean test_local_cmdline (GApplication *application, gchar ***arguments, @@ -6557,18 +6587,19 @@ test_application_class_init (TestApplicationClass *class) ... } -]| +``` + In this example of split commandline handling, options that start with `--local-` are handled locally, all other options are passed -to the #GApplication::command-line handler which runs in the primary +to the [signal@Gio.Application::command-line] handler which runs in the primary instance. The complete example can be found here: [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) -If handling the commandline requires a lot of work, it may -be better to defer it. -|[<!-- language="C" --> +If handling the commandline requires a lot of work, it may be better to defer it. + +```c static gboolean my_cmdline_handler (gpointer data) { @@ -6598,15 +6629,42 @@ command_line (GApplication *application, return 0; } -]| +``` + In this example the commandline is not completely handled before -the #GApplication::command-line handler returns. Instead, we keep -a reference to the #GApplicationCommandLine object and handle it +the [signal@Gio.Application::command-line] handler returns. Instead, we keep +a reference to the `GApplicationCommandLine` object and handle it later (in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline. The complete example can be found here: [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) + + Signals that command line processing is completed. + +For remote invocation, it causes the invoking process to terminate. + +For local invocation, it does nothing. + +This method should be called in the [signal@Gio.Application::command-line] +handler, after the exit status is set and all messages are printed. + +After this call, g_application_command_line_set_exit_status() has no effect. +Subsequent calls to this method are no-ops. + +This method is automatically called when the #GApplicationCommandLine +object is disposed — so you can omit the call in non-garbage collected +languages. + + + + + + a #GApplicationCommandLine + + + + Gets the stdin of the invoking process. @@ -6629,28 +6687,42 @@ You must only call this function once per commandline invocation. - + + Prints a message using the stdout print handler in the invoking process. + +Unlike g_application_command_line_print(), @message is not a `printf()`-style +format string. Use this function if @message contains text you don't have +control over, that could include `printf()` escape sequences. + a #GApplicationCommandLine + the message - + + Prints a message using the stderr print handler in the invoking process. + +Unlike g_application_command_line_printerr(), @message is not +a `printf()`-style format string. Use this function if @message contains text +you don't have control over, that could include `printf()` escape sequences. + a #GApplicationCommandLine + the message @@ -6677,6 +6749,32 @@ the invoking process rather than the local process. + + Signals that command line processing is completed. + +For remote invocation, it causes the invoking process to terminate. + +For local invocation, it does nothing. + +This method should be called in the [signal@Gio.Application::command-line] +handler, after the exit status is set and all messages are printed. + +After this call, g_application_command_line_set_exit_status() has no effect. +Subsequent calls to this method are no-ops. + +This method is automatically called when the #GApplicationCommandLine +object is disposed — so you can omit the call in non-garbage collected +languages. + + + + + + a #GApplicationCommandLine + + + + Gets the list of arguments that was passed on the command line. @@ -6905,6 +7003,26 @@ g_print() in the invoking process. + + Prints a message using the stdout print handler in the invoking process. + +Unlike g_application_command_line_print(), @message is not a `printf()`-style +format string. Use this function if @message contains text you don't have +control over, that could include `printf()` escape sequences. + + + + + + a #GApplicationCommandLine + + + + the message + + + + Formats a message and prints it using the stderr print handler in the invoking process. @@ -6930,6 +7048,26 @@ calling g_printerr() in the invoking process. + + Prints a message using the stderr print handler in the invoking process. + +Unlike g_application_command_line_printerr(), @message is not +a `printf()`-style format string. Use this function if @message contains text +you don't have control over, that could include `printf()` escape sequences. + + + + + + a #GApplicationCommandLine + + + + the message + + + + Sets the exit status that will be used when the invoking process exits. @@ -6951,7 +7089,10 @@ in the mainloop running (ie: because the use-count of the application increased to a non-zero value) then the application is considered to have been 'successful' in a certain sense, and the exit status is always zero. If the application use count is zero, though, the exit -status of the local #GApplicationCommandLine is used. +status of the local #GApplicationCommandLine is used. + +This method is a no-op if g_application_command_line_done() has +been called. @@ -6966,16 +7107,21 @@ status of the local #GApplicationCommandLine is used. - + + The commandline that caused this [signal@Gio.Application::command-line] +signal emission. - + + Whether this is a remote commandline. - + + The options sent along with the commandline. - + + Platform-specific data for the commandline. @@ -6998,9 +7144,11 @@ contains private data only. + a #GApplicationCommandLine + the message @@ -7013,9 +7161,11 @@ contains private data only. + a #GApplicationCommandLine + the message @@ -7035,8 +7185,21 @@ contains private data only. + + + + + + + + a #GApplicationCommandLine + + + + + - + @@ -7131,22 +7294,24 @@ situation. - This is the asynchronous version of #GInitable; it behaves the same + `GAsyncInitable` is an interface for asynchronously initializable objects. + +This is the asynchronous version of [iface@Gio.Initable]; it behaves the same in all ways except that initialization is asynchronous. For more details -see the descriptions on #GInitable. +see the descriptions on `GInitable`. -A class may implement both the #GInitable and #GAsyncInitable interfaces. +A class may implement both the `GInitable` and `GAsyncInitable` interfaces. Users of objects implementing this are not intended to use the interface method directly; instead it will be used automatically in various ways. -For C applications you generally just call g_async_initable_new_async() +For C applications you generally just call [func@Gio.AsyncInitable.new_async] directly, or indirectly via a foo_thing_new_async() wrapper. This will call -g_async_initable_init_async() under the cover, calling back with %NULL and -a set %GError on failure. +[method@Gio.AsyncInitable.init_async] under the covers, calling back with `NULL` +and a set `GError` on failure. A typical implementation might look something like this: -|[<!-- language="C" --> +```c enum { NOT_INITIALIZED, INITIALIZING, @@ -7229,7 +7394,7 @@ foo_async_initable_iface_init (gpointer g_iface, iface->init_async = foo_init_async; iface->init_finish = foo_init_finish; } -]| +``` Helper function for constructing #GAsyncInitable object. This is similar to g_object_new() but also initializes the object asynchronously. @@ -7634,37 +7799,38 @@ after this callback returns. - Provides a base class for implementing asynchronous function results. + `GAsyncResult` provides a base class for implementing asynchronous function results. Asynchronous operations are broken up into two separate operations -which are chained together by a #GAsyncReadyCallback. To begin -an asynchronous operation, provide a #GAsyncReadyCallback to the +which are chained together by a `GAsyncReadyCallback`. To begin +an asynchronous operation, provide a `GAsyncReadyCallback` to the asynchronous function. This callback will be triggered when the operation has completed, and must be run in a later iteration of -the [thread-default main context][g-main-context-push-thread-default] -from where the operation was initiated. It will be passed a -#GAsyncResult instance filled with the details of the operation's -success or failure, the object the asynchronous function was -started for and any error codes returned. The asynchronous callback -function is then expected to call the corresponding "_finish()" +the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) from where the operation was +initiated. It will be passed a `GAsyncResult` instance filled with the +details of the operation's success or failure, the object the asynchronous +function was started for and any error codes returned. The asynchronous +callback function is then expected to call the corresponding `_finish()` function, passing the object the function was called for, the -#GAsyncResult instance, and (optionally) an @error to grab any +`GAsyncResult` instance, and (optionally) an @error to grab any error conditions that may have occurred. -The "_finish()" function for an operation takes the generic result -(of type #GAsyncResult) and returns the specific result that the -operation in question yields (e.g. a #GFileEnumerator for a +The `_finish()` function for an operation takes the generic result +(of type `GAsyncResult`) and returns the specific result that the +operation in question yields (e.g. a [class@Gio.FileEnumerator] for a "enumerate children" operation). If the result or error status of the -operation is not needed, there is no need to call the "_finish()" +operation is not needed, there is no need to call the `_finish()` function; GIO will take care of cleaning up the result and error -information after the #GAsyncReadyCallback returns. You can pass -%NULL for the #GAsyncReadyCallback if you don't need to take any +information after the `GAsyncReadyCallback` returns. You can pass +`NULL` for the `GAsyncReadyCallback` if you don't need to take any action at all after the operation completes. Applications may also -take a reference to the #GAsyncResult and call "_finish()" later; -however, the "_finish()" function may be called at most once. +take a reference to the `GAsyncResult` and call `_finish()` later; +however, the `_finish()` function may be called at most once. Example of a typical asynchronous operation flow: -|[<!-- language="C" --> + +```c void _theoretical_frobnitz_async (Theoretical *t, GCancellable *c, GAsyncReadyCallback cb, @@ -7703,20 +7869,20 @@ int main (int argc, void *argv[]) ... } -]| +``` The callback for an asynchronous operation is called only once, and is always called, even in the case of a cancelled operation. On cancellation -the result is a %G_IO_ERROR_CANCELLED error. +the result is a `G_IO_ERROR_CANCELLED` error. -## I/O Priority # {#io-priority} +## I/O Priority Many I/O-related asynchronous operations have a priority parameter, which is used in certain cases to determine the order in which operations are executed. They are not used to determine system-wide I/O scheduling. Priorities are integers, with lower numbers indicating higher priority. It is recommended to choose priorities between -%G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT +`G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT` as a default. Gets the source object from a #GAsyncResult. @@ -7935,17 +8101,16 @@ to enable subclasses to chain up correctly. Buffered input stream implements #GFilterInputStream and provides for buffered reads. -By default, #GBufferedInputStream's buffer size is set at 4 kilobytes. +By default, `GBufferedInputStream`'s buffer size is set at 4 kilobytes. -To create a buffered input stream, use g_buffered_input_stream_new(), -or g_buffered_input_stream_new_sized() to specify the buffer's size at +To create a buffered input stream, use [ctor@Gio.BufferedInputStream.new], +or [ctor@Gio.BufferedInputStream.new_sized] to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use -g_buffered_input_stream_get_buffer_size(). To change the size of a -buffered input stream's buffer, use -g_buffered_input_stream_set_buffer_size(). Note that the buffer's size -cannot be reduced below the size of the data within the buffer. +[method@Gio.BufferedInputStream.get_buffer_size]. To change the size of a +buffered input stream's buffer, use [method@Gio.BufferedInputStream.set_buffer_size]. +Note that the buffer's size cannot be reduced below the size of the data within the buffer. Creates a new #GInputStream from the given @base_stream, with @@ -8302,6 +8467,7 @@ smaller than its current contents. + The size of the backend buffer, in bytes. @@ -8427,20 +8593,19 @@ smaller than its current contents. - Buffered output stream implements #GFilterOutputStream and provides + Buffered output stream implements [class@Gio.FilterOutputStream] and provides for buffered writes. -By default, #GBufferedOutputStream's buffer size is set at 4 kilobytes. +By default, `GBufferedOutputStream`'s buffer size is set at 4 kilobytes. -To create a buffered output stream, use g_buffered_output_stream_new(), -or g_buffered_output_stream_new_sized() to specify the buffer's size +To create a buffered output stream, use [ctor@Gio.BufferedOutputStream.new], +or [ctor@Gio.BufferedOutputStream.new_sized] to specify the buffer's size at construction. To get the size of a buffer within a buffered input stream, use -g_buffered_output_stream_get_buffer_size(). To change the size of a -buffered output stream's buffer, use -g_buffered_output_stream_set_buffer_size(). Note that the buffer's -size cannot be reduced below the size of the data within the buffer. +[method@Gio.BufferedOutputStream.get_buffer_size]. To change the size of a +buffered output stream's buffer, use [method@Gio.BufferedOutputStream.set_buffer_size]. +Note that the buffer's size cannot be reduced below the size of the data within the buffer. Creates a new buffered output stream for a base stream. @@ -8535,9 +8700,11 @@ the data to the underlying stream. + Whether the buffer should automatically grow. + The size of the backend buffer, in bytes. @@ -8721,8 +8888,8 @@ name. - #GBytesIcon specifies an image held in memory in a common format (usually -png) to be used as icon. + `GBytesIcon` specifies an image held in memory in a common format (usually +PNG) to be used as icon. @@ -8863,7 +9030,9 @@ This cannot fail, but loading and interpreting the bytes may fail later on - GCancellable is a thread-safe operation cancellation stack used + `GCancellable` allows operations to be cancelled. + +`GCancellable` is a thread-safe operation cancellation stack used throughout GIO to allow for cancellation of synchronous and asynchronous operations. @@ -9316,8 +9485,8 @@ returned by g_cancellable_source_new(). - #GCharsetConverter is an implementation of #GConverter based on -GIConv. + `GCharsetConverter` is an implementation of [iface@Gio.Converter] based on +[struct@GLib.IConv]. @@ -9379,13 +9548,16 @@ GIConv. - + + The character encoding to convert from. - + + The character encoding to convert to. - + + Use fallback (of form `\<hexval>`) for invalid bytes. @@ -9395,7 +9567,9 @@ GIConv. - #GConverter is implemented by objects that convert + `GConverter` is an interface for streaming conversions. + +`GConverter` is implemented by objects that convert binary data in various ways. The conversion can be stateful and may fail at any place. @@ -9776,11 +9950,11 @@ and may fail at any place. - Converter input stream implements #GInputStream and allows + Converter input stream implements [class@Gio.InputStream] and allows conversion of data of various types during reading. -As of GLib 2.34, #GConverterInputStream implements -#GPollableInputStream. +As of GLib 2.34, `GConverterInputStream` implements +[iface@Gio.PollableInputStream]. Creates a new converter input stream for the @base_stream. @@ -9813,6 +9987,7 @@ As of GLib 2.34, #GConverterInputStream implements + The converter object. @@ -9864,11 +10039,11 @@ As of GLib 2.34, #GConverterInputStream implements - Converter output stream implements #GOutputStream and allows + Converter output stream implements [class@Gio.OutputStream] and allows conversion of data of various types during reading. -As of GLib 2.34, #GConverterOutputStream implements -#GPollableOutputStream. +As of GLib 2.34, `GConverterOutputStream` implements +[iface@Gio.PollableOutputStream]. Creates a new converter output stream for the @base_stream. @@ -9901,6 +10076,7 @@ As of GLib 2.34, #GConverterOutputStream implements + The converter object. @@ -9967,43 +10143,41 @@ As of GLib 2.34, #GConverterOutputStream implements - The #GCredentials type is a reference-counted wrapper for native -credentials. This information is typically used for identifying, + The `GCredentials` type is a reference-counted wrapper for native +credentials. + +The information in `GCredentials` is typically used for identifying, authenticating and authorizing other processes. -Some operating systems supports looking up the credentials of the -remote peer of a communication endpoint - see e.g. -g_socket_get_credentials(). +Some operating systems supports looking up the credentials of the remote +peer of a communication endpoint - see e.g. [method@Gio.Socket.get_credentials]. Some operating systems supports securely sending and receiving -credentials over a Unix Domain Socket, see -#GUnixCredentialsMessage, g_unix_connection_send_credentials() and -g_unix_connection_receive_credentials() for details. +credentials over a Unix Domain Socket, see [class@Gio.UnixCredentialsMessage], +[method@Gio.UnixConnection.send_credentials] and +[method@Gio.UnixConnection.receive_credentials] for details. On Linux, the native credential type is a `struct ucred` - see the -unix(7) man page for details. This corresponds to -%G_CREDENTIALS_TYPE_LINUX_UCRED. +[`unix(7)` man page](man:unix(7)) for details. This corresponds to +`G_CREDENTIALS_TYPE_LINUX_UCRED`. -On Apple operating systems (including iOS, tvOS, and macOS), -the native credential type is a `struct xucred`. -This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED. +On Apple operating systems (including iOS, tvOS, and macOS), the native credential +type is a `struct xucred`. This corresponds to `G_CREDENTIALS_TYPE_APPLE_XUCRED`. -On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native -credential type is a `struct cmsgcred`. This corresponds -to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. +On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a +`struct cmsgcred`. This corresponds to `G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED`. On NetBSD, the native credential type is a `struct unpcbid`. -This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID. +This corresponds to `G_CREDENTIALS_TYPE_NETBSD_UNPCBID`. On OpenBSD, the native credential type is a `struct sockpeercred`. -This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. +This corresponds to `G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED`. -On Solaris (including OpenSolaris and its derivatives), the native -credential type is a `ucred_t`. This corresponds to -%G_CREDENTIALS_TYPE_SOLARIS_UCRED. +On Solaris (including OpenSolaris and its derivatives), the native credential type +is a `ucred_t`. This corresponds to `G_CREDENTIALS_TYPE_SOLARIS_UCRED`. Since GLib 2.72, on Windows, the native credentials may contain the PID of a -process. This corresponds to %G_CREDENTIALS_TYPE_WIN32_PID. +process. This corresponds to `G_CREDENTIALS_TYPE_WIN32_PID`. Creates a new #GCredentials object with credentials matching the the current process. @@ -10460,9 +10634,11 @@ use %FALSE instead. - #GDBusActionGroup is an implementation of the #GActionGroup -interface that can be used as a proxy for an action group -that is exported over D-Bus with g_dbus_connection_export_action_group(). + `GDBusActionGroup` is an implementation of the [iface@Gio.ActionGroup] +interface. + +`GDBusActionGroup` can be used as a proxy for an action group +that is exported over D-Bus with [method@Gio.DBusConnection.export_action_group]. @@ -10620,22 +10796,23 @@ the memory used is freed. - The #GDBusAuthObserver type provides a mechanism for participating -in how a #GDBusServer (or a #GDBusConnection) authenticates remote -peers. Simply instantiate a #GDBusAuthObserver and connect to the + `GDBusAuthObserver` provides a mechanism for participating +in how a [class@Gio.DBusServer] (or a [class@Gio.DBusConnection]) +authenticates remote peers. + +Simply instantiate a `GDBusAuthObserver` and connect to the signals you are interested in. Note that new signals may be added -in the future +in the future. ## 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: +By default, a `GDBusServer` or server-side `GDBusConnection` will allow +any authentication mechanism to be used. If you only want to allow D-Bus +connections with the `EXTERNAL` mechanism, which makes use of credentials +passing and is the recommended mechanism for modern Unix platforms such +as Linux and the BSD family, you would use a signal handler like this: -|[<!-- language="C" --> +```c static gboolean on_allow_mechanism (GDBusAuthObserver *observer, const gchar *mechanism, @@ -10648,19 +10825,19 @@ on_allow_mechanism (GDBusAuthObserver *observer, return FALSE; } -]| +``` -## Controlling Authorization # {#auth-observer} +## Controlling Authorization -By default, a #GDBusServer or server-side #GDBusConnection will accept +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, since GLib 2.68, you should use the -%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent +`G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag. It’s equivalent to the following signal handler: -|[<!-- language="C" --> +```c static gboolean on_authorize_authenticated_peer (GDBusAuthObserver *observer, GIOStream *stream, @@ -10681,7 +10858,7 @@ on_authorize_authenticated_peer (GDBusAuthObserver *observer, return authorized; } -]| +``` Creates a new #GDBusAuthObserver object. @@ -10785,52 +10962,55 @@ supports exchanging UNIX file descriptors with the remote peer. - The #GDBusConnection type is used for D-Bus connections to remote -peers such as a message buses. It is a low-level API that offers a -lot of flexibility. For instance, it lets you establish a connection -over any transport that can by represented as a #GIOStream. + The `GDBusConnection` type is used for D-Bus connections to remote +peers such as a message buses. + +It is a low-level API that offers a lot of flexibility. For instance, +it lets you establish a connection over any transport that can by represented +as a [class@Gio.IOStream]. This class is rarely used directly in D-Bus clients. If you are writing -a D-Bus client, it is often easier to use the g_bus_own_name(), -g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. +a D-Bus client, it is often easier to use the [func@Gio.bus_own_name], +[func@Gio.bus_watch_name] or [func@Gio.DBusProxy.new_for_bus] APIs. As an exception to the usual GLib rule that a particular object must not -be used by two threads at the same time, #GDBusConnection's methods may be -called from any thread. This is so that g_bus_get() and g_bus_get_sync() -can safely return the same #GDBusConnection when called from any thread. - -Most of the ways to obtain a #GDBusConnection automatically initialize it -(i.e. connect to D-Bus): for instance, g_dbus_connection_new() and -g_bus_get(), and the synchronous versions of those methods, give you an -initialized connection. Language bindings for GIO should use -g_initable_new() or g_async_initable_new_async(), which also initialize the -connection. - -If you construct an uninitialized #GDBusConnection, such as via -g_object_new(), you must initialize it via g_initable_init() or -g_async_initable_init_async() before using its methods or properties. -Calling methods or accessing properties on a #GDBusConnection that has not +be used by two threads at the same time, `GDBusConnection`s methods may be +called from any thread. This is so that [func@Gio.bus_get] and +[func@Gio.bus_get_sync] can safely return the same `GDBusConnection` when +called from any thread. + +Most of the ways to obtain a `GDBusConnection` automatically initialize it +(i.e. connect to D-Bus): for instance, [func@Gio.DBusConnection.new] and +[func@Gio.bus_get], and the synchronous versions of those methods, give you +an initialized connection. Language bindings for GIO should use +[func@Gio.Initable.new] or [func@Gio.AsyncInitable.new_async], which also +initialize the connection. + +If you construct an uninitialized `GDBusConnection`, such as via +[ctor@GObject.Object.new], you must initialize it via [method@Gio.Initable.init] or +[method@Gio.AsyncInitable.init_async] before using its methods or properties. +Calling methods or accessing properties on a `GDBusConnection` that has not completed initialization successfully is considered to be invalid, and leads to undefined behaviour. In particular, if initialization fails with a -#GError, the only valid thing you can do with that #GDBusConnection is to -free it with g_object_unref(). +`GError`, the only valid thing you can do with that `GDBusConnection` is to +free it with [method@GObject.Object.unref]. -## An example D-Bus server # {#gdbus-server} +## An example D-Bus server Here is an example for a D-Bus server: [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c) -## An example for exporting a subtree # {#gdbus-subtree-server} +## An example for exporting a subtree Here is an example for exporting a subtree: [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) -## An example for file descriptor passing # {#gdbus-unix-fd-client} +## An example for file descriptor passing Here is an example for passing UNIX file descriptors: [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) -## An example for exporting a GObject # {#gdbus-export} +## An example for exporting a GObject Here is an example for exporting a #GObject: [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) @@ -13144,9 +13324,11 @@ This is typically used when presenting errors to the end user. - The #GDBusInterface type is the base type for D-Bus interfaces both -on the service side (see #GDBusInterfaceSkeleton) and client side -(see #GDBusProxy). + Base type for D-Bus interfaces. + +The `GDBusInterface` type is the base type for D-Bus interfaces both +on the service side (see [class@Gio.DBusInterfaceSkeleton]) and client side +(see [class@Gio.DBusProxy]). Gets the #GDBusObject that @interface_ belongs to, if any. @@ -14163,9 +14345,9 @@ the call, you must return the value of type %G_VARIANT_TYPE_UNIT. - #GDBusMenuModel is an implementation of #GMenuModel that can be used -as a proxy for a menu model that is exported over D-Bus with -g_dbus_connection_export_menu_model(). + `GDBusMenuModel` is an implementation of [class@Gio.MenuModel] that can be +used as a proxy for a menu model that is exported over D-Bus with +[method@Gio.DBusConnection.export_menu_model]. Obtains a #GDBusMenuModel for the menu model which is exported at the given @bus_name and @object_path. @@ -14199,7 +14381,7 @@ the thread default main context unchanged. A type for representing D-Bus messages that can be sent or received -on a #GDBusConnection. +on a [class@Gio.DBusConnection]. Creates a new empty #GDBusMessage. @@ -14324,7 +14506,10 @@ and the per-process or system-wide open files limit is reached. - Convenience to get the first item in the body of @message. + Convenience to get the first item in the body of @message. + +See [method@Gio.DBusMessage.get_arg0_path] for returning object-path-typed +arg0 values. The string item or %NULL if the first item in the body of @message is not a string. @@ -14337,6 +14522,22 @@ and the per-process or system-wide open files limit is reached. + + Convenience to get the first item in the body of @message. + +See [method@Gio.DBusMessage.get_arg0] for returning string-typed arg0 values. + + The object path item or `NULL` if the first item in the + body of @message is not an object path. + + + + + A `GDBusMessage`. + + + + Gets the body of a message. @@ -14703,7 +14904,7 @@ create a reply message to. The contents of the description has no ABI guarantees, the contents and formatting is subject to change at any time. Typical output looks something like this: -|[ +``` Flags: none Version: 0 Serial: 4 @@ -14715,9 +14916,9 @@ Headers: Body: () UNIX File Descriptors: (none) -]| +``` or -|[ +``` Flags: no-reply-expected Version: 0 Serial: 477 @@ -14729,9 +14930,9 @@ Headers: Body: () UNIX File Descriptors: fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635 -]| +``` - A string that should be freed with g_free(). + A string that should be freed with [func@GLib.free]. @@ -15293,13 +15494,14 @@ the memory used is freed. - Instances of the #GDBusMethodInvocation class are used when + Instances of the `GDBusMethodInvocation` class are used when handling D-Bus method calls. It provides a way to asynchronously return results and errors. -The normal way to obtain a #GDBusMethodInvocation object is to receive -it as an argument to the handle_method_call() function in a -#GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). +The normal way to obtain a `GDBusMethodInvocation` object is to receive +it as an argument to the `handle_method_call()` function in a +[type@Gio.DBusInterfaceVTable] that was passed to +[method@Gio.DBusConnection.register_object]. Gets the #GDBusConnection the method was invoked on. @@ -15827,9 +16029,9 @@ the memory used is freed. - The #GDBusObject type is the base type for D-Bus objects on both -the service side (see #GDBusObjectSkeleton) and the client side -(see #GDBusObjectProxy). It is essentially just a container of + The `GDBusObject` type is the base type for D-Bus objects on both +the service side (see [class@Gio.DBusObjectSkeleton]) and the client side +(see [class@Gio.DBusObjectProxy]). It is essentially just a container of interfaces. Gets the D-Bus interface with name @interface_name associated with @@ -16069,13 +16271,13 @@ interfaces. - The #GDBusObjectManager type is the base type for service- and + The `GDBusObjectManager` type is the base type for service- and client-side implementations of the standardized -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) +[`org.freedesktop.DBus.ObjectManager`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. -See #GDBusObjectManagerClient for the client-side implementation -and #GDBusObjectManagerServer for the service-side implementation. +See [class@Gio.DBusObjectManagerClient] for the client-side implementation +and [class@Gio.DBusObjectManagerServer] for the service-side implementation. Gets the interface proxy for @interface_name at @object_path, if any. @@ -16342,79 +16544,82 @@ connect signals to all objects managed by @manager. - #GDBusObjectManagerClient is used to create, monitor and delete object -proxies for remote objects exported by a #GDBusObjectManagerServer (or any -code implementing the + `GDBusObjectManagerClient` is used to create, monitor and delete object +proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer] +(or any code implementing the [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface). Once an instance of this type has been created, you can connect to -the #GDBusObjectManager::object-added and -#GDBusObjectManager::object-removed signals and inspect the -#GDBusObjectProxy objects returned by -g_dbus_object_manager_get_objects(). +the [signal@Gio.DBusObjectManager::object-added] and +[signal@Gio.DBusObjectManager::object-removed signals] and inspect the +[class@Gio.DBusObjectProxy] objects returned by +[method@Gio.DBusObjectManager.get_objects]. -If the name for a #GDBusObjectManagerClient is not owned by anyone at +If the name for a `GDBusObjectManagerClient` is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be -disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START -flag. It's also worth noting that this only works if the name of +disabled using the `G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START` +flag. It’s also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this -case, #GDBusObjectManagerClient object construction still succeeds but +case, `GDBusObjectManagerClient` object construction still succeeds but there will be no object proxies -(e.g. g_dbus_object_manager_get_objects() returns the empty list) and -the #GDBusObjectManagerClient:name-owner property is %NULL. +(e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and +the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`. The owner of the requested name can come and go (for example -consider a system service being restarted) – #GDBusObjectManagerClient -handles this case too; simply connect to the #GObject::notify -signal to watch for changes on the #GDBusObjectManagerClient:name-owner -property. When the name owner vanishes, the behavior is that -#GDBusObjectManagerClient:name-owner is set to %NULL (this includes -emission of the #GObject::notify signal) and then -#GDBusObjectManager::object-removed signals are synthesized +consider a system service being restarted) – `GDBusObjectManagerClient` +handles this case too; simply connect to the [signal@GObject.Object::notify] +signal to watch for changes on the +[property@Gio.DBusObjectManagerClient:name-owner] property. When the name +owner vanishes, the behavior is that +[property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this +includes emission of the [signal@GObject.Object::notify] signal) and then +[signal@Gio.DBusObjectManager::object-removed] signals are synthesized for all currently existing object proxies. Since -#GDBusObjectManagerClient:name-owner is %NULL when this happens, you can -use this information to disambiguate a synthesized signal from a -genuine signal caused by object removal on the remote -#GDBusObjectManager. Similarly, when a new name owner appears, -#GDBusObjectManager::object-added signals are synthesized -while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all -object proxies have been added, the #GDBusObjectManagerClient:name-owner -is set to the new name owner (this includes emission of the -#GObject::notify signal). Furthermore, you are guaranteed that -#GDBusObjectManagerClient:name-owner will alternate between a name owner -(e.g. `:1.42`) and %NULL even in the case where +[property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this +happens, you can use this information to disambiguate a synthesized signal +from a genuine signal caused by object removal on the remote +[iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears, +[signal@Gio.DBusObjectManager::object-added] signals are synthesized +while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only +when all object proxies have been added, the +[property@Gio.DBusObjectManagerClient:name-owner] is set to the new name +owner (this includes emission of the [signal@GObject.Object::notify] signal). +Furthermore, you are guaranteed that +[property@Gio.DBusObjectManagerClient:name-owner] will alternate between a +name owner (e.g. `:1.42`) and `NULL` even in the case where the name of interest is atomically replaced -Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy -instances. All signals (including the -org.freedesktop.DBus.Properties::PropertiesChanged signal) -delivered to #GDBusProxy instances are guaranteed to originate +Ultimately, `GDBusObjectManagerClient` is used to obtain +[class@Gio.DBusProxy] instances. All signals (including the +`org.freedesktop.DBus.Properties::PropertiesChanged` signal) +delivered to [class@Gio.DBusProxy] instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the -"half the proxy is from the old owner and the other half is from -the new owner" problem cannot happen. +“half the proxy is from the old owner and the other half is from +the new owner” problem cannot happen. To avoid having the application connect to signals on the returned -#GDBusObjectProxy and #GDBusProxy objects, the -#GDBusObject::interface-added, -#GDBusObject::interface-removed, -#GDBusProxy::g-properties-changed and -#GDBusProxy::g-signal signals -are also emitted on the #GDBusObjectManagerClient instance managing these +[class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the +[signal@Gio.DBusObject::interface-added], +[signal@Gio.DBusObject::interface-removed], +[signal@Gio.DBusProxy::g-properties-changed] and +[signal@Gio.DBusProxy::g-signal] signals +are also emitted on the `GDBusObjectManagerClient` instance managing these objects. The signals emitted are -#GDBusObjectManager::interface-added, -#GDBusObjectManager::interface-removed, -#GDBusObjectManagerClient::interface-proxy-properties-changed and -#GDBusObjectManagerClient::interface-proxy-signal. +[signal@Gio.DBusObjectManager::interface-added], +[signal@Gio.DBusObjectManager::interface-removed], +[signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and +[signal@Gio.DBusObjectManagerClient::interface-proxy-signal]. Note that all callbacks and signals are emitted in the -[thread-default main context][g-main-context-push-thread-default] -that the #GDBusObjectManagerClient object was constructed -in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects -originating from the #GDBusObjectManagerClient object will be created in +thread-default main context (see +[method@GLib.MainContext.push_thread_default]) that the +`GDBusObjectManagerClient` object was constructed in. Additionally, the +[class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects +originating from the `GDBusObjectManagerClient` object will be created in the same context and, consequently, will deliver signals in the same main loop. @@ -17109,9 +17314,9 @@ that @manager was constructed in. - #GDBusObjectManagerServer is used to export #GDBusObject instances using -the standardized -[org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) + `GDBusObjectManagerServer` is used to export [iface@Gio.DBusObject] instances +using the standardized +[`org.freedesktop.DBus.ObjectManager`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) interface. For example, remote D-Bus clients can get all objects and properties in a single call. Additionally, any change in the object hierarchy is broadcast using signals. This means that D-Bus @@ -17127,10 +17332,9 @@ below (to allow for multiple object managers in a service). It is supported, but not recommended, to export an object manager at the root path, `/`. -See #GDBusObjectManagerClient for the client-side code that is -intended to be used with #GDBusObjectManagerServer or any D-Bus -object implementing the org.freedesktop.DBus.ObjectManager -interface. +See [class@Gio.DBusObjectManagerClient] for the client-side code that is +intended to be used with `GDBusObjectManagerServer` or any D-Bus +object implementing the `org.freedesktop.DBus.ObjectManager` interface. Creates a new #GDBusObjectManagerServer object. @@ -17294,9 +17498,9 @@ object path for @manager. - A #GDBusObjectProxy is an object used to represent a remote object -with one or more D-Bus interfaces. Normally, you don't instantiate -a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient + A `GDBusObjectProxy` is an object used to represent a remote object +with one or more D-Bus interfaces. Normally, you don’t instantiate +a `GDBusObjectProxy` yourself — typically [class@Gio.DBusObjectManagerClient] is used to obtain it. @@ -17360,11 +17564,11 @@ object path. - A #GDBusObjectSkeleton instance is essentially a group of D-Bus + A `GDBusObjectSkeleton` instance is essentially a group of D-Bus interfaces. The set of exported interfaces on the object may be dynamic and change at runtime. -This type is intended to be used with #GDBusObjectManager. +This type is intended to be used with [iface@Gio.DBusObjectManager]. Creates a new #GDBusObjectSkeleton. @@ -17614,50 +17818,52 @@ the memory used is freed. - #GDBusProxy is a base class used for proxies to access a D-Bus -interface on a remote object. A #GDBusProxy can be constructed for + `GDBusProxy` is a base class used for proxies to access a D-Bus +interface on a remote object. A `GDBusProxy` can be constructed for both well-known and unique names. -By default, #GDBusProxy will cache all properties (and listen to +By default, `GDBusProxy` will cache all properties (and listen to 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 +[flags@Gio.DBusProxyFlags] when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears. -The unique name owner of the proxy's name is tracked and can be read from -#GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to -get notified of changes. Additionally, only signals and property -changes emitted from the current name owner are considered and -calls are always sent to the current name owner. This avoids a -number of race conditions when the name is lost by one owner and -claimed by another. However, if no name owner currently exists, +The unique name owner of the proxy’s name is tracked and can be read from +[property@Gio.DBusProxy:g-name-owner]. Connect to the +[signal@GObject.Object::notify] signal to get notified of changes. +Additionally, only signals and property changes emitted from the current name +owner are considered and calls are always sent to the current name owner. +This avoids a number of race conditions when the name is lost by one owner +and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless -%G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). +`G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START` is set). If the proxy is for a stateless D-Bus service, where the name owner may -be started and stopped between calls, the #GDBusProxy:g-name-owner tracking -of #GDBusProxy will cause the proxy to drop signal and property changes from -the service after it has restarted for the first time. When interacting -with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus -method calls and signal connections. - -The generic #GDBusProxy::g-properties-changed and -#GDBusProxy::g-signal signals are not very convenient to work with. -Therefore, the recommended way of working with proxies is to subclass -#GDBusProxy, and have more natural properties and signals in your derived -class. This [example][gdbus-example-gdbus-codegen] shows how this can -easily be done using the [gdbus-codegen][gdbus-codegen] tool. - -A #GDBusProxy instance can be used from multiple threads but note -that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed -and #GObject::notify) are emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread where the instance was constructed. +be started and stopped between calls, the +[property@Gio.DBusProxy:g-name-owner] tracking of `GDBusProxy` will cause the +proxy to drop signal and property changes from the service after it has +restarted for the first time. When interacting with a stateless D-Bus +service, do not use `GDBusProxy` — use direct D-Bus method calls and signal +connections. + +The generic [signal@Gio.DBusProxy::g-properties-changed] and +[signal@Gio.DBusProxy::g-signal] signals are not very convenient to work +with. Therefore, the recommended way of working with proxies is to subclass +`GDBusProxy`, and have more natural properties and signals in your derived +class. This [example](migrating-gdbus.html#using-gdbus-codegen) shows how +this can easily be done using the [`gdbus-codegen`](gdbus-codegen.html) tool. + +A `GDBusProxy` instance can be used from multiple threads but note +that all signals (e.g. [signal@Gio.DBusProxy::g-signal], +[signal@Gio.DBusProxy::g-properties-changed] and +[signal@GObject.Object::notify]) are emitted in the thread-default main +context (see [method@GLib.MainContext.push_thread_default]) of the thread +where the instance was constructed. An example using a proxy for a well-known name can be found in -[gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c) +[`gdbus-example-watch-proxy.c`](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c). @@ -18736,24 +18942,26 @@ sending a message. - #GDBusServer is a helper for listening to and accepting D-Bus + `GDBusServer` is a helper for listening to and accepting D-Bus connections. This can be used to create a new D-Bus server, allowing two peers to use the D-Bus protocol for their own specialized communication. A server instance provided in this way will not perform message routing or -implement the org.freedesktop.DBus interface. +implement the +[`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages). To just export an object on a well-known name on a message bus, such as the -session or system bus, you should instead use g_bus_own_name(). +session or system bus, you should instead use [func@Gio.bus_own_name]. An example of peer-to-peer communication with GDBus can be found in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/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. Since GLib 2.68 this can -be achieved more simply by passing the -%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server. +Note that a minimal `GDBusServer` will accept connections from any +peer. In many use-cases it will be necessary to add a +[class@Gio.DBusAuthObserver] that only accepts connections that have +successfully authenticated as the same user that is running the +`GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing +the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the +server. Creates a new D-Bus server that listens on the first address in @@ -19246,6 +19454,684 @@ See [Extending GIO][extending-gio]. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -19336,8 +20222,8 @@ See [Extending GIO][extending-gio]. - Data input stream implements #GInputStream and includes functions for -reading structured data directly from a binary input stream. + Data input stream implements [class@Gio.InputStream] and includes functions +for reading structured data directly from a binary input stream. Creates a new data input stream for the @base_stream. @@ -20031,8 +20917,8 @@ as a line ending when reading complete lines from the stream. - Data output stream implements #GOutputStream and includes functions for -writing data directly to an output stream. + Data output stream implements [class@Gio.OutputStream] and includes functions +for writing data directly to an output stream. Creates a new data output stream for @base_stream. @@ -20326,52 +21212,54 @@ across various machine architectures. - A #GDatagramBased is a networking interface for representing datagram-based + Interface for socket-like objects with datagram semantics. + +A `GDatagramBased` is a networking interface for representing datagram-based communications. It is a more or less direct mapping of the core parts of the BSD socket API in a portable GObject interface. It is implemented by -#GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows. +[class@Gio.Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows. -#GDatagramBased is entirely platform independent, and is intended to be used -alongside higher-level networking APIs such as #GIOStream. +`GDatagramBased` is entirely platform independent, and is intended to be used +alongside higher-level networking APIs such as [class@Gio.IOStream]. It uses vectored scatter/gather I/O by default, allowing for many messages to be sent or received in a single call. Where possible, implementations of the interface should take advantage of vectored I/O to minimise processing -or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where -possible. Callers should take advantage of scatter/gather I/O (the use of +or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()` +where possible. Callers should take advantage of scatter/gather I/O (the use of multiple buffers per message) to avoid unnecessary copying of data to assemble or disassemble a message. -Each #GDatagramBased operation has a timeout parameter which may be negative +Each `GDatagramBased` operation has a timeout parameter which may be negative for blocking behaviour, zero for non-blocking behaviour, or positive for timeout behaviour. A blocking operation blocks until finished or there is an error. A non-blocking operation will return immediately with a -%G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation +`G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation will block until the operation is complete or the timeout expires; if the timeout expires it will return what progress it made, or -%G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would -successfully run you can call g_datagram_based_condition_check() or -g_datagram_based_condition_wait(). You can also use -g_datagram_based_create_source() and attach it to a #GMainContext to get -callbacks when I/O is possible. +`G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would +successfully run you can call [method@Gio.DatagramBased.condition_check] or +[method@Gio.DatagramBased.condition_wait]. You can also use +[method@Gio.DatagramBased.create_source] and attach it to a [struct@Glib.MainContext] +to get callbacks when I/O is possible. When running a non-blocking operation applications should always be able to -handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function +handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable until a write -returns %G_IO_ERROR_WOULD_BLOCK. +returns `G_IO_ERROR_WOULD_BLOCK`. -As with #GSocket, #GDatagramBaseds can be either connection oriented (for -example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be +As with `GSocket`, `GDatagramBased`s can be either connection oriented (for +example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be datagram-based, not stream-based. The interface does not cover connection establishment — use methods on the underlying type to establish a connection -before sending and receiving data through the #GDatagramBased API. For +before sending and receiving data through the `GDatagramBased` API. For connectionless socket types the target/source address is specified or received in each I/O operation. -Like most other APIs in GLib, #GDatagramBased is not inherently thread safe. -To use a #GDatagramBased concurrently from multiple threads, you must +Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe. +To use a `GDatagramBased` concurrently from multiple threads, you must implement your own locking. Checks on the readiness of @datagram_based to perform operations. The @@ -21127,20 +22015,21 @@ returned by g_datagram_based_create_source(). - #GDebugController is an interface to expose control of debugging features and + `GDebugController` is an interface to expose control of debugging features and debug output. -It is implemented on Linux using #GDebugControllerDBus, which exposes a D-Bus -interface to allow authenticated peers to control debug features in this -process. +It is implemented on Linux using [class@Gio.DebugControllerDBus], which +exposes a D-Bus interface to allow authenticated peers to control debug +features in this process. Whether debug output is enabled is exposed as -#GDebugController:debug-enabled. This controls g_log_set_debug_enabled() by -default. Application code may connect to the #GObject::notify signal for it +[property@Gio.DebugController:debug-enabled]. This controls +[func@GLib.log_set_debug_enabled] by default. Application code may +connect to the [signal@GObject.Object::notify] signal for it to control other parts of its debug infrastructure as necessary. If your application or service is using the default GLib log writer function, -creating one of the built-in implementations of #GDebugController should be +creating one of the built-in implementations of `GDebugController` should be all that’s needed to dynamically enable or disable debug output. @@ -21179,30 +22068,32 @@ the journal), %FALSE otherwise. - #GDebugControllerDBus is an implementation of #GDebugController which exposes -debug settings as a D-Bus object. + `GDebugControllerDBus` is an implementation of [iface@Gio.DebugController] +which exposes debug settings as a D-Bus object. -It is a #GInitable object, and will register an object at +It is a [iface@Gio.Initable] object, and will register an object at `/org/gtk/Debugging` on the bus given as -#GDebugControllerDBus:connection once it’s initialized. The object will be -unregistered when the last reference to the #GDebugControllerDBus is dropped. +[property@Gio.DebugControllerDBus:connection] once it’s initialized. The +object will be unregistered when the last reference to the +`GDebugControllerDBus` is dropped. This D-Bus object can be used by remote processes to enable or disable debug output in this process. Remote processes calling `org.gtk.Debugging.SetDebugEnabled()` will affect the value of -#GDebugController:debug-enabled and, by default, g_log_get_debug_enabled(). -default. +[property@Gio.DebugController:debug-enabled] and, by default, +[func@GLib.log_get_debug_enabled]. By default, no processes are allowed to call `SetDebugEnabled()` unless a -#GDebugControllerDBus::authorize signal handler is installed. This is because -the process may be privileged, or might expose sensitive information in its -debug output. You may want to restrict the ability to enable debug output to -privileged users or processes. +[signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This +is because the process may be privileged, or might expose sensitive +information in its debug output. You may want to restrict the ability to +enable debug output to privileged users or processes. One option is to install a D-Bus security policy which restricts access to `SetDebugEnabled()`, installing something like the following in `$datadir/dbus-1/system.d/`: -|[<!-- language="XML" --> + +```xml <?xml version="1.0"?> <!--*-nxml-*--> <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> @@ -21214,7 +22105,7 @@ One option is to install a D-Bus security policy which restricts access to <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/> </policy> </busconfig> -]| +``` This will prevent the `SetDebugEnabled()` method from being called by all except root. It will not prevent the `DebugEnabled` property from being read, @@ -21222,9 +22113,10 @@ as it’s accessed through the `org.freedesktop.DBus.Properties` interface. Another option is to use polkit to allow or deny requests on a case-by-case basis, allowing for the possibility of dynamic authorisation. To do this, -connect to the #GDebugControllerDBus::authorize signal and query polkit in -it: -|[<!-- language="C" --> +connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query +polkit in it: + +```c g_autoptr(GError) child_error = NULL; g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL); gulong debug_controller_authorize_id = 0; @@ -21285,7 +22177,7 @@ it: return polkit_authorization_result_get_is_authorized (auth_result); } -]| +``` @@ -21428,7 +22320,7 @@ The default class handler just returns %TRUE. - #GDesktopAppInfo is an implementation of #GAppInfo based on + `GDesktopAppInfo` is an implementation of [iface@Gio.AppInfo] based on desktop files. Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific @@ -22110,32 +23002,32 @@ for each, providing the process ID. - #GDrive - this represent a piece of hardware connected to the machine. -It's generally only created for removable hardware or hardware with + `GDrive` represents a piece of hardware connected to the machine. +It’s generally only created for removable hardware or hardware with removable media. -#GDrive is a container class for #GVolume objects that stem from -the same piece of media. As such, #GDrive abstracts a drive with +`GDrive` is a container class for [iface@Gio.Volume] objects that stem from +the same piece of media. As such, `GDrive` abstracts a drive with (or without) removable media and provides operations for querying whether media is available, determining whether media change is automatically detected and ejecting the media. -If the #GDrive reports that media isn't automatically detected, one +If the `GDrive` reports that media isn’t automatically detected, one can poll for media; typically one should not do this periodically as a poll for media operation is potentially expensive and may spin up the drive creating noise. -#GDrive supports starting and stopping drives with authentication +`GDrive` supports starting and stopping drives with authentication support for the former. This can be used to support a diverse set of use cases including connecting/disconnecting iSCSI devices, powering down external disk enclosures and starting/stopping multi-disk devices such as RAID devices. Note that the actual -semantics and side-effects of starting/stopping a #GDrive may vary +semantics and side-effects of starting/stopping a `GDrive` may vary according to implementation. To choose the correct verbs in e.g. a -file manager, use g_drive_get_start_stop_type(). +file manager, use [method@Gio.Drive.get_start_stop_type]. -For porting from GnomeVFS note that there is no equivalent of -#GDrive in that API. +For [porting from GnomeVFS](migrating-gnome-vfs.html) note that there is no +equivalent of `GDrive` in that API. Checks if a drive can be ejected. @@ -23857,8 +24749,8 @@ been pressed. - #GDtlsClientConnection is the client-side subclass of -#GDtlsConnection, representing a client-side DTLS connection. + `GDtlsClientConnection` is the client-side subclass of +[iface@Gio.DtlsConnection], representing a client-side DTLS connection. @@ -24038,25 +24930,27 @@ connect to #GDtlsConnection::accept-certificate. - #GDtlsConnection is the base DTLS connection class type, which wraps -a #GDatagramBased and provides DTLS encryption on top of it. Its -subclasses, #GDtlsClientConnection and #GDtlsServerConnection, -implement client-side and server-side DTLS, respectively. + `GDtlsConnection` is the base DTLS connection class type, which wraps +a [iface@Gio.DatagramBased] and provides DTLS encryption on top of it. Its +subclasses, [iface@Gio.DtlsClientConnection] and +[iface@Gio.DtlsServerConnection], implement client-side and server-side DTLS, +respectively. -For TLS support, see #GTlsConnection. +For TLS support, see [class@Gio.TlsConnection]. -As DTLS is datagram based, #GDtlsConnection implements #GDatagramBased, -presenting a datagram-socket-like API for the encrypted connection. This -operates over a base datagram connection, which is also a #GDatagramBased -(#GDtlsConnection:base-socket). +As DTLS is datagram based, `GDtlsConnection` implements +[iface@Gio.DatagramBased], presenting a datagram-socket-like API for the +encrypted connection. This operates over a base datagram connection, which is +also a `GDatagramBased` ([property@Gio.DtlsConnection:base-socket]). -To close a DTLS connection, use g_dtls_connection_close(). +To close a DTLS connection, use [method@Gio.DtlsConnection.close]. -Neither #GDtlsServerConnection or #GDtlsClientConnection set the peer address -on their base #GDatagramBased if it is a #GSocket — it is up to the caller to -do that if they wish. If they do not, and g_socket_close() is called on the -base socket, the #GDtlsConnection will not raise a %G_IO_ERROR_NOT_CONNECTED -error on further I/O. +Neither [iface@Gio.DtlsServerConnection] or [iface@Gio.DtlsClientConnection] +set the peer address on their base [iface@Gio.DatagramBased] if it is a +[class@Gio.Socket] — it is up to the caller to do that if they wish. If they +do not, and [method@Gio.Socket.close] is called on the base socket, the +`GDtlsConnection` will not raise a `G_IO_ERROR_NOT_CONNECTED` error on +further I/O. @@ -25366,8 +26260,8 @@ case @error will be set - #GDtlsServerConnection is the server-side subclass of #GDtlsConnection, -representing a server-side DTLS connection. + `GDtlsServerConnection` is the server-side subclass of +[iface@Gio.DtlsConnection], representing a server-side DTLS connection. @@ -25439,9 +26333,9 @@ rehandshake with a different mode from the initial handshake. - #GEmblem is an implementation of #GIcon that supports + `GEmblem` is an implementation of [iface@Gio.Icon] that supports having an emblem, which is an icon with additional properties. -It can than be added to a #GEmblemedIcon. +It can than be added to a [class@Gio.EmblemedIcon]. Currently, only metainformation about the emblem's origin is supported. More may be added in the future. @@ -25503,10 +26397,12 @@ supported. More may be added in the future. - + + The actual icon of the emblem. - + + The origin the emblem is derived from. @@ -25528,12 +26424,12 @@ to #GEmblem. - #GEmblemedIcon is an implementation of #GIcon that supports + `GEmblemedIcon` is an implementation of [iface@Gio.Icon] that supports adding an emblem to an icon. Adding multiple emblems to an -icon is ensured via g_emblemed_icon_add_emblem(). +icon is ensured via [method@Gio.EmblemedIcon.add_emblem]. -Note that #GEmblemedIcon allows no control over the position -of the emblems. See also #GEmblem for more information. +Note that `GEmblemedIcon` allows no control over the position +of the emblems. See also [class@Gio.Emblem] for more information. Creates a new emblemed icon for @icon with the emblem @emblem. @@ -25609,7 +26505,8 @@ of the emblems. See also #GEmblem for more information. - + + The [iface@Gio.Icon] to attach emblems to. @@ -26693,89 +27590,97 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - #GFile is a high level abstraction for manipulating files on a -virtual file system. #GFiles are lightweight, immutable objects + `GFile` is a high level abstraction for manipulating files on a +virtual file system. `GFile`s are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that -#GFile objects do not represent files, merely an identifier for a +`GFile` objects do not represent files, merely an identifier for a file. All file content I/O is implemented as streaming operations -(see #GInputStream and #GOutputStream). - -To construct a #GFile, you can use: -- g_file_new_for_path() if you have a path. -- g_file_new_for_uri() if you have a URI. -- g_file_new_for_commandline_arg() for a command line argument. -- g_file_new_tmp() to create a temporary file from a template. -- g_file_new_tmp_async() to asynchronously create a temporary file. -- g_file_new_tmp_dir_async() to asynchronously create a temporary directory. -- g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). -- g_file_new_build_filename() or g_file_new_build_filenamev() to create a file from path elements. - -One way to think of a #GFile is as an abstraction of a pathname. For +(see [class@Gio.InputStream] and [class@Gio.OutputStream]). + +To construct a `GFile`, you can use: + +- [func@Gio.File.new_for_path] if you have a path. +- [func@Gio.File.new_for_uri] if you have a URI. +- [func@Gio.File.new_for_commandline_arg] or + [func@Gio.File.new_for_commandline_arg_and_cwd] for a command line + argument. +- [func@Gio.File.new_tmp] to create a temporary file from a template. +- [func@Gio.File.new_tmp_async] to asynchronously create a temporary file. +- [func@Gio.File.new_tmp_dir_async] to asynchronously create a temporary + directory. +- [func@Gio.File.parse_name] from a UTF-8 string gotten from + [method@Gio.File.get_parse_name]. +- [func@Gio.File.new_build_filename] or [func@Gio.File.new_build_filenamev] + to create a file from path elements. + +One way to think of a `GFile` is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as -#GFiles are extensible it could also be something else that corresponds +`GFile`s are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. -#GFiles make up hierarchies of directories and files that correspond to +`GFile`s make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with -#GFile using g_file_get_parent() to get an identifier for the parent -directory, g_file_get_child() to get a child within a directory, -g_file_resolve_relative_path() to resolve a relative path between two -#GFiles. There can be multiple hierarchies, so you may not end up at -the same root if you repeatedly call g_file_get_parent() on two different -files. - -All #GFiles have a basename (get with g_file_get_basename()). These names -are byte strings that are used to identify the file on the filesystem +`GFile` using [method@Gio.File.get_parent] to get an identifier for the +parent directory, [method@Gio.File.get_child] to get a child within a +directory, and [method@Gio.File.resolve_relative_path] to resolve a relative +path between two `GFile`s. There can be multiple hierarchies, so you may not +end up at the same root if you repeatedly call [method@Gio.File.get_parent] +on two different files. + +All `GFile`s have a basename (get with [method@Gio.File.get_basename]). These +names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the -%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with g_file_query_info(). -This is guaranteed to be in UTF-8 and can be used in a user interface. -But always store the real basename or the #GFile to use to actually -access the file, because there is no way to go from a display name to -the actual name. +`G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME` attribute with +[method@Gio.File.query_info]. This is guaranteed to be in UTF-8 and can be +used in a user interface. But always store the real basename or the `GFile` +to use to actually access the file, because there is no way to go from a +display name to the actual name. -Using #GFile as an identifier has the same weaknesses as using a path +Using `GFile` as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, -hard or soft links may cause two different #GFiles to refer to the same +hard or soft links may cause two different `GFile`s to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to -check if two #GFiles point to the same file you can query for the -%G_FILE_ATTRIBUTE_ID_FILE attribute. Note that #GFile does some trivial +check if two `GFile`s point to the same file you can query for the +`G_FILE_ATTRIBUTE_ID_FILE` attribute. Note that `GFile` does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of -path, "." or ".." path segments, etc) does not create different #GFiles. +path, `.` or `..` path segments, etc) does not create different `GFile`s. -Many #GFile operations have both synchronous and asynchronous versions +Many `GFile` operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions -simply have _async() appended to their function names. The asynchronous -I/O functions call a #GAsyncReadyCallback which is then used to finalize -the operation, producing a GAsyncResult which is then passed to the -function's matching _finish() operation. +simply have `_async()` appended to their function names. The asynchronous +I/O functions call a [callback@Gio.AsyncReadyCallback] which is then used to +finalize the operation, producing a [iface@Gio.AsyncResult] which is then +passed to the function’s matching `_finish()` operation. It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the -[introduction to asynchronous programming section][async-programming] for -more. +[introduction to asynchronous programming section](overview.html#asynchronous-programming) +for more. -Some #GFile operations almost always take a noticeable amount of time, and +Some `GFile` operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include: -- g_file_mount_mountable() to mount a mountable file. -- g_file_unmount_mountable_with_operation() to unmount a mountable file. -- g_file_eject_mountable_with_operation() to eject a mountable file. -## Entity Tags # {#gfile-etag} +- [method@Gio.File.mount_mountable] to mount a mountable file. +- [method@Gio.File.unmount_mountable_with_operation] to unmount a mountable + file. +- [method@Gio.File.eject_mountable_with_operation] to eject a mountable file. + +## Entity Tags -One notable feature of #GFiles are entity tags, or "etags" for +One notable feature of `GFile`s are entity tags, or ‘etags’ for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the HTTP 1.1 [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) -for HTTP Etag headers, which are a very similar concept. +for HTTP `ETag` headers, which are a very similar concept. Constructs a #GFile from a series of elements using the correct separator for filenames. @@ -28369,7 +29274,7 @@ g_file_make_symbolic_link_async(). - + Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also @@ -28406,7 +29311,7 @@ callback will be invoked. optional #GCancellable - + a #GFileMeasureProgressCallback @@ -28518,8 +29423,7 @@ directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor(). a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). + or %NULL on error. Free the returned object with g_object_unref(). @@ -29444,7 +30348,7 @@ possible too, and depend on what kind of filesystem the file is on. - an optional [entity tag][gfile-etag] + an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore @@ -29482,7 +30386,7 @@ of the operation. - an [entity tag][gfile-etag] for the current #GFile, + an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore @@ -29555,7 +30459,7 @@ rather than just opening for reading or writing. - an optional [entity tag][gfile-etag] + an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore @@ -29594,7 +30498,7 @@ the result of the operation. - an [entity tag][gfile-etag] for the current #GFile, + an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore @@ -32021,7 +32925,7 @@ g_file_make_symbolic_link_async(). - + Recursively measures the disk usage of @file. This is essentially an analog of the 'du' command, but it also @@ -32058,7 +32962,7 @@ callback will be invoked. optional #GCancellable - + a #GFileMeasureProgressCallback @@ -32199,8 +33103,7 @@ directory for changes made via hard links; if you want to do this then you must register individual watches with g_file_monitor(). a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). + or %NULL on error. Free the returned object with g_object_unref(). @@ -33252,7 +34155,7 @@ possible too, and depend on what kind of filesystem the file is on. - an optional [entity tag][gfile-etag] + an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore @@ -33290,7 +34193,7 @@ of the operation. - an [entity tag][gfile-etag] for the current #GFile, + an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore @@ -33360,7 +34263,7 @@ changed the next time it is saved over. - the old [entity-tag][gfile-etag] for the document, + the old [entity-tag](#entity-tags) for the document, or %NULL @@ -33373,7 +34276,7 @@ changed the next time it is saved over. - a location to a new [entity tag][gfile-etag] + a location to a new [entity tag](#entity-tags) for the document. This should be freed with g_free() when no longer needed, or %NULL @@ -33423,7 +34326,7 @@ contents (without copying) for the duration of the call. - a new [entity tag][gfile-etag] for the @file, or %NULL + a new [entity tag](#entity-tags) for the @file, or %NULL @@ -33470,7 +34373,7 @@ g_file_replace_contents_finish(). - a new [entity tag][gfile-etag] for the @file, or %NULL + a new [entity tag](#entity-tags) for the @file, or %NULL @@ -33513,7 +34416,7 @@ tag for the document, if present. - a location of a new [entity tag][gfile-etag] + a location of a new [entity tag](#entity-tags) for the document. This should be freed with g_free() when it is no longer needed, or %NULL @@ -33561,7 +34464,7 @@ rather than just opening for reading or writing. - an optional [entity tag][gfile-etag] + an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore @@ -33600,7 +34503,7 @@ the result of the operation. - an [entity tag][gfile-etag] for the current #GFile, + an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore @@ -34849,6 +35752,10 @@ the @matcher is automatically freed. Leaves target file with default perms, instead of setting the source file perms. + + Use default modification + timestamps instead of copying them from the source file. Since 2.80 + Flags used when an operation may create a file. @@ -34873,8 +35780,10 @@ the @matcher is automatically freed. - #GFileDescriptorBased is implemented by streams (implementations of -#GInputStream or #GOutputStream) that are based on file descriptors. + `GFileDescriptorBased` is an interface for file descriptor based IO. + +It is implemented by streams (implementations of [class@Gio.InputStream] or +[class@Gio.OutputStream]) that are based on file descriptors. Note that `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config @@ -34928,19 +35837,19 @@ file when using it. - #GFileEnumerator allows you to operate on a set of #GFiles, -returning a #GFileInfo structure for each file enumerated (e.g. -g_file_enumerate_children() will return a #GFileEnumerator for each + `GFileEnumerator` allows you to operate on a set of [iface@Gio.File] objects, +returning a [class@Gio.FileInfo] structure for each file enumerated (e.g. +[method@Gio.File.enumerate_children] will return a `GFileEnumerator` for each of the children within a directory). -To get the next file's information from a #GFileEnumerator, use -g_file_enumerator_next_file() or its asynchronous version, -g_file_enumerator_next_files_async(). Note that the asynchronous -version will return a list of #GFileInfos, whereas the +To get the next file's information from a `GFileEnumerator`, use +[method@Gio.FileEnumerator.next_file] or its asynchronous version, +[method@Gio.FileEnumerator.next_files_async]. Note that the asynchronous +version will return a list of [class@Gio.FileInfo] objects, whereas the synchronous will only return the next file in the enumerator. The ordering of returned files is unspecified for non-Unix -platforms; for more information, see g_dir_read_name(). On Unix, +platforms; for more information, see [method@GLib.Dir.read_name]. On Unix, when operating on local files, returned files will be sorted by inode number. Effectively you can assume that the ordering of returned files will be stable between successive calls (and @@ -34950,10 +35859,10 @@ If your application needs a specific ordering, such as by name or modification time, you will have to implement that in your application code. -To close a #GFileEnumerator, use g_file_enumerator_close(), or -its asynchronous version, g_file_enumerator_close_async(). Once -a #GFileEnumerator is closed, no further actions may be performed -on it, and it should be freed with g_object_unref(). +To close a `GFileEnumerator`, use [method@Gio.FileEnumerator.close], or +its asynchronous version, [method@Gio.FileEnumerator.close_async]. Once +a `GFileEnumerator` is closed, no further actions may be performed +on it, and it should be freed with [method@GObject.Object.unref]. Asynchronously closes the file enumerator. @@ -35548,6 +36457,7 @@ priority is %G_PRIORITY_DEFAULT. + The container that is being enumerated. @@ -35752,26 +36662,25 @@ priority is %G_PRIORITY_DEFAULT. - GFileIOStream provides io streams that both read and write to the same + `GFileIOStream` provides I/O streams that both read and write to the same file handle. -GFileIOStream implements #GSeekable, which allows the io +`GFileIOStream` implements [iface@Gio.Seekable], which allows the I/O stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. -To find the position of a file io stream, use -g_seekable_tell(). +To find the position of a file I/O stream, use [method@Gio.Seekable.tell]. -To find out if a file io stream supports seeking, use g_seekable_can_seek(). -To position a file io stream, use g_seekable_seek(). -To find out if a file io stream supports truncating, use -g_seekable_can_truncate(). To truncate a file io -stream, use g_seekable_truncate(). +To find out if a file I/O stream supports seeking, use +[method@Gio.Seekable.can_seek]. To position a file I/O stream, use +[method@Gio.Seekable.seek]. To find out if a file I/O stream supports +truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file I/O +stream, use [method@Gio.Seekable.truncate]. -The default implementation of all the #GFileIOStream operations -and the implementation of #GSeekable just call into the same operations -on the output stream. +The default implementation of all the `GFileIOStream` operations +and the implementation of [iface@Gio.Seekable] just call into the same +operations on the output stream. @@ -35865,7 +36774,8 @@ g_file_io_stream_query_info(). - the [I/O priority][gio-GIOScheduler] of the request + the [I/O priority](iface.AsyncResult.html#io-priority) of the + request @@ -36018,7 +36928,8 @@ g_file_io_stream_query_info(). - the [I/O priority][gio-GIOScheduler] of the request + the [I/O priority](iface.AsyncResult.html#io-priority) of the + request @@ -36177,7 +37088,8 @@ by g_file_io_stream_query_info_async(). - the [I/O priority][gio-GIOScheduler] of the request + the [I/O priority](iface.AsyncResult.html#io-priority) of the + request @@ -36266,8 +37178,10 @@ by g_file_io_stream_query_info_async(). - #GFileIcon specifies an icon by pointing to an image file -to be used as icon. + `GFileIcon` specifies an icon by pointing to an image file +to be used as icon. + +It implements [iface@Gio.LoadableIcon]. @@ -37405,7 +38319,7 @@ to be used as icon. - an optional [entity tag][gfile-etag] + an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore @@ -37436,7 +38350,7 @@ to be used as icon. - an [entity tag][gfile-etag] for the current #GFile, + an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore @@ -38191,8 +39105,7 @@ to be used as icon. a #GFileMonitor for the given @file, - or %NULL on error. - Free the returned object with g_object_unref(). + or %NULL on error. Free the returned object with g_object_unref(). @@ -38398,7 +39311,7 @@ to be used as icon. - an optional [entity tag][gfile-etag] + an optional [entity tag](#entity-tags) for the current #GFile, or #NULL to ignore @@ -38429,7 +39342,7 @@ to be used as icon. - an [entity tag][gfile-etag] for the current #GFile, + an [entity tag](#entity-tags) for the current #GFile, or %NULL to ignore @@ -38747,8 +39660,8 @@ otherwise. - - + + %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. @@ -38767,7 +39680,7 @@ otherwise. optional #GCancellable - + a #GFileMeasureProgressCallback @@ -38864,40 +39777,42 @@ otherwise. - Functionality for manipulating basic metadata for files. #GFileInfo + Stores information about a file system object referenced by a [iface@Gio.File]. + +Functionality for manipulating basic metadata for files. `GFileInfo` implements methods for getting information that all files should contain, and allows for manipulation of extended attributes. -See [GFileAttribute][gio-GFileAttribute] for more information on how -GIO handles file attributes. +See [file-attributes.html](file attributes) for more information on how GIO +handles file attributes. -To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its -async variant). To obtain a #GFileInfo for a file input or output -stream, use g_file_input_stream_query_info() or -g_file_output_stream_query_info() (or their async variants). +To obtain a `GFileInfo` for a [iface@Gio.File], use +[method@Gio.File.query_info] (or its async variant). To obtain a `GFileInfo` +for a file input or output stream, use [method@Gio.FileInputStream.query_info] +or [method@Gio.FileOutputStream.query_info] (or their async variants). To change the actual attributes of a file, you should then set the -attribute in the #GFileInfo and call g_file_set_attributes_from_info() -or g_file_set_attributes_async() on a GFile. +attribute in the `GFileInfo` and call [method@Gio.File.set_attributes_from_info] +or [method@Gio.File.set_attributes_async] on a `GFile`. However, not all attributes can be changed in the file. For instance, -the actual size of a file cannot be changed via g_file_info_set_size(). -You may call g_file_query_settable_attributes() and -g_file_query_writable_namespaces() to discover the settable attributes +the actual size of a file cannot be changed via [method@Gio.FileInfo.set_size]. +You may call [method@Gio.File.query_settable_attributes] and +[method@Gio.File.query_writable_namespaces] to discover the settable attributes of a particular file at runtime. -The direct accessors, such as g_file_info_get_name(), are slightly more +The direct accessors, such as [method@Gio.FileInfo.get_name], are slightly more optimized than the generic attribute accessors, such as -g_file_info_get_attribute_byte_string().This optimization will matter +[method@Gio.FileInfo.get_attribute_byte_string].This optimization will matter only if calling the API in a tight loop. It is an error to call these accessors without specifying their required file -attributes when creating the #GFileInfo. Use g_file_info_has_attribute() or -g_file_info_list_attributes() to check what attributes are specified for a -#GFileInfo. +attributes when creating the `GFileInfo`. Use +[method@Gio.FileInfo.has_attribute] or [method@Gio.FileInfo.list_attributes] +to check what attributes are specified for a `GFileInfo`. -#GFileAttributeMatcher allows for searching through a #GFileInfo for -attributes. +[struct@Gio.FileAttributeMatcher] allows for searching through a `GFileInfo` +for attributes. Creates a new file info structure. @@ -39339,7 +40254,7 @@ It is an error to call this if the #GFileInfo does not contain - Gets the [entity tag][gfile-etag] for a given + Gets the [entity tag](iface.File.html#entity-tags) for a given #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. It is an error to call this if the #GFileInfo does not contain @@ -40226,15 +41141,15 @@ is set. - GFileInputStream provides input streams that take their + `GFileInputStream` provides input streams that take their content from a file. -GFileInputStream implements #GSeekable, which allows the input +`GFileInputStream` implements [iface@Gio.Seekable], which allows the input stream to jump to arbitrary positions in the file, provided the filesystem of the file allows it. To find the position of a file -input stream, use g_seekable_tell(). To find out if a file input -stream supports seeking, use g_seekable_can_seek(). -To position a file input stream, use g_seekable_seek(). +input stream, use [method@Gio.Seekable.tell]. To find out if a file input +stream supports seeking, use [iface@Gio.Seekable.can_seek]. +To position a file input stream, use [iface@Gio.Seekable.seek]. @@ -40693,17 +41608,16 @@ result. Always check the async result to get the final value. Monitors a file or directory for changes. -To obtain a #GFileMonitor for a file or directory, use -g_file_monitor(), g_file_monitor_file(), or -g_file_monitor_directory(). +To obtain a `GFileMonitor` for a file or directory, use +[method@Gio.File.monitor], [method@Gio.File.monitor_file], or +[method@Gio.File.monitor_directory]. To get informed about changes to the file or directory you are -monitoring, connect to the #GFileMonitor::changed signal. The -signal will be emitted in the -[thread-default main context][g-main-context-push-thread-default] -of the thread that the monitor was created in -(though if the global default main context is blocked, this may -cause notifications to be blocked even if the thread-default +monitoring, connect to the [signal@Gio.FileMonitor::changed] signal. The +signal will be emitted in the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) of the thread that the monitor +was created in (though if the global default main context is blocked, this +may cause notifications to be blocked even if the thread-default context is still running). Cancels a file monitor. @@ -40812,9 +41726,11 @@ consecutive change events to the same file. + Whether the monitor has been cancelled. + The limit of the monitor to watch for changes, in milliseconds. @@ -41018,20 +41934,20 @@ In all the other cases, @other_file will be set to #NULL. - GFileOutputStream provides output streams that write their + `GFileOutputStream` provides output streams that write their content to a file. -GFileOutputStream implements #GSeekable, which allows the output +`GFileOutputStream` implements [iface@Gio.Seekable], which allows the output stream to jump to arbitrary positions in the file and to truncate the file, provided the filesystem of the file supports these operations. -To find the position of a file output stream, use g_seekable_tell(). +To find the position of a file output stream, use [method@Gio.Seekable.tell]. To find out if a file output stream supports seeking, use -g_seekable_can_seek().To position a file output stream, use -g_seekable_seek(). To find out if a file output stream supports -truncating, use g_seekable_can_truncate(). To truncate a file output -stream, use g_seekable_truncate(). +[method@Gio.Seekable.can_seek].To position a file output stream, use +[method@Gio.Seekable.seek]. To find out if a file output stream supports +truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file output +stream, use [method@Gio.Seekable.truncate]. @@ -41125,7 +42041,8 @@ g_file_output_stream_query_info(). - the [I/O priority][gio-GIOScheduler] of the request + the [I/O priority](iface.AsyncResult.html#io-priority) of the + request @@ -41277,7 +42194,8 @@ g_file_output_stream_query_info(). - the [I/O priority][gio-GIOScheduler] of the request + the [I/O priority](iface.AsyncResult.html#io-priority) of the + request @@ -41435,7 +42353,8 @@ by g_file_output_stream_query_info_async(). - the [I/O priority][gio-GIOScheduler] of the request + the [I/O priority](iface.AsyncResult.html#io-priority) of the + request @@ -41797,9 +42716,11 @@ closed. + The underlying base stream on which the I/O ops will be done. + Whether the base stream should be closed when the filter stream is closed. @@ -41887,6 +42808,7 @@ closed. + Whether the base stream should be closed when the filter stream is closed. @@ -42197,6 +43119,9 @@ See also #GPollableReturn for a cheaper way of returning No such device found. Since 2.74 + + Destination address unset. Since 2.80 + #GIOExtension is an opaque data structure and can only be accessed @@ -42259,8 +43184,57 @@ associated with @extension. - #GIOExtensionPoint is an opaque data structure and can only be accessed -using the following functions. + `GIOExtensionPoint` provides a mechanism for modules to extend the +functionality of the library or application that loaded it in an +organized fashion. + +An extension point is identified by a name, and it may optionally +require that any implementation must be of a certain type (or derived +thereof). Use [func@Gio.IOExtensionPoint.register] to register an +extension point, and [method@Gio.IOExtensionPoint.set_required_type] to +set a required type. + +A module can implement an extension point by specifying the +[type@GObject.Type] that implements the functionality. Additionally, each +implementation of an extension point has a name, and a priority. Use +[func@Gio.IOExtensionPoint.implement] to implement an extension point. + +```c +GIOExtensionPoint *ep; + +// Register an extension point +ep = g_io_extension_point_register ("my-extension-point"); +g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); +``` + +```c +// Implement an extension point +G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) +g_io_extension_point_implement ("my-extension-point", + my_example_impl_get_type (), + "my-example", + 10); +``` + + It is up to the code that registered the extension point how + it uses the implementations that have been associated with it. + Depending on the use case, it may use all implementations, or + only the one with the highest priority, or pick a specific + one by name. + + To avoid opening all modules just to find out what extension + points they implement, GIO makes use of a caching mechanism, + see [gio-querymodules](gio-querymodules.html). + You are expected to run this command after installing a + GIO module. + + The `GIO_EXTRA_MODULES` environment variable can be used to + specify additional directories to automatically load modules + from. This environment variable has the same syntax as the + `PATH`. If two modules have the same base name in different + directories, then the latter one will be ignored. If additional + directories are specified GIO will load modules from the built-in + directory last. Finds a #GIOExtension for an extension point by name. @@ -42562,9 +43536,11 @@ in this scope. basename as previously loaded module. - + Opaque class for defining and scheduling IO jobs. - + Use [struct@GLib.ThreadPool] or + [method@Gio.Task.run_in_thread] + Used from an I/O job to send a callback to be run in the thread that the job was started from, waiting for the result (and thus blocking the I/O job). @@ -42592,7 +43568,7 @@ blocking the I/O job). - + Used from an I/O job to send a callback to be run asynchronously in the thread that the job was started from. The callback will be run when the main loop is available, but at that time the I/O job might @@ -42626,11 +43602,13 @@ g_io_scheduler_push_job() or by using refcounting for @user_data. - + I/O Job function. Long-running jobs should periodically check the @cancellable to see if they have been cancelled. + Use [struct@GLib.ThreadPool] or + [method@Gio.Task.run_in_thread] %TRUE if this function should be called again to complete the job, %FALSE if the job is complete (or cancelled) @@ -42652,52 +43630,54 @@ to see if they have been cancelled. - GIOStream represents an object that has both read and write streams. + `GIOStream` represents an object that has both read and write streams. Generally the two streams act as separate input and output streams, but they share some common resources and state. For instance, for seekable streams, both streams may use the same position. -Examples of #GIOStream objects are #GSocketConnection, which represents -a two-way network connection; and #GFileIOStream, which represents a +Examples of `GIOStream` objects are [class@Gio.SocketConnection], which represents +a two-way network connection; and [class@Gio.FileIOStream], which represents a file handle opened in read-write mode. To do the actual reading and writing you need to get the substreams -with g_io_stream_get_input_stream() and g_io_stream_get_output_stream(). +with [method@Gio.IOStream.get_input_stream] and +[method@Gio.IOStream.get_output_stream]. -The #GIOStream object owns the input and the output streams, not the other -way around, so keeping the substreams alive will not keep the #GIOStream -object alive. If the #GIOStream object is freed it will be closed, thus +The `GIOStream` object owns the input and the output streams, not the other +way around, so keeping the substreams alive will not keep the `GIOStream` +object alive. If the `GIOStream` object is freed it will be closed, thus closing the substreams, so even if the substreams stay alive they will -always return %G_IO_ERROR_CLOSED for all operations. +always return `G_IO_ERROR_CLOSED` for all operations. -To close a stream use g_io_stream_close() which will close the common +To close a stream use [method@Gio.IOStream.close] which will close the common stream object and also the individual substreams. You can also close the substreams themselves. In most cases this only marks the substream as closed, so further I/O on it fails but common state in the -#GIOStream may still be open. However, some streams may support -"half-closed" states where one direction of the stream is actually shut down. - -Operations on #GIOStreams cannot be started while another operation on the -#GIOStream or its substreams is in progress. Specifically, an application can -read from the #GInputStream and write to the #GOutputStream simultaneously -(either in separate threads, or as asynchronous operations in the same -thread), but an application cannot start any #GIOStream operation while there -is a #GIOStream, #GInputStream or #GOutputStream operation in progress, and -an application can’t start any #GInputStream or #GOutputStream operation -while there is a #GIOStream operation in progress. +`GIOStream` may still be open. However, some streams may support +‘half-closed’ states where one direction of the stream is actually shut down. + +Operations on `GIOStream`s cannot be started while another operation on the +`GIOStream` or its substreams is in progress. Specifically, an application can +read from the [class@Gio.InputStream] and write to the +[class@Gio.OutputStream] simultaneously (either in separate threads, or as +asynchronous operations in the same thread), but an application cannot start +any `GIOStream` operation while there is a `GIOStream`, `GInputStream` or +`GOutputStream` operation in progress, and an application can’t start any +`GInputStream` or `GOutputStream` operation while there is a `GIOStream` +operation in progress. This is a product of individual stream operations being associated with a -given #GMainContext (the thread-default context at the time the operation was -started), rather than entire streams being associated with a single -#GMainContext. +given [type@GLib.MainContext] (the thread-default context at the time the +operation was started), rather than entire streams being associated with a +single `GMainContext`. -GIO may run operations on #GIOStreams from other (worker) threads, and this +GIO may run operations on `GIOStream`s from other (worker) threads, and this may be exposed to application code in the behaviour of wrapper streams, such -as #GBufferedInputStream or #GTlsConnection. With such wrapper APIs, -application code may only run operations on the base (wrapped) stream when -the wrapper stream is idle. Note that the semantics of such operations may -not be well-defined due to the state the wrapper stream leaves the base -stream in (though they are guaranteed not to crash). +as [class@Gio.BufferedInputStream] or [class@Gio.TlsConnection]. With such +wrapper APIs, application code may only run operations on the base (wrapped) +stream when the wrapper stream is idle. Note that the semantics of such +operations may not be well-defined due to the state the wrapper stream leaves +the base stream in (though they are guaranteed not to crash). Finishes an asynchronous io stream splice operation. @@ -43039,13 +44019,16 @@ result of the operation. - + + Whether the stream is closed. - + + The [class@Gio.InputStream] to read from. - + + The [class@Gio.OutputStream] to write to. @@ -44672,34 +45655,35 @@ Do not free. - #GIcon is a very minimal interface for icons. It provides functions + `GIcon` is a very minimal interface for icons. It provides functions for checking the equality of two icons, hashing of icons and serializing an icon to and from strings. -#GIcon does not provide the actual pixmap for the icon as this is out -of GIO's scope, however implementations of #GIcon may contain the name -of an icon (see #GThemedIcon), or the path to an icon (see #GLoadableIcon). +`GIcon` does not provide the actual pixmap for the icon as this is out +of GIO's scope, however implementations of `GIcon` may contain the name +of an icon (see [class@Gio.ThemedIcon]), or the path to an icon +(see [iface@Gio.LoadableIcon]). -To obtain a hash of a #GIcon, see g_icon_hash(). +To obtain a hash of a `GIcon`, see [method@Gio.Icon.hash]. -To check if two #GIcons are equal, see g_icon_equal(). +To check if two `GIcon`s are equal, see [method@Gio.Icon.equal]. -For serializing a #GIcon, use g_icon_serialize() and -g_icon_deserialize(). +For serializing a `GIcon`, use [method@Gio.Icon.serialize] and +[func@Gio.Icon.deserialize]. -If you want to consume #GIcon (for example, in a toolkit) you must +If you want to consume `GIcon` (for example, in a toolkit) you must be prepared to handle at least the three following cases: -#GLoadableIcon, #GThemedIcon and #GEmblemedIcon. It may also make -sense to have fast-paths for other cases (like handling #GdkPixbuf -directly, for example) but all compliant #GIcon implementations -outside of GIO must implement #GLoadableIcon. +[iface@Gio.LoadableIcon], [class@Gio.ThemedIcon] and [class@Gio.EmblemedIcon]. +It may also make sense to have fast-paths for other cases (like handling +[class@GdkPixbuf.Pixbuf] directly, for example) but all compliant `GIcon` +implementations outside of GIO must implement [iface@Gio.LoadableIcon]. -If your application or library provides one or more #GIcon +If your application or library provides one or more `GIcon` implementations you need to ensure that your new implementation also -implements #GLoadableIcon. Additionally, you must provide an -implementation of g_icon_serialize() that gives a result that is -understood by g_icon_deserialize(), yielding one of the built-in icon -types. +implements [iface@Gio.LoadableIcon]. Additionally, you must provide an +implementation of [method@Gio.Icon.serialize] that gives a result that is +understood by [func@Gio.Icon.deserialize], yielding one of the built-in +icon types. Deserializes a #GIcon previously serialized using g_icon_serialize(). @@ -44753,7 +45737,7 @@ with the type system prior to calling g_icon_new_for_string(). Gets a hash for an icon. a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. + use in a #GHashTable or similar data structure. @@ -44826,7 +45810,7 @@ This is can be invoked when g_icon_new_for_string() is called. Gets a hash for an icon. a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. + use in a #GHashTable or similar data structure. @@ -44895,7 +45879,7 @@ examples of how to implement this interface. a #guint containing a hash for the @icon, suitable for -use in a #GHashTable or similar data structure. + use in a #GHashTable or similar data structure. @@ -44983,15 +45967,15 @@ use in a #GHashTable or similar data structure. - #GInetAddress represents an IPv4 or IPv6 internet address. Use -g_resolver_lookup_by_name() or g_resolver_lookup_by_name_async() to -look up the #GInetAddress for a hostname. Use -g_resolver_lookup_by_address() or -g_resolver_lookup_by_address_async() to look up the hostname for a -#GInetAddress. + `GInetAddress` represents an IPv4 or IPv6 internet address. Use +[method@Gio.Resolver.lookup_by_name] or +[method@Gio.Resolver.lookup_by_name_async] to look up the `GInetAddress` for +a hostname. Use [method@Gio.Resolver.lookup_by_address] or +[method@Gio.Resolver.lookup_by_address_async] to look up the hostname for a +`GInetAddress`. To actually connect to a remote host, you will need a -#GInetSocketAddress (which includes a #GInetAddress as well as a +[class@Gio.InetSocketAddress] (which includes a `GInetAddress` as well as a port number). Creates a #GInetAddress for the "any" address (unassigned/"don't @@ -45298,10 +46282,12 @@ freed after use. - + + The raw address data. - + + The address family (IPv4 or IPv6). @@ -45398,10 +46384,10 @@ array can be gotten with g_inet_address_get_native_size(). - #GInetAddressMask represents a range of IPv4 or IPv6 addresses + `GInetAddressMask` represents a range of IPv4 or IPv6 addresses described by a base address and a length indicating how many bits of the base address are relevant for matching purposes. These are -often given in string form. Eg, "10.0.0.0/8", or "fe80::/10". +often given in string form. For example, `10.0.0.0/8`, or `fe80::/10`. Creates a new #GInetAddressMask representing all addresses whose @@ -45525,13 +46511,16 @@ on error. - + + The base address. - + + The address family (IPv4 or IPv6). - + + The prefix length, in bytes. @@ -45549,8 +46538,11 @@ on error. - An IPv4 or IPv6 socket address; that is, the combination of a -#GInetAddress and a port number. + An IPv4 or IPv6 socket address. That is, the combination of a +[class@Gio.InetAddress] and a port number. + +In UNIX terms, `GInetSocketAddress` corresponds to a +[`struct sockaddr_in` or `struct sockaddr_in6`](man:sockaddr(3type)). Creates a new #GInetSocketAddress for @address and @port. @@ -45645,17 +46637,20 @@ which must be an IPv6 address. - + + The address. The `sin6_flowinfo` field, for IPv6 addresses. - + + The port. - + + The `sin6_scope_id` field, for IPv6 addresses. @@ -45672,28 +46667,28 @@ which must be an IPv6 address. - #GInitable is implemented by objects that can fail during + `GInitable` is implemented by objects that can fail during initialization. If an object implements this interface then it must be initialized as the first thing after construction, -either via g_initable_init() or g_async_initable_init_async() -(the latter is only available if it also implements #GAsyncInitable). +either via [method@Gio.Initable.init] or [method@Gio.AsyncInitable.init_async] +(the latter is only available if it also implements [iface@Gio.AsyncInitable]). If the object is not initialized, or initialization returns with an -error, then all operations on the object except g_object_ref() and -g_object_unref() are considered to be invalid, and have undefined -behaviour. They will often fail with g_critical() or g_warning(), but -this must not be relied on. +error, then all operations on the object except `g_object_ref()` and +`g_object_unref()` are considered to be invalid, and have undefined +behaviour. They will often fail with [func@GLib.critical] or +[func@GLib.warning], but this must not be relied on. Users of objects implementing this are not intended to use the interface method directly, instead it will be used automatically in various ways. For C applications you generally just call -g_initable_new() directly, or indirectly via a foo_thing_new() wrapper. -This will call g_initable_init() under the cover, returning %NULL and -setting a #GError on failure (at which point the instance is +[func@Gio.Initable.new] directly, or indirectly via a `foo_thing_new()` wrapper. +This will call [method@Gio.Initable.init] under the cover, returning `NULL` +and setting a `GError` on failure (at which point the instance is unreferenced). For bindings in languages where the native constructor supports -exceptions the binding could check for objects implementing %GInitable +exceptions the binding could check for objects implementing `GInitable` during normal construction and automatically initialize them, throwing an exception on failure. @@ -45990,15 +46985,17 @@ Flags relevant to this message will be returned in @flags. For example, - #GInputStream has functions to read from a stream (g_input_stream_read()), -to close a stream (g_input_stream_close()) and to skip some content -(g_input_stream_skip()). + `GInputStream` is a base class for implementing streaming input. + +It has functions to read from a stream ([method@Gio.InputStream.read]), +to close a stream ([method@Gio.InputStream.close]) and to skip some content +([method@Gio.InputStream.skip]). To copy the content of an input stream to an output stream without -manually handling the reads and writes, use g_output_stream_splice(). +manually handling the reads and writes, use [method@Gio.OutputStream.splice]. -See the documentation for #GIOStream for details of thread safety of -streaming APIs. +See the documentation for [class@Gio.IOStream] for details of thread safety +of streaming APIs. All of these functions have async variants too. @@ -47189,68 +48186,70 @@ first buffer, switching to the next as needed. - #GListModel is an interface that represents a mutable list of -#GObjects. Its main intention is as a model for various widgets in -user interfaces, such as list views, but it can also be used as a + `GListModel` is an interface that represents a mutable list of +[class@GObject.Object]. Its main intention is as a model for various widgets +in user interfaces, such as list views, but it can also be used as a convenient method of returning lists of data, with support for updates. Each object in the list may also report changes in itself via some -mechanism (normally the #GObject::notify signal). Taken together -with the #GListModel::items-changed signal, this provides for a list -that can change its membership, and in which the members can change -their individual properties. +mechanism (normally the [signal@GObject.Object::notify] signal). Taken +together with the [signal@Gio.ListModel::items-changed] signal, this provides +for a list that can change its membership, and in which the members can +change their individual properties. A good example would be the list of visible wireless network access points, where each access point can report dynamic properties such as signal strength. -It is important to note that the #GListModel itself does not report +It is important to note that the `GListModel` itself does not report changes to the individual items. It only reports changes to the list membership. If you want to observe changes to the objects themselves then you need to connect signals to the objects that you are interested in. -All items in a #GListModel are of (or derived from) the same type. -g_list_model_get_item_type() returns that type. The type may be an +All items in a `GListModel` are of (or derived from) the same type. +[method@Gio.ListModel.get_item_type] returns that type. The type may be an interface, in which case all objects in the list must implement it. The semantics are close to that of an array: -g_list_model_get_n_items() returns the number of items in the list and -g_list_model_get_item() returns an item at a (0-based) position. In -order to allow implementations to calculate the list length lazily, +[method@Gio.ListModel.get_n_items] returns the number of items in the list +and [method@Gio.ListModel.get_item] returns an item at a (0-based) position. +In order to allow implementations to calculate the list length lazily, you can also iterate over items: starting from 0, repeatedly call -g_list_model_get_item() until it returns %NULL. +[method@Gio.ListModel.get_item] until it returns `NULL`. An implementation may create objects lazily, but must take care to return the same object for a given position until all references to it are gone. On the other side, a consumer is expected only to hold references on -objects that are currently "user visible", in order to facilitate the +objects that are currently ‘user visible’, in order to facilitate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time. This interface is intended only to be used from a single thread. The thread in which it is appropriate to use it depends on the particular implementation, but typically it will be from the thread that owns -the [thread-default main context][g-main-context-push-thread-default] -in effect at the time that the model was created. +the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) in effect at the time that the +model was created. -Over time, it has established itself as good practice for listmodel +Over time, it has established itself as good practice for list model implementations to provide properties `item-type` and `n-items` to ease working with them. While it is not required, it is recommended that implementations provide these two properties. They should return -the values of g_list_model_get_item_type() and g_list_model_get_n_items() -respectively and be defined as such: -|[<!-- language="C" --> +the values of [method@Gio.ListModel.get_item_type] and +[method@Gio.ListModel.get_n_items] respectively and be defined as such: + +```c properties[PROP_ITEM_TYPE] = - g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT, + g_param_spec_gtype ("item-type", NULL, NULL, G_TYPE_OBJECT, G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS); properties[PROP_N_ITEMS] = - g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0, + g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0, G_PARAM_READABLE | G_PARAM_STATIC_STRINGS); -]| +``` Get the item at @position. If @position is greater than the number of items in @list, %NULL is returned. @@ -47524,8 +48523,8 @@ in the model change. - #GListStore is a simple implementation of #GListModel that stores all -items in memory. + `GListStore` is a simple implementation of [iface@Gio.ListModel] that stores +all items in memory. It provides insertions, deletions, and lookups in logarithmic time with a fast path for the common case of iterating the list linearly. @@ -47829,8 +48828,8 @@ subclasses of #GObject. - Extends the #GIcon interface and adds the ability to -load icons from streams. + `GLoadableIcon` extends the [iface@Gio.Icon] interface and adds the ability +to load icons from streams. Loads a loadable icon. For the asynchronous version of this function, @@ -48289,11 +49288,11 @@ See also g_menu_item_set_link(). - #GMemoryInputStream is a class for using arbitrary + `GMemoryInputStream` is a class for using arbitrary memory chunks as input for GIO streaming input operations. -As of GLib 2.34, #GMemoryInputStream implements -#GPollableInputStream. +As of GLib 2.34, `GMemoryInputStream` implements +[iface@Gio.PollableInputStream]. @@ -48430,9 +49429,10 @@ As of GLib 2.34, #GMemoryInputStream implements - #GMemoryMonitor will monitor system memory and suggest to the application + `GMemoryMonitor` will monitor system memory and suggest to the application when to free memory so as to leave more room for other applications. -It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) +It is implemented on Linux using the +[Low Memory Monitor](https://gitlab.freedesktop.org/hadess/low-memory-monitor/) ([API documentation](https://hadess.pages.freedesktop.org/low-memory-monitor/)). There is also an implementation for use inside Flatpak sandboxes. @@ -48440,11 +49440,11 @@ There is also an implementation for use inside Flatpak sandboxes. Possible actions to take when the signal is received are: - Free caches - - Save files that haven't been looked at in a while to disk, ready to be reopened when needed + - Save files that haven’t been looked at in a while to disk, ready to be reopened when needed - Run a garbage collection cycle - Try and compress fragmented allocations - Exit on idle if the process has no reason to stay around - - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + - Call [`malloc_trim(3)`](man:malloc_trim(3)) to return cached heap pages to the kernel (if supported by your libc) Note that some actions may not always improve system performance, and so @@ -48452,9 +49452,10 @@ should be profiled for your application. `malloc_trim()`, for example, may make future heap allocations slower (due to releasing cached heap pages back to the kernel). -See #GMemoryMonitorWarningLevel for details on the various warning levels. +See [type@Gio.MemoryMonitorWarningLevel] for details on the various warning +levels. -|[<!-- language="C" --> +```c static void warning_cb (GMemoryMonitor *m, GMemoryMonitorWarningLevel level) { @@ -48472,10 +49473,10 @@ monitor_low_memory (void) G_CALLBACK (warning_cb), NULL); return m; } -]| +``` -Don't forget to disconnect the #GMemoryMonitor::low-memory-warning -signal, and unref the #GMemoryMonitor itself when exiting. +Don’t forget to disconnect the [signal@Gio.MemoryMonitor::low-memory-warning] +signal, and unref the `GMemoryMonitor` itself when exiting. Gets a reference to the default #GMemoryMonitor for the system. @@ -48561,11 +49562,11 @@ if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) - #GMemoryOutputStream is a class for using arbitrary + `GMemoryOutputStream` is a class for using arbitrary memory chunks as output for GIO streaming output operations. -As of GLib 2.34, #GMemoryOutputStream trivially implements -#GPollableOutputStream: it always polls as ready. +As of GLib 2.34, `GMemoryOutputStream` trivially implements +[iface@Gio.PollableOutputStream]: it always polls as ready. @@ -48802,14 +49803,14 @@ freed using the free function set in @ostream's - #GMenu is a simple implementation of #GMenuModel. -You populate a #GMenu by adding #GMenuItem instances to it. + `GMenu` is a simple implementation of [class@Gio.MenuModel]. +You populate a `GMenu` by adding [class@Gio.MenuItem] instances to it. There are some convenience functions to allow you to directly -add items (avoiding #GMenuItem) for the common cases. To add -a regular item, use g_menu_insert(). To add a section, use -g_menu_insert_section(). To add a submenu, use -g_menu_insert_submenu(). +add items (avoiding [class@Gio.MenuItem]) for the common cases. To add +a regular item, use [method@Gio.Menu.insert]. To add a section, use +[method@Gio.Menu.insert_section]. To add a submenu, use +[method@Gio.Menu.insert_submenu]. Creates a new #GMenu. @@ -50019,7 +51020,7 @@ at all). - #GMenuModel represents the contents of a menu -- an ordered list of + `GMenuModel` represents the contents of a menu — an ordered list of menu items. The items are associated with actions, which can be activated through them. Items can be grouped in sections, and may have submenus associated with them. Both items and sections usually @@ -50027,20 +51028,20 @@ have some representation data, such as labels or icons. The type of the associated action (ie whether it is stateful, and what kind of state it has) can influence the representation of the item. -The conceptual model of menus in #GMenuModel is hierarchical: -sections and submenus are again represented by #GMenuModels. +The conceptual model of menus in `GMenuModel` is hierarchical: +sections and submenus are again represented by `GMenuModel`s. Menus themselves do not define their own roles. Rather, the role -of a particular #GMenuModel is defined by the item that references -it (or, in the case of the 'root' menu, is defined by the context +of a particular `GMenuModel` is defined by the item that references +it (or, in the case of the ‘root’ menu, is defined by the context in which it is used). As an example, consider the visible portions of this menu: -## An example menu # {#menu-example} +## An example menu ![](menu-example.png) -There are 8 "menus" visible in the screenshot: one menubar, two +There are 8 ‘menus’ visible in the screenshot: one menubar, two submenus and 5 sections: - the toplevel menubar (containing 4 items) @@ -50052,17 +51053,17 @@ submenus and 5 sections: - the Sources section (containing 2 items) - the Markup section (containing 2 items) -The [example][menu-model] illustrates the conceptual connection between +The [example](#a-menu-example) illustrates the conceptual connection between these 8 menus. Each large block in the figure represents a menu and the smaller blocks within the large block represent items in that menu. Some items contain references to other menus. -## A menu example # {#menu-model} +## A menu example ![](menu-model.png) -Notice that the separators visible in the [example][menu-example] -appear nowhere in the [menu model][menu-model]. This is because +Notice that the separators visible in the [example](#an-example-menu) +appear nowhere in the [menu model](#a-menu-example). This is because separators are not explicitly represented in the menu model. Instead, a separator is inserted between any two non-empty sections of a menu. Section items can have labels just like any other item. In that case, @@ -50071,32 +51072,32 @@ a display system may show a section header instead of a separator. The motivation for this abstract model of application controls is that modern user interfaces tend to make these controls available outside the application. Examples include global menus, jumplists, -dash boards, etc. To support such uses, it is necessary to 'export' +dash boards, etc. To support such uses, it is necessary to ‘export’ information about actions and their representation in menus, which -is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] -and the [GMenuModel exporter][gio-GMenuModel-exporter] do for -#GActionGroup and #GMenuModel. The client-side counterparts to -make use of the exported information are #GDBusActionGroup and -#GDBusMenuModel. - -The API of #GMenuModel is very generic, with iterators for the -attributes and links of an item, see g_menu_model_iterate_item_attributes() -and g_menu_model_iterate_item_links(). The 'standard' attributes and -link types have predefined names: %G_MENU_ATTRIBUTE_LABEL, -%G_MENU_ATTRIBUTE_ACTION, %G_MENU_ATTRIBUTE_TARGET, %G_MENU_LINK_SECTION -and %G_MENU_LINK_SUBMENU. - -Items in a #GMenuModel represent active controls if they refer to +is exactly what the action group exporter and the menu model exporter do for +[iface@Gio.ActionGroup] and [class@Gio.MenuModel]. The client-side +counterparts to make use of the exported information are +[class@Gio.DBusActionGroup] and [class@Gio.DBusMenuModel]. + +The API of `GMenuModel` is very generic, with iterators for the +attributes and links of an item, see +[method@Gio.MenuModel.iterate_item_attributes] and +[method@Gio.MenuModel.iterate_item_links]. The ‘standard’ attributes and +link types have predefined names: `G_MENU_ATTRIBUTE_LABEL`, +`G_MENU_ATTRIBUTE_ACTION`, `G_MENU_ATTRIBUTE_TARGET`, `G_MENU_LINK_SECTION` +and `G_MENU_LINK_SUBMENU`. + +Items in a `GMenuModel` represent active controls if they refer to an action that can get activated when the user interacts with the -menu item. The reference to the action is encoded by the string id -in the %G_MENU_ATTRIBUTE_ACTION attribute. An action id uniquely +menu item. The reference to the action is encoded by the string ID +in the `G_MENU_ATTRIBUTE_ACTION` attribute. An action ID uniquely identifies an action in an action group. Which action group(s) provide actions depends on the context in which the menu model is used. E.g. when the model is exported as the application menu of a -#GtkApplication, actions can be application-wide or window-specific +[class@Gtk.Application], actions can be application-wide or window-specific (and thus come from two different action groups). By convention, the -application-wide actions have names that start with "app.", while the -names of window-specific actions start with "win.". +application-wide actions have names that start with `app.`, while the +names of window-specific actions start with `win.`. While a wide variety of stateful actions is possible, the following is the minimum that is expected to be supported by all users of exported @@ -50113,12 +51114,12 @@ Selecting such a menu item will activate the action (with no parameter). ## Boolean State -An action with a boolean state will most typically be used with a "toggle" -or "switch" menu item. The state can be set directly, but activating the +An action with a boolean state will most typically be used with a ‘toggle’ +or ‘switch’ menu item. The state can be set directly, but activating the action (with no parameter) results in the state being toggled. Selecting a toggle menu item will activate the action. The menu item should -be rendered as "checked" when the state is true. +be rendered as ‘checked’ when the state is true. ## String Parameter and State @@ -50130,7 +51131,7 @@ equivalent to setting that parameter as the state. Radio menu items, in addition to being associated with the action, will have a target value. Selecting that menu item will result in activation of the action with the target value as the parameter. The menu item should -be rendered as "selected" when the state of the action is equal to the +be rendered as ‘selected’ when the state of the action is equal to the target value of the menu item. Queries the item at position @item_index in @model for the attribute @@ -50738,25 +51739,27 @@ reported. The signal is emitted after the modification. - The #GMount interface represents user-visible mounts. Note, when -porting from GnomeVFS, #GMount is the moral equivalent of #GnomeVFSVolume. + The `GMount` interface represents user-visible mounts. Note, when +[porting from GnomeVFS](migrating-gnome-vfs.html), `GMount` is the moral +equivalent of `GnomeVFSVolume`. -#GMount is a "mounted" filesystem that you can access. Mounted is in -quotes because it's not the same as a unix mount, it might be a gvfs +`GMount` is a ‘mounted’ filesystem that you can access. Mounted is in +quotes because it’s not the same as a UNIX mount, it might be a GVFS mount, but you can still access the files on it if you use GIO. Might or might not be related to a volume object. -Unmounting a #GMount instance is an asynchronous operation. For -more information about asynchronous operations, see #GAsyncResult -and #GTask. To unmount a #GMount instance, first call -g_mount_unmount_with_operation() with (at least) the #GMount instance and a -#GAsyncReadyCallback. The callback will be fired when the -operation has resolved (either with success or failure), and a -#GAsyncResult structure will be passed to the callback. That -callback should then call g_mount_unmount_with_operation_finish() with the #GMount -and the #GAsyncResult data to see if the operation was completed -successfully. If an @error is present when g_mount_unmount_with_operation_finish() -is called, then it will be filled with any error information. +Unmounting a `GMount` instance is an asynchronous operation. For +more information about asynchronous operations, see [iface@Gio.AsyncResult] +and [class@Gio.Task]. To unmount a `GMount` instance, first call +[method@Gio.Mount.unmount_with_operation] with (at least) the `GMount` +instance and a [type@Gio.AsyncReadyCallback]. The callback will be fired +when the operation has resolved (either with success or failure), and a +[iface@Gio.AsyncResult] structure will be passed to the callback. That +callback should then call [method@Gio.Mount.unmount_with_operation_finish] +with the `GMount` and the [iface@Gio.AsyncResult] data to see if the +operation was completed successfully. If an `error` is present when +[method@Gio.Mount.unmount_with_operation_finish] is called, then it will be +filled with any error information. Checks if @mount can be ejected. @@ -52490,23 +53493,23 @@ finalized. - #GMountOperation provides a mechanism for interacting with the user. + `GMountOperation` provides a mechanism for interacting with the user. It can be used for authenticating mountable operations, such as loop mounting files, hard drive partitions or server locations. It can also be used to ask the user questions or show a list of applications preventing unmount or eject operations from completing. -Note that #GMountOperation is used for more than just #GMount -objects – for example it is also used in g_drive_start() and -g_drive_stop(). +Note that `GMountOperation` is used for more than just [iface@Gio.Mount] +objects – for example it is also used in [method@Gio.Drive.start] and +[method@Gio.Drive.stop]. Users should instantiate a subclass of this that implements all the various callbacks to show the required dialogs, such as -#GtkMountOperation. If no user interaction is desired (for example -when automounting filesystems at login time), usually %NULL can be -passed, see each method taking a #GMountOperation for details. +[class@Gtk.MountOperation]. If no user interaction is desired (for example +when automounting filesystems at login time), usually `NULL` can be +passed, see each method taking a `GMountOperation` for details. -The term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. +Throughout the API, the term ‘TCRYPT’ is used to mean ‘compatible with TrueCrypt and VeraCrypt’. [TrueCrypt](https://en.wikipedia.org/wiki/TrueCrypt) is a discontinued system for encrypting file containers, partitions or whole disks, typically used with Windows. [VeraCrypt](https://www.veracrypt.fr/) is a maintained fork of TrueCrypt with various @@ -53434,8 +54437,11 @@ See [Extending GIO][extending-gio]. - - A socket address of some unknown native type. + + A socket address of some unknown native type. + +This corresponds to a general `struct sockaddr` of a type not otherwise +handled by GLib. Creates a new #GNativeSocketAddress for @native and @len. @@ -53493,7 +54499,7 @@ See [Extending GIO][extending-gio]. - #GNetworkAddress provides an easy way to resolve a hostname and + `GNetworkAddress` provides an easy way to resolve a hostname and then attempt to connect to that host, handling the possibility of multiple IP addresses and multiple address families. @@ -53501,7 +54507,7 @@ 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 +See [iface@Gio.SocketConnectable] for an example of using the connectable interface. @@ -53653,13 +54659,16 @@ depending on what @addr was created with. - + + Hostname to resolve. - + + Network port. - + + URI scheme. @@ -53697,7 +54706,7 @@ depending on what @addr was created with. - #GNetworkMonitor provides an easy-to-use cross-platform API + `GNetworkMonitor` provides an easy-to-use cross-platform API for monitoring network connectivity. On Linux, the available implementations are based on the kernel's netlink interface and on NetworkManager. @@ -54126,14 +55135,14 @@ See also #GNetworkMonitor:network-available. - Like #GNetworkAddress does with hostnames, #GNetworkService + Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService` provides an easy way to resolve a SRV record, and then attempt to connect to one of the hosts that implements that service, handling service priority/weighting, multiple IP addresses, and multiple address families. -See #GSrvTarget for more information about SRV records, and see -#GSocketConnectable for an example of using the connectable +See [struct@Gio.SrvTarget] for more information about SRV records, and see +[iface@Gio.SocketConnectable] for an example of using the connectable interface. @@ -54230,16 +55239,20 @@ is used as scheme. - + + Network domain, for example `example.com`. - + + Network protocol, for example `tcp`. - + + Network scheme (default is to use service). - + + Service name, for example `ldap`. @@ -54256,50 +55269,51 @@ is used as scheme. - #GNotification is a mechanism for creating a notification to be shown -to the user -- typically as a pop-up notification presented by the + `GNotification` is a mechanism for creating a notification to be shown +to the user — typically as a pop-up notification presented by the desktop environment shell. -The key difference between #GNotification and other similar APIs is +The key difference between `GNotification` and other similar APIs is that, if supported by the desktop environment, notifications sent -with #GNotification will persist after the application has exited, +with `GNotification` will persist after the application has exited, and even across system reboots. Since the user may click on a notification while the application is -not running, applications using #GNotification should be able to be -started as a D-Bus service, using #GApplication. +not running, applications using `GNotification` should be able to be +started as a D-Bus service, using [class@Gio.Application]. -In order for #GNotification to work, the application must have installed +In order for `GNotification` to work, the application must have installed a `.desktop` file. For example: -|[ - [Desktop Entry] - Name=Test Application - Comment=Description of what Test Application does - Exec=gnome-test-application - Icon=org.gnome.TestApplication - Terminal=false - Type=Application - Categories=GNOME;GTK;TestApplication Category; - StartupNotify=true - DBusActivatable=true - X-GNOME-UsesNotifications=true -]| +``` +[Desktop Entry] +Name=Test Application +Comment=Description of what Test Application does +Exec=gnome-test-application +Icon=org.gnome.TestApplication +Terminal=false +Type=Application +Categories=GNOME;GTK;TestApplication Category; +StartupNotify=true +DBusActivatable=true +X-GNOME-UsesNotifications=true +``` The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center that this application uses notifications, so it can be listed in the Control Center’s ‘Notifications’ panel. The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, -where `org.gnome.TestApplication` is the ID passed to g_application_new(). +where `org.gnome.TestApplication` is the ID passed to +[ctor@Gio.Application.new]. User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: -"app." actions). It is not possible to route user interaction +`app.` actions). It is not possible to route user interaction through the notification itself, because the object will not exist if the application is autostarted as a result of a notification being clicked. -A notification can be sent with g_application_send_notification(). +A notification can be sent with [method@Gio.Application.send_notification]. Creates a new #GNotification with @title as its title. @@ -54679,17 +55693,23 @@ If @address is %NULL then the message is sent to the default receiver - #GOutputStream has functions to write to a stream (g_output_stream_write()), -to close a stream (g_output_stream_close()) and to flush pending writes -(g_output_stream_flush()). + `GOutputStream` is a base class for implementing streaming output. + +It has functions to write to a stream ([method@Gio.OutputStream.write]), +to close a stream ([method@Gio.OutputStream.close]) and to flush pending +writes ([method@Gio.OutputStream.flush]). To copy the content of an input stream to an output stream without -manually handling the reads and writes, use g_output_stream_splice(). +manually handling the reads and writes, use [method@Gio.OutputStream.splice]. -See the documentation for #GIOStream for details of thread safety of -streaming APIs. +See the documentation for [class@Gio.IOStream] for details of thread safety +of streaming APIs. -All of these functions have async variants too. +All of these functions have async variants too. + +All classes derived from `GOutputStream` *should* implement synchronous +writing, splicing, flushing and closing streams, but *may* implement +asynchronous versions. Requests an asynchronous close of the stream, releasing resources related to it. When the operation is finished @callback will be @@ -56902,7 +57922,7 @@ to, and later retrieves it again from there. - A #GPermission represents the status of the caller's permission to + A `GPermission` represents the status of the caller’s permission to perform a certain action. You can query if the action is currently allowed and if it is @@ -56912,10 +57932,10 @@ in the future. There is also an API to actually acquire the permission and one to release it. -As an example, a #GPermission might represent the ability for the -user to write to a #GSettings object. This #GPermission object could -then be used to decide if it is appropriate to show a "Click here to -unlock" button in a dialog and to provide the mechanism to invoke +As an example, a `GPermission` might represent the ability for the +user to write to a [class@Gio.Settings] object. This `GPermission` object +could then be used to decide if it is appropriate to show a “Click here to +unlock” button in a dialog and to provide the mechanism to invoke when that button is clicked. Attempts to acquire the permission represented by @permission. @@ -57462,14 +58482,14 @@ g_permission_release(). - #GPollableInputStream is implemented by #GInputStreams that + `GPollableInputStream` is implemented by [class@Gio.InputStream]s that can be polled for readiness to read. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. -Some classes may implement #GPollableInputStream but have only certain -instances of that class be pollable. If g_pollable_input_stream_can_poll() -returns %FALSE, then the behavior of other #GPollableInputStream methods is +Some classes may implement `GPollableInputStream` but have only certain +instances of that class be pollable. If [method@Gio.PollableInputStream.can_poll] +returns false, then the behavior of other `GPollableInputStream` methods is undefined. @@ -57789,14 +58809,14 @@ readable. - #GPollableOutputStream is implemented by #GOutputStreams that + `GPollableOutputStream` is implemented by [class@Gio.OutputStream]s that can be polled for readiness to write. This can be used when interfacing with a non-GIO API that expects UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. -Some classes may implement #GPollableOutputStream but have only certain -instances of that class be pollable. If g_pollable_output_stream_can_poll() -returns %FALSE, then the behavior of other #GPollableOutputStream methods is +Some classes may implement `GPollableOutputStream` but have only certain +instances of that class be pollable. If [method@Gio.PollableOutputStream.can_poll] +returns false, then the behavior of other `GPollableOutputStream` methods is undefined. @@ -58303,10 +59323,10 @@ g_pollable_output_stream_create_source(). - #GPowerProfileMonitor makes it possible for applications as well as OS components -to monitor system power profiles and act upon them. It currently only exports -whether the system is in “Power Saver” mode (known as “Low Power” mode on -some systems). + `GPowerProfileMonitor` makes it possible for applications as well as OS +components to monitor system power profiles and act upon them. It currently +only exports whether the system is in “Power Saver” mode (known as +“Low Power” mode on some systems). When in “Low Power” mode, it is recommended that applications: - disable automatic downloads; @@ -58323,8 +59343,9 @@ monitor the battery discharge rate, `powertop` to check on the background activi or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to profile GPU usage. -Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled -signal, and unref the #GPowerProfileMonitor itself when exiting. +Don’t forget to disconnect the [signal@GObject.Object::notify] signal for +[property@Gio.PowerProfileMonitor:power-saver-enabled], and unref the +`GPowerProfileMonitor` itself when exiting. Gets a reference to the default #GPowerProfileMonitor for the system. @@ -58363,12 +59384,12 @@ changed. - A #GPropertyAction is a way to get a #GAction with a state value -reflecting and controlling the value of a #GObject property. + A `GPropertyAction` is a way to get a [iface@Gio.Action] with a state value +reflecting and controlling the value of a [class@GObject.Object] property. The state of the action will correspond to the value of the property. Changing it will change the property (assuming the requested value -matches the requirements as specified in the #GParamSpec). +matches the requirements as specified in the [type@GObject.ParamSpec]). Only the most common types are presently supported. Booleans are mapped to booleans, strings to strings, signed/unsigned integers to @@ -58376,16 +59397,16 @@ int32/uint32 and floats and doubles to doubles. If the property is an enum then the state will be string-typed and conversion will automatically be performed between the enum value and -"nick" string as per the #GEnumValue table. +‘nick’ string as per the [type@GObject.EnumValue] table. Flags types are not currently supported. Properties of object types, boxed types and pointer types are not supported and probably never will be. -Properties of #GVariant types are not currently supported. +Properties of [type@GLib.Variant] types are not currently supported. -If the property is boolean-valued then the action will have a NULL +If the property is boolean-valued then the action will have a `NULL` parameter type, and activating the action (with no parameter) will toggle the value of the property. @@ -58394,26 +59415,26 @@ the property. The general idea here is to reduce the number of locations where a particular piece of state is kept (and therefore has to be synchronised -between). #GPropertyAction does not have a separate state that is kept -in sync with the property value -- its state is the property value. +between). `GPropertyAction` does not have a separate state that is kept +in sync with the property value — its state is the property value. -For example, it might be useful to create a #GAction corresponding to -the "visible-child-name" property of a #GtkStack so that the current -page can be switched from a menu. The active radio indication in the +For example, it might be useful to create a [iface@Gio.Action] corresponding +to the `visible-child-name` property of a [class@Gtk.Stack] so that the +current page can be switched from a menu. The active radio indication in the menu is then directly determined from the active page of the -#GtkStack. +[class@Gtk.Stack]. -An anti-example would be binding the "active-id" property on a -#GtkComboBox. This is because the state of the combobox itself is +An anti-example would be binding the `active-id` property on a +[class@Gtk.ComboBox]. This is because the state of the combobox itself is probably uninteresting and is actually being used to control something else. -Another anti-example would be to bind to the "visible-child-name" -property of a #GtkStack if this value is actually stored in -#GSettings. In that case, the real source of the value is -#GSettings. If you want a #GAction to control a setting stored in -#GSettings, see g_settings_create_action() instead, and possibly -combine its use with g_settings_bind(). +Another anti-example would be to bind to the `visible-child-name` +property of a [class@Gtk.Stack] if this value is actually stored in +[class@Gio.Settings]. In that case, the real source of the value is +[class@Gio.Settings]. If you want a [iface@Gio.Action] to control a setting +stored in [class@Gio.Settings], see [method@Gio.Settings.create_action] +instead, and possibly combine its use with [method@Gio.Settings.bind]. Creates a #GAction corresponding to the value of property @@ -58490,12 +59511,12 @@ action is stateless. - A #GProxy handles connecting to a remote host via a given type of -proxy server. It is implemented by the 'gio-proxy' extension point. + A `GProxy` handles connecting to a remote host via a given type of +proxy server. It is implemented by the `gio-proxy` extension point. The extensions are named after their proxy protocol name. As an example, a SOCKS5 proxy implementation can be retrieved with the -name 'socks5' using the function -g_io_extension_point_get_extension_by_name(). +name `socks5` using the function +[method@Gio.IOExtensionPoint.get_extension_by_name]. Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. @@ -58709,7 +59730,7 @@ g_proxy_connect() or g_proxy_connect_async(). - Support for proxied #GInetSocketAddress. + A [class@Gio.InetSocketAddress] representing a connection via a proxy server. Creates a new #GProxyAddress for @inetaddr with @protocol that should @@ -58851,10 +59872,12 @@ server; eg, "http" or "ftp". - + + The proxy destination hostname. - + + The proxy destination port. @@ -58862,10 +59885,12 @@ server; eg, "http" or "ftp". the #GProxyAddress doesn't know. - + + The proxy password. - + + The proxy protocol. @@ -58873,7 +59898,8 @@ the #GProxyAddress doesn't know. if the creator didn't specify this). - + + The proxy username. @@ -58890,16 +59916,18 @@ if the creator didn't specify this). - #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which -takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator -and wraps them in #GProxyAddress instances, using the given -#GProxyAddressEnumerator:proxy-resolver. + `GProxyAddressEnumerator` is a wrapper around +[class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress] +instances returned by the [class@Gio.SocketAddressEnumerator] +and wraps them in [class@Gio.ProxyAddress] instances, using the given +[property@Gio.ProxyAddressEnumerator:proxy-resolver]. This enumerator will be returned (for example, by -g_socket_connectable_enumerate()) as appropriate when a proxy is configured; -there should be no need to manually wrap a #GSocketAddressEnumerator instance -with one. +[method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is +configured; there should be no need to manually wrap a +[class@Gio.SocketAddressEnumerator] instance with one. + The connectable being enumerated. @@ -58912,6 +59940,7 @@ specify one. + The destination URI. Use `none://` for a generic socket. @@ -59079,13 +60108,14 @@ specify one. - #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. + `GProxyResolver` provides synchronous and asynchronous network proxy +resolution. `GProxyResolver` is used within [class@Gio.SocketClient] through +the method [method@Gio.SocketConnectable.proxy_enumerate]. + +Implementations of `GProxyResolver` based on +[libproxy](https://github.com/libproxy/libproxy) and GNOME settings can be +found in [glib-networking](https://gitlab.gnome.org/GNOME/glib-networking). +GIO comes with an implementation for use inside Flatpak portals. Gets the default #GProxyResolver for the system. @@ -59456,25 +60486,25 @@ The function should have the same semantics as realloc(). - The GRemoteActionGroup interface is implemented by #GActionGroup + The `GRemoteActionGroup` interface is implemented by [iface@Gio.ActionGroup] instances that either transmit action invocations to other processes or receive action invocations in the local process from other processes. The interface has `_full` variants of the two -methods on #GActionGroup used to activate actions: -g_action_group_activate_action() and -g_action_group_change_action_state(). These variants allow a -"platform data" #GVariant to be specified: a dictionary providing +methods on [iface@Gio.ActionGroup] used to activate actions: +[method@Gio.ActionGroup.activate_action] and +[method@Gio.ActionGroup.change_action_state]. These variants allow a +‘platform data’ [struct@GLib.Variant] to be specified: a dictionary providing context for the action invocation (for example: timestamps, startup notification IDs, etc). -#GDBusActionGroup implements #GRemoteActionGroup. This provides a +[class@Gio.DBusActionGroup] implements `GRemoteActionGroup`. This provides a mechanism to send platform data for action invocations over D-Bus. -Additionally, g_dbus_connection_export_action_group() will check if -the exported #GActionGroup implements #GRemoteActionGroup and use the -`_full` variants of the calls if available. This +Additionally, [method@Gio.DBusConnection.export_action_group] will check if +the exported [iface@Gio.ActionGroup] implements `GRemoteActionGroup` and use +the `_full` variants of the calls if available. This provides a mechanism by which to receive platform data for action invocations that arrive by way of D-Bus. @@ -59664,18 +60694,25 @@ user interaction timestamp or startup notification information. - #GResolver provides cancellable synchronous and asynchronous DNS -resolution, for hostnames (g_resolver_lookup_by_address(), -g_resolver_lookup_by_name() and their async variants) and SRV -(service) records (g_resolver_lookup_service()). - -#GNetworkAddress and #GNetworkService provide wrappers around -#GResolver functionality that also implement #GSocketConnectable, -making it easy to connect to a remote host/service. - -The default resolver (see g_resolver_get_default()) has a timeout of 30s set -on it since GLib 2.78. Earlier versions of GLib did not support resolver -timeouts. + The object that handles DNS resolution. Use [func@Gio.Resolver.get_default] +to get the default resolver. + +`GResolver` provides cancellable synchronous and asynchronous DNS +resolution, for hostnames ([method@Gio.Resolver.lookup_by_address], +[method@Gio.Resolver.lookup_by_name] and their async variants) and SRV +(service) records ([method@Gio.Resolver.lookup_service]). + +[class@Gio.NetworkAddress] and [class@Gio.NetworkService] provide wrappers +around `GResolver` functionality that also implement +[iface@Gio.SocketConnectable], making it easy to connect to a remote +host/service. + +The default resolver (see [func@Gio.Resolver.get_default]) has a timeout of +30s set on it since GLib 2.78. Earlier versions of GLib did not support +resolver timeouts. + +This is an abstract type; subclasses of it implement different resolvers for +different platforms and situations. Frees @addresses (which should be the return value from g_resolver_lookup_by_name() or g_resolver_lookup_by_name_finish()). @@ -59719,6 +60756,30 @@ many threads it should allocate for concurrent DNS resolutions. + + + + + + + + + + + + + + + + + + + + + + + + Synchronously reverse-resolves @address to determine its associated hostname. @@ -61245,67 +62306,82 @@ as a `guint32`, and the TTL as a `guint32`. look up DNS NS records for a domain + + + + + + + + + + Applications and libraries often contain binary or textual data that is really part of the application, rather than user data. For instance -#GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, -icons, etc. These are often shipped as files in `$datadir/appname`, or -manually included as literal strings in the code. - -The #GResource API and the [glib-compile-resources][glib-compile-resources] program -provide a convenient and efficient alternative to this which has some nice properties. You -maintain the files as normal files, so its easy to edit them, but during the build the files -are combined into a binary bundle that is linked into the executable. This means that loading -the resource files are efficient (as they are already in memory, shared with other instances) and -simple (no need to check for things like I/O errors or locate the files in the filesystem). It +[class@Gtk.Builder] `.ui` files, splashscreen images, [class@Gio.Menu] markup +XML, CSS files, icons, etc. These are often shipped as files in +`$datadir/appname`, or manually included as literal strings in the code. + +The `GResource` API and the +[`glib-compile-resources`](glib-compile-resources.html) program provide a +convenient and efficient alternative to this which has some nice properties. +You maintain the files as normal files, so it’s easy to edit them, but during +the build the files are combined into a binary bundle that is linked into the +executable. This means that loading the resource files are efficient (as they +are already in memory, shared with other instances) and simple (no need to +check for things like I/O errors or locate the files in the filesystem). It also makes it easier to create relocatable applications. -Resource files can also be marked as compressed. Such files will be included in the resource bundle -in a compressed form, but will be automatically uncompressed when the resource is used. This -is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. +Resource files can also be marked as compressed. Such files will be included +in the resource bundle in a compressed form, but will be automatically +uncompressed when the resource is used. This is very useful e.g. for larger +text files that are parsed once (or rarely) and then thrown away. Resource files can also be marked to be preprocessed, by setting the value of the `preprocess` attribute to a comma-separated list of preprocessing options. The only options currently supported are: -`xml-stripblanks` which will use the xmllint command -to strip ignorable whitespace from the XML file. For this to work, -the `XMLLINT` environment variable must be set to the full path to -the xmllint executable, or xmllint must be in the `PATH`; otherwise -the preprocessing step is skipped. - -`to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the -`gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format, -which allows you to create pixbufs directly using the data inside the -resource file, rather than an (uncompressed) copy of it. For this, the -`gdk-pixbuf-pixdata` program must be in the `PATH`, or the -`GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the -`gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort. -`to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource -supports embedding modern image formats just as well. Instead of using it, -embed a PNG or SVG file in your #GResource. - -`json-stripblanks` which will use the `json-glib-format` command to strip -ignorable whitespace from the JSON file. For this to work, the -`JSON_GLIB_FORMAT` environment variable must be set to the full path to the -`json-glib-format` executable, or it must be in the `PATH`; -otherwise the preprocessing step is skipped. In addition, at least version -1.6 of `json-glib-format` is required. - -Resource files will be exported in the GResource namespace using the + - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command + to strip ignorable whitespace from the XML file. For this to work, + the `XMLLINT` environment variable must be set to the full path to + the xmllint executable, or xmllint must be in the `PATH`; otherwise + the preprocessing step is skipped. + + - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the + `gdk-pixbuf-pixdata` command to convert images to the [class@Gdk.Pixdata] + format, which allows you to create pixbufs directly using the data inside + the resource file, rather than an (uncompressed) copy of it. For this, the + `gdk-pixbuf-pixdata` program must be in the `PATH`, or the + `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to + the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will + abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as + `GResource` supports embedding modern image formats just as well. Instead + of using it, embed a PNG or SVG file in your `GResource`. + + - `json-stripblanks` which will use the + [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable + whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT` + environment variable must be set to the full path to the + `json-glib-format` executable, or it must be in the `PATH`; otherwise the + preprocessing step is skipped. In addition, at least version 1.6 of + `json-glib-format` is required. + +Resource files will be exported in the `GResource` namespace using the combination of the given `prefix` and the filename from the `file` element. The `alias` attribute can be used to alter the filename to expose them at a different location in the resource namespace. Typically, this is used to include files from a different source directory without exposing the source directory in the resource namespace, as in the example below. -Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program -which takes an XML file that describes the bundle, and a set of files that the XML references. These -are combined into a binary resource bundle. +Resource bundles are created by the +[`glib-compile-resources`](glib-compile-resources.html) program +which takes an XML file that describes the bundle, and a set of files that +the XML references. These are combined into a binary resource bundle. An example resource description: -|[ +```xml <?xml version="1.0" encoding="UTF-8"?> <gresources> <gresource prefix="/org/gtk/Example"> @@ -61315,74 +62391,92 @@ An example resource description: <file alias="example.css">data/example.css</file> </gresource> </gresources> -]| +``` This will create a resource bundle with the following files: -|[ +``` /org/gtk/Example/data/splashscreen.png /org/gtk/Example/dialog.ui /org/gtk/Example/menumarkup.xml /org/gtk/Example/example.css -]| +``` -Note that all resources in the process share the same namespace, so use Java-style -path prefixes (like in the above example) to avoid conflicts. +Note that all resources in the process share the same namespace, so use +Java-style path prefixes (like in the above example) to avoid conflicts. -You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a -binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and ---generate-header arguments to create a source file and header to link directly into your application. +You can then use [`glib-compile-resources`](glib-compile-resources.html) to +compile the XML to a binary bundle that you can load with +[func@Gio.Resource.load]. However, it’s more common to use the +`--generate-source` and `--generate-header` arguments to create a source file +and header to link directly into your application. This will generate `get_resource()`, `register_resource()` and `unregister_resource()` functions, prefixed by the `--c-name` argument passed -to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns -the generated #GResource object. The register and unregister functions -register the resource so its files can be accessed using -g_resources_lookup_data(). - -Once a #GResource has been created and registered all the data in it can be accessed globally in the process by -using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer -to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access -the resource data. - -Some higher-level APIs, such as #GtkApplication, will automatically load -resources from certain well-known paths in the resource namespace as a +to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()` +returns the generated `GResource` object. The register and unregister +functions register the resource so its files can be accessed using +[func@Gio.resources_lookup_data]. + +Once a `GResource` has been created and registered all the data in it can be +accessed globally in the process by using API calls like +[func@Gio.resources_open_stream] to stream the data or +[func@Gio.resources_lookup_data] to get a direct pointer to the data. You can +also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with +[iface@Gio.File] to access the resource data. + +Some higher-level APIs, such as [class@Gtk.Application], will automatically +load resources from certain well-known paths in the resource namespace as a convenience. See the documentation for those APIs for details. -There are two forms of the generated source, the default version uses the compiler support for constructor -and destructor functions (where available) to automatically create and register the #GResource on startup -or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created -instead. This requires an explicit initialization call in your application/library, but it works on all platforms, -even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) - -Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries -during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away -when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses -are for your own resources, and resource data is often used once, during parsing, and then released. - -When debugging a program or testing a change to an installed version, it is often useful to be able to -replace resources in the program or library, without recompiling, for debugging or quick hacking and testing -purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay -resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform -during resource lookups. It is ignored when running in a setuid process. +There are two forms of the generated source, the default version uses the +compiler support for constructor and destructor functions (where available) +to automatically create and register the `GResource` on startup or library +load time. If you pass `--manual-register`, two functions to +register/unregister the resource are created instead. This requires an +explicit initialization call in your application/library, but it works on all +platforms, even on the minor ones where constructors are not supported. +(Constructor support is available for at least Win32, Mac OS and Linux.) + +Note that resource data can point directly into the data segment of e.g. a +library, so if you are unloading libraries during runtime you need to be very +careful with keeping around pointers to data from a resource, as this goes +away when the library is unloaded. However, in practice this is not generally +a problem, since most resource accesses are for your own resources, and +resource data is often used once, during parsing, and then released. + +# Overlays + +When debugging a program or testing a change to an installed version, it is +often useful to be able to replace resources in the program or library, +without recompiling, for debugging or quick hacking and testing purposes. +Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment +variable to selectively overlay resources with replacements from the +filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions +to perform during resource lookups. It is ignored when running in a setuid +process. A substitution has the form -|[ - /org/gtk/libgtk=/home/desrt/gtk-overlay -]| +``` +/org/gtk/libgtk=/home/desrt/gtk-overlay +``` -The part before the `=` is the resource subpath for which the overlay applies. The part after is a -filesystem path which contains files and subdirectories as you would like to be loaded as resources with the +The part before the `=` is the resource subpath for which the overlay +applies. The part after is a filesystem path which contains files and +subdirectories as you would like to be loaded as resources with the equivalent names. -In the example above, if an application tried to load a resource with the resource path -`/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path -`/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an -overlay, not an outright replacement, which means that if a file is not found at that path, the built-in -version will be used instead. Whiteouts are not currently supported. - -Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after -the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the -location of a single resource with an individual file. +In the example above, if an application tried to load a resource with the +resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check +the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was +found there, it would be used instead. This is an overlay, not an outright +replacement, which means that if a file is not found at that path, the +built-in version will be used instead. Whiteouts are not currently +supported. + +Substitutions must start with a slash, and must not contain a trailing slash +before the `=`. The path after the slash should ideally be absolute, but +this is not strictly required. It is possible to overlay the location of a +single resource with an individual file. Creates a GResource from a reference to the binary resource bundle. This will keep a reference to @data while the resource lives, so @@ -61935,20 +63029,20 @@ bundle. - #GSeekable is implemented by streams (implementations of -#GInputStream or #GOutputStream) that support seeking. + `GSeekable` is implemented by streams (implementations of +[class@Gio.InputStream] or [class@Gio.OutputStream]) that support seeking. Seekable streams largely fall into two categories: resizable and fixed-size. -#GSeekable on fixed-sized streams is approximately the same as POSIX -lseek() on a block device (for example: attempting to seek past the -end of the device is an error). Fixed streams typically cannot be +`GSeekable` on fixed-sized streams is approximately the same as POSIX +[`lseek()`](man:lseek(2)) on a block device (for example: attempting to seek +past the end of the device is an error). Fixed streams typically cannot be truncated. -#GSeekable on resizable streams is approximately the same as POSIX -lseek() on a normal file. Seeking past the end and writing data will -usually cause the stream to resize by introducing zero bytes. +`GSeekable` on resizable streams is approximately the same as POSIX +[`lseek()`](man:lseek(2)) on a normal file. Seeking past the end and writing +data will usually cause the stream to resize by introducing zero bytes. Tests if the stream supports the #GSeekableIface. @@ -62277,112 +63371,113 @@ buffer, zero if the target is not seekable. - The #GSettings class provides a convenient API for storing and retrieving + The `GSettings` class provides a convenient API for storing and retrieving application settings. Reads and writes can be considered to be non-blocking. Reading -settings with #GSettings is typically extremely fast: on +settings with `GSettings` is typically extremely fast: on approximately the same order of magnitude (but slower than) a -#GHashTable lookup. Writing settings is also extremely fast in terms -of time to return to your application, but can be extremely expensive +[struct@GLib.HashTable] lookup. Writing settings is also extremely fast in +terms of time to return to your application, but can be extremely expensive for other threads and other processes. Many settings backends (including dconf) have lazy initialisation which means in the common case of the user using their computer without modifying any settings -a lot of work can be avoided. For dconf, the D-Bus service doesn't +a lot of work can be avoided. For dconf, the D-Bus service doesn’t even need to be started in this case. For this reason, you should -only ever modify #GSettings keys in response to explicit user action. +only ever modify `GSettings` keys in response to explicit user action. Particular care should be paid to ensure that modifications are not -made during startup -- for example, when setting the initial value -of preferences widgets. The built-in g_settings_bind() functionality -is careful not to write settings in response to notify signals as a -result of modifications that it makes to widgets. +made during startup — for example, when setting the initial value +of preferences widgets. The built-in [method@Gio.Settings.bind] +functionality is careful not to write settings in response to notify signals +as a result of modifications that it makes to widgets. -When creating a GSettings instance, you have to specify a schema +When creating a `GSettings` instance, you have to specify a schema that describes the keys in your settings and their types and default values, as well as some other information. Normally, a schema has a fixed path that determines where the settings are stored in the conceptual global tree of settings. However, schemas -can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with +can also be ‘[relocatable](#relocatable-schemas)’, i.e. not equipped with a fixed path. This is -useful e.g. when the schema describes an 'account', and you want to be +useful e.g. when the schema describes an ‘account’, and you want to be able to store a arbitrary number of accounts. -Paths must start with and end with a forward slash character ('/') +Paths must start with and end with a forward slash character (`/`) and must not contain two sequential slash characters. Paths should be chosen based on a domain name associated with the program or library to which the settings belong. Examples of paths are -"/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". -Paths should not start with "/apps/", "/desktop/" or "/system/" as +`/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`. +Paths should not start with `/apps/`, `/desktop/` or `/system/` as they often did in GConf. Unlike other configuration systems (like GConf), GSettings does not restrict keys to basic types like strings and numbers. GSettings stores -values as #GVariant, and allows any #GVariantType for keys. Key names -are restricted to lowercase characters, numbers and '-'. Furthermore, -the names must begin with a lowercase character, must not end -with a '-', and must not contain consecutive dashes. +values as [struct@GLib.Variant], and allows any [type@GLib.VariantType] for +keys. Key names are restricted to lowercase characters, numbers and `-`. +Furthermore, the names must begin with a lowercase character, must not end +with a `-`, and must not contain consecutive dashes. Similar to GConf, the default values in GSettings schemas can be localized, but the localized values are stored in gettext catalogs and looked up with the domain that is specified in the -`gettext-domain` attribute of the <schemalist> or <schema> +`gettext-domain` attribute of the `<schemalist>` or `<schema>` elements and the category that is specified in the `l10n` attribute of -the <default> element. The string which is translated includes all text in -the <default> element, including any surrounding quotation marks. +the `<default>` element. The string which is translated includes all text in +the `<default>` element, including any surrounding quotation marks. The `l10n` attribute must be set to `messages` or `time`, and sets the [locale category for translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). The `messages` category should be used by default; use `time` for translatable date or time formats. A translation comment can be added as an -XML comment immediately above the <default> element — it is recommended to +XML comment immediately above the `<default>` element — it is recommended to add these comments to aid translators understand the meaning and implications of the default value. An optional translation `context` -attribute can be set on the <default> element to disambiguate multiple +attribute can be set on the `<default>` element to disambiguate multiple defaults which use the same string. For example: -|[ +```xml <!-- Translators: A list of words which are not allowed to be typed, in GVariant serialization syntax. See: https://developer.gnome.org/glib/stable/gvariant-text.html --> <default l10n='messages' context='Banned words'>['bad', 'words']</default> -]| +``` Translations of default values must remain syntactically valid serialized -#GVariants (e.g. retaining any surrounding quotation marks) or runtime -errors will occur. +[struct@GLib.Variant]s (e.g. retaining any surrounding quotation marks) or +runtime errors will occur. GSettings uses schemas in a compact binary form that is created -by the [glib-compile-schemas][glib-compile-schemas] +by the [`glib-compile-schemas`](glib-compile-schemas.html) utility. The input is a schema description in an XML format. A DTD for the gschema XML format can be found here: [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) -The [glib-compile-schemas][glib-compile-schemas] tool expects schema +The [`glib-compile-schemas`](glib-compile-schemas.html) tool expects schema files to have the extension `.gschema.xml`. -At runtime, schemas are identified by their id (as specified in the -id attribute of the <schema> element). The convention for schema -ids is to use a dotted name, similar in style to a D-Bus bus name, -e.g. "org.gnome.SessionManager". In particular, if the settings are +At runtime, schemas are identified by their ID (as specified in the +`id` attribute of the `<schema>` element). The convention for schema +IDs is to use a dotted name, similar in style to a D-Bus bus name, +e.g. `org.gnome.SessionManager`. In particular, if the settings are for a specific service that owns a D-Bus bus name, the D-Bus bus name -and schema id should match. For schemas which deal with settings not -associated with one named application, the id should not use -StudlyCaps, e.g. "org.gnome.font-rendering". - -In addition to #GVariant types, keys can have types that have -enumerated types. These can be described by a <choice>, -<enum> or <flags> element, as seen in the -[example][schema-enumerated]. The underlying type of such a key -is string, but you can use g_settings_get_enum(), g_settings_set_enum(), -g_settings_get_flags(), g_settings_set_flags() access the numeric values -corresponding to the string value of enum and flags keys. +and schema ID should match. For schemas which deal with settings not +associated with one named application, the ID should not use +StudlyCaps, e.g. `org.gnome.font-rendering`. + +In addition to [struct@GLib.Variant] types, keys can have types that have +enumerated types. These can be described by a `<choice>`, +`<enum>` or `<flags>` element, as seen in the +second example below. The underlying type of such a key +is string, but you can use [method@Gio.Settings.get_enum], +[method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags], +[method@Gio.Settings.set_flags] access the numeric values corresponding to +the string value of enum and flags keys. An example for default value: -|[ +```xml <schemalist> <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test"> @@ -62405,10 +63500,10 @@ An example for default value: </schema> </schemalist> -]| +``` An example for ranges, choices and enumerated types: -|[ +```xml <schemalist> <enum id="org.gtk.Test.myenum"> @@ -62451,7 +63546,7 @@ An example for ranges, choices and enumerated types: </key> </schema> </schemalist> -]| +``` ## Vendor overrides @@ -62459,41 +63554,42 @@ Default values are defined in the schemas that get installed by an application. Sometimes, it is necessary for a vendor or distributor to adjust these defaults. Since patching the XML source for the schema is inconvenient and error-prone, -[glib-compile-schemas][glib-compile-schemas] reads so-called vendor -override' files. These are keyfiles in the same directory as the XML -schema sources which can override default values. The schema id serves +[`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor +override’ files. These are keyfiles in the same directory as the XML +schema sources which can override default values. The schema ID serves as the group name in the key file, and the values are expected in -serialized GVariant form, as in the following example: -|[ - [org.gtk.Example] - key1='string' - key2=1.5 -]| - -glib-compile-schemas expects schema files to have the extension +serialized [struct@GLib.Variant] form, as in the following example: +``` +[org.gtk.Example] +key1='string' +key2=1.5 +``` + +`glib-compile-schemas` expects schema files to have the extension `.gschema.override`. ## Binding -A very convenient feature of GSettings lets you bind #GObject properties -directly to settings, using g_settings_bind(). Once a GObject property -has been bound to a setting, changes on either side are automatically -propagated to the other side. GSettings handles details like mapping -between GObject and GVariant types, and preventing infinite cycles. +A very convenient feature of GSettings lets you bind [class@GObject.Object] +properties directly to settings, using [method@Gio.Settings.bind]. Once a +[class@GObject.Object] property has been bound to a setting, changes on +either side are automatically propagated to the other side. GSettings handles +details like mapping between [class@GObject.Object] and [struct@GLib.Variant] +types, and preventing infinite cycles. This makes it very easy to hook up a preferences dialog to the underlying settings. To make this even more convenient, GSettings -looks for a boolean property with the name "sensitivity" and +looks for a boolean property with the name `sensitivity` and automatically binds it to the writability of the bound setting. -If this 'magic' gets in the way, it can be suppressed with the -%G_SETTINGS_BIND_NO_SENSITIVITY flag. +If this ‘magic’ gets in the way, it can be suppressed with the +`G_SETTINGS_BIND_NO_SENSITIVITY` flag. -## Relocatable schemas # {#gsettings-relocatable} +## Relocatable schemas A relocatable schema is one with no `path` attribute specified on its -<schema> element. By using g_settings_new_with_path(), a #GSettings object -can be instantiated for a relocatable schema, assigning a path to the -instance. Paths passed to g_settings_new_with_path() will typically be +`<schema>` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings` +object can be instantiated for a relocatable schema, assigning a path to the +instance. Paths passed to [ctor@Gio.Settings.new_with_path] will typically be constructed dynamically from a constant prefix plus some form of instance identifier; but they must still be valid GSettings paths. Paths could also be constant and used with a globally installed schema originating from a @@ -62504,59 +63600,59 @@ for different windows in an application. If the schema ID was `org.foo.MyApp.Window`, it could be instantiated for paths `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known -they can be specified as <child> elements in the parent schema, e.g.: -|[ +they can be specified as `<child>` elements in the parent schema, e.g.: +```xml <schema id="org.foo.MyApp" path="/org/foo/MyApp/"> <child name="main" schema="org.foo.MyApp.Window"/> </schema> -]| +``` -## Build system integration # {#gsettings-build-system} +## Build system integration GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your `configure.ac`: -|[ +``` GLIB_GSETTINGS -]| +``` In the appropriate `Makefile.am`, use the following snippet to compile and install the named schema: -|[ +``` gsettings_SCHEMAS = org.foo.MyApp.gschema.xml EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@ -]| +``` No changes are needed to the build system to mark a schema XML file for translation. Assuming it sets the `gettext-domain` attribute, a schema may be marked for translation by adding it to `POTFILES.in`, assuming gettext 0.19 is in use (the preferred method for translation): -|[ +``` data/org.foo.MyApp.gschema.xml -]| +``` Alternatively, if intltool 0.50.1 is in use: -|[ +``` [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml -]| +``` -GSettings will use gettext to look up translations for the <summary> and -<description> elements, and also any <default> elements which have a `l10n` -attribute set. Translations must not be included in the `.gschema.xml` file -by the build system, for example by using intltool XML rules with a +GSettings will use gettext to look up translations for the `<summary>` and +`<description>` elements, and also any `<default>` elements which have a +`l10n` attribute set. Translations must not be included in the `.gschema.xml` +file by the build system, for example by using intltool XML rules with a `.gschema.xml.in` template. If an enumerated type defined in a C header file is to be used in a GSettings -schema, it can either be defined manually using an <enum> element in the +schema, it can either be defined manually using an `<enum>` element in the schema XML, or it can be extracted automatically from the C header. This approach is preferred, as it ensures the two representations are always synchronised. To do so, add the following to the relevant `Makefile.am`: -|[ +``` gsettings_ENUM_NAMESPACE = org.foo.MyApp gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h -]| +``` `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, which are specified in `gsettings_ENUM_FILES`. This will generate a @@ -64128,11 +65224,11 @@ callbacks when the writability of "x" changes. - The #GSettingsBackend interface defines a generic interface for + The `GSettingsBackend` interface defines a generic interface for non-strictly-typed data that is stored in a hierarchy. To implement -an alternative storage backend for #GSettings, you need to implement -the #GSettingsBackend interface and then make it implement the -extension point %G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. +an alternative storage backend for [class@Gio.Settings], you need to +implement the `GSettingsBackend` interface and then make it implement the +extension point `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. The interface defines methods for reading and writing values, a method for determining if writing of certain values will fail @@ -64142,15 +65238,14 @@ The semantics of the interface are very precisely defined and implementations must carefully adhere to the expectations of callers that are documented on each of the interface methods. -Some of the #GSettingsBackend functions accept or return a #GTree. -These trees always have strings as keys and #GVariant as values. -g_settings_backend_create_tree() is a convenience function to create -suitable trees. +Some of the `GSettingsBackend` functions accept or return a +[struct@GLib.Tree]. These trees always have strings as keys and +[struct@GLib.Variant] as values. -The #GSettingsBackend API is exported to allow third-party +The `GSettingsBackend` API is exported to allow third-party implementations, but does not carry the same stability guarantees as the public GIO API. For this reason, you have to define the -C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including +C preprocessor symbol `G_SETTINGS_ENABLE_BACKEND` before including `gio/gsettingsbackend.h`. Calculate the longest common prefix of all keys in a tree and write @@ -64904,7 +65999,7 @@ g_settings_get_mapped() - The #GSettingsSchemaSource and #GSettingsSchema APIs provide a + The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a mechanism for advanced control over the loading of schemas and a mechanism for introspecting their content. @@ -64914,20 +66009,20 @@ settings visible to GSettings. Typically, a plugin will want to ship the schema along with itself and it won't be installed into the standard system directories for schemas. -#GSettingsSchemaSource provides a mechanism for dealing with this by -allowing the creation of a new 'schema source' from which schemas can +[struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this +by allowing the creation of a new ‘schema source’ from which schemas can be acquired. This schema source can then become part of the metadata associated with the plugin and queried whenever the plugin requires access to some settings. Consider the following example: -|[<!-- language="C" --> +```c typedef struct { - ... + … GSettingsSchemaSource *schema_source; - ... + … } Plugin; Plugin * @@ -64935,18 +66030,18 @@ initialise_plugin (const gchar *dir) { Plugin *plugin; - ... + … plugin->schema_source = g_settings_schema_source_new_from_directory (dir, g_settings_schema_source_get_default (), FALSE, NULL); - ... + … return plugin; } -... +… GSettings * plugin_get_settings (Plugin *plugin, @@ -64962,12 +66057,12 @@ plugin_get_settings (Plugin *plugin, if (schema == NULL) { - ... disable the plugin or abort, etc ... + … disable the plugin or abort, etc … } return g_settings_new_full (schema, NULL, NULL); } -]| +``` The code above shows how hooks should be added to the code that initialises (or enables) the plugin to create the schema source and @@ -64979,19 +66074,19 @@ From the standpoint of the plugin, it would need to ensure that it ships a gschemas.compiled file as part of itself, and then simply do the following: -|[<!-- language="C" --> +```c { GSettings *settings; gint some_value; settings = plugin_get_settings (self, NULL); some_value = g_settings_get_int (settings, "some-value"); - ... + … } -]| +``` It's also possible that the plugin system expects the schema source -files (ie: .gschema.xml files) instead of a gschemas.compiled file. +files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file. In that case, the plugin loading system must compile the schemas for itself before attempting to create the settings source. @@ -65490,11 +66585,11 @@ recursively. - A #GSimpleAction is the obvious simple implementation of the #GAction -interface. This is the easiest way to create an action for purposes of -adding it to a #GSimpleActionGroup. + A `GSimpleAction` is the obvious simple implementation of the +[iface@Gio.Action] interface. This is the easiest way to create an action for +purposes of adding it to a [class@Gio.SimpleActionGroup]. -See also #GtkAction. +See also [class@Gtk.Action]. Creates a new action. @@ -65707,8 +66802,9 @@ It could set it to any value at all, or take some other action. - #GSimpleActionGroup is a hash table filled with #GAction objects, -implementing the #GActionGroup and #GActionMap interfaces. + `GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects, +implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] +interfaces. @@ -65827,78 +66923,79 @@ If no action of this name is in the group then nothing happens. - As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of -#GTask, which provides a simpler API. + As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of +[class@Gio.Task], which provides a simpler API. -#GSimpleAsyncResult implements #GAsyncResult. +`GSimpleAsyncResult` implements [iface@Gio.AsyncResult]. -GSimpleAsyncResult handles #GAsyncReadyCallbacks, error +`GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error reporting, operation cancellation and the final state of an operation, completely transparent to the application. Results can be returned as a pointer e.g. for functions that return data that is collected asynchronously, a boolean value for checking the success or failure -of an operation, or a #gssize for operations which return the number +of an operation, or a `gssize` for operations which return the number of bytes modified by the operation; all of the simple return cases are covered. Most of the time, an application will not need to know of the details of this API; it is handled transparently, and any necessary operations -are handled by #GAsyncResult's interface. However, if implementing a -new GIO module, for writing language bindings, or for complex +are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing +a new GIO module, for writing language bindings, or for complex applications that need better control of how asynchronous operations are completed, it is important to understand this functionality. -GSimpleAsyncResults are tagged with the calling function to ensure +`GSimpleAsyncResult`s are tagged with the calling function to ensure that asynchronous functions and their finishing functions are used together correctly. -To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). -If the result needs to be created for a #GError, use -g_simple_async_result_new_from_error() or -g_simple_async_result_new_take_error(). If a #GError is not available -(e.g. the asynchronous operation's doesn't take a #GError argument), +To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new]. +If the result needs to be created for a `GError`, use +[ctor@Gio.SimpleAsyncResult.new_from_error] or +[ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available +(e.g. the asynchronous operation doesn’t take a `GError` argument), but the result still needs to be created for an error condition, use -g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() -if your application or binding requires passing a variable argument list -directly), and the error can then be propagated through the use of -g_simple_async_result_propagate_error(). +[ctor@Gio.SimpleAsyncResult.new_error] (or +[method@Gio.SimpleAsyncResult.set_error_va] if your application or binding +requires passing a variable argument list directly), and the error can then +be propagated through the use of +[method@Gio.SimpleAsyncResult.propagate_error]. An asynchronous operation can be made to ignore a cancellation event by -calling g_simple_async_result_set_handle_cancellation() with a -#GSimpleAsyncResult for the operation and %FALSE. This is useful for +calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a +`GSimpleAsyncResult` for the operation and `FALSE`. This is useful for operations that are dangerous to cancel, such as close (which would cause a leak if cancelled before being run). -GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, -or it can use #GThreads. -g_simple_async_result_complete() will finish an I/O task directly -from the point where it is called. g_simple_async_result_complete_in_idle() -will finish it from an idle handler in the -[thread-default main context][g-main-context-push-thread-default] -where the #GSimpleAsyncResult was created. -g_simple_async_result_run_in_thread() will run the job in a -separate thread and then use -g_simple_async_result_complete_in_idle() to deliver the result. +`GSimpleAsyncResult` can integrate into GLib’s event loop, +[type@GLib.MainLoop], or it can use [type@GLib.Thread]s. +[method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly +from the point where it is called. +[method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle +handler in the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult` +was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in +a separate thread and then use +[method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result. To set the results of an asynchronous function, -g_simple_async_result_set_op_res_gpointer(), -g_simple_async_result_set_op_res_gboolean(), and -g_simple_async_result_set_op_res_gssize() -are provided, setting the operation's result to a gpointer, gboolean, or -gssize, respectively. +[method@Gio.SimpleAsyncResult.set_op_res_gpointer], +[method@Gio.SimpleAsyncResult.set_op_res_gboolean], and +[method@Gio.SimpleAsyncResult.set_op_res_gssize] +are provided, setting the operation's result to a `gpointer`, `gboolean`, or +`gssize`, respectively. Likewise, to get the result of an asynchronous function, -g_simple_async_result_get_op_res_gpointer(), -g_simple_async_result_get_op_res_gboolean(), and -g_simple_async_result_get_op_res_gssize() are -provided, getting the operation's result as a gpointer, gboolean, and -gssize, respectively. +[method@Gio.SimpleAsyncResult.get_op_res_gpointer], +[method@Gio.SimpleAsyncResult.get_op_res_gboolean], and +[method@Gio.SimpleAsyncResult.get_op_res_gssize] are +provided, getting the operation’s result as a `gpointer`, `gboolean`, and +`gssize`, respectively. For the details of the requirements implementations must respect, see -#GAsyncResult. A typical implementation of an asynchronous operation -using GSimpleAsyncResult looks something like this: +[iface@Gio.AsyncResult]. A typical implementation of an asynchronous +operation using `GSimpleAsyncResult` looks something like this: -|[<!-- language="C" --> +```c static void baked_cb (Cake *cake, gpointer user_data) @@ -65991,7 +67088,7 @@ baker_bake_cake_finish (Baker *self, cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); return g_object_ref (cake); } -]| +``` Creates a #GSimpleAsyncResult. @@ -66521,14 +67618,14 @@ checks for cancellation. - GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and -#GOutputStream. This allows any pair of input and output streams to be used -with #GIOStream methods. - -This is useful when you obtained a #GInputStream and a #GOutputStream -by other means, for instance creating them with platform specific methods as -g_unix_input_stream_new() or g_win32_input_stream_new(), and you want -to take advantage of the methods provided by #GIOStream. + `GSimpleIOStream` creates a [class@Gio.IOStream] from an arbitrary +[class@Gio.InputStream] and [class@Gio.OutputStream]. This allows any pair of +input and output streams to be used with [class@Gio.IOStream] methods. + +This is useful when you obtained a [class@Gio.InputStream] and a +[class@Gio.OutputStream] by other means, for instance creating them with +platform specific methods as [ctor@Gio.UnixInputStream.new], and you want to +take advantage of the methods provided by [class@Gio.IOStream]. Creates a new #GSimpleIOStream wrapping @input_stream and @output_stream. See also #GIOStream. @@ -66548,18 +67645,21 @@ See also #GIOStream. + The [class@Gio.InputStream] to read from. + The [class@Gio.OutputStream] to write to. - #GSimplePermission is a trivial implementation of #GPermission that -represents a permission that is either always or never allowed. The -value is given at construction and doesn't change. + `GSimplePermission` is a trivial implementation of [class@Gio.Permission] +that represents a permission that is either always or never allowed. The +value is given at construction and doesn’t change. -Calling request or release will result in errors. +Calling [method@Gio.Permission.acquire] or [method@Gio.Permission.release] +on a `GSimplePermission` will result in errors. Creates a new #GPermission instance that represents an action that is either always or never allowed. @@ -66576,14 +67676,14 @@ either always or never allowed. - #GSimpleProxyResolver is a simple #GProxyResolver implementation + `GSimpleProxyResolver` is a simple [iface@Gio.ProxyResolver] implementation that handles a single default proxy, multiple URI-scheme-specific proxies, and a list of hosts that proxies should not be used for. -#GSimpleProxyResolver is never the default proxy resolver, but it +`GSimpleProxyResolver` is never the default proxy resolver, but it can be used as the base class for another proxy resolver implementation, or it can be created and used manually, such as -with g_socket_client_set_proxy_resolver(). +with [method@Gio.SocketClient.set_proxy_resolver]. Creates a new #GSimpleProxyResolver. See @@ -66778,41 +67878,42 @@ commonly used by other applications. - A #GSocket is a low-level networking primitive. It is a more or less + A `GSocket` is a low-level networking primitive. It is a more or less direct mapping of the BSD socket API in a portable GObject based API. It supports both the UNIX socket implementations and winsock2 on Windows. -#GSocket is the platform independent base upon which the higher level +`GSocket` is the platform independent base upon which the higher level network primitives are based. Applications are not typically meant to -use it directly, but rather through classes like #GSocketClient, -#GSocketService and #GSocketConnection. However there may be cases where -direct use of #GSocket is useful. - -#GSocket implements the #GInitable interface, so if it is manually constructed -by e.g. g_object_new() you must call g_initable_init() and check the -results before using the object. This is done automatically in -g_socket_new() and g_socket_new_from_fd(), so these functions can return -%NULL. +use it directly, but rather through classes like [class@Gio.SocketClient], +[class@Gio.SocketService] and [class@Gio.SocketConnection]. However there may +be cases where direct use of `GSocket` is useful. + +`GSocket` implements the [iface@Gio.Initable] interface, so if it is manually +constructed by e.g. [ctor@GObject.Object.new] you must call +[method@Gio.Initable.init] and check the results before using the object. +This is done automatically in [ctor@Gio.Socket.new] and +[ctor@Gio.Socket.new_from_fd], so these functions can return `NULL`. Sockets operate in two general modes, blocking or non-blocking. When in blocking mode all operations (which don’t take an explicit blocking parameter) block until the requested operation is finished or there is an error. In non-blocking mode all calls that -would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. -To know when a call would successfully run you can call g_socket_condition_check(), -or g_socket_condition_wait(). You can also use g_socket_create_source() and -attach it to a #GMainContext to get callbacks when I/O is possible. +would block return immediately with a `G_IO_ERROR_WOULD_BLOCK` error. +To know when a call would successfully run you can call +[method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait]. +You can also use [method@Gio.Socket.create_source] and attach it to a +[type@GLib.MainContext] to get callbacks when I/O is possible. Note that all sockets are always set to non blocking mode in the system, and -blocking mode is emulated in GSocket. +blocking mode is emulated in `GSocket`. When working in non-blocking mode applications should always be able to -handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other +handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function said that I/O was possible. This can easily happen in case of a race condition in the application, but it can also happen for other reasons. For instance, on Windows a socket is always seen as writable -until a write returns %G_IO_ERROR_WOULD_BLOCK. +until a write returns `G_IO_ERROR_WOULD_BLOCK`. -#GSockets can be either connection oriented or datagram based. +`GSocket`s can be either connection oriented or datagram based. For connection oriented types you must first establish a connection by either connecting to an address or accepting a connection from another address. For connectionless socket types the target/source address is @@ -66820,15 +67921,33 @@ specified or received in each I/O operation. All socket file descriptors are set to be close-on-exec. -Note that creating a #GSocket causes the signal %SIGPIPE to be +Note that creating a `GSocket` causes the signal `SIGPIPE` to be ignored for the remainder of the program. If you are writing a -command-line utility that uses #GSocket, you may need to take into +command-line utility that uses `GSocket`, you may need to take into account the fact that your program will not automatically be killed -if it tries to write to %stdout after it has been closed. +if it tries to write to `stdout` after it has been closed. -Like most other APIs in GLib, #GSocket is not inherently thread safe. To use -a #GSocket concurrently from multiple threads, you must implement your own -locking. +Like most other APIs in GLib, `GSocket` is not inherently thread safe. To use +a `GSocket` concurrently from multiple threads, you must implement your own +locking. + +## Nagle’s algorithm + +Since GLib 2.80, `GSocket` will automatically set the `TCP_NODELAY` option on +all `G_SOCKET_TYPE_STREAM` sockets. This disables +[Nagle’s algorithm](https://en.wikipedia.org/wiki/Nagle%27s_algorithm) as it +typically does more harm than good on modern networks. + +If your application needs Nagle’s algorithm enabled, call +[method@Gio.Socket.set_option] after constructing a `GSocket` to enable it: +```c +socket = g_socket_new (…, G_SOCKET_TYPE_STREAM, …); +if (socket != NULL) + { + g_socket_set_option (socket, IPPROTO_TCP, TCP_NODELAY, FALSE, &local_error); + // handle error if needed + } +``` @@ -67754,6 +68873,85 @@ the peer, or -1 on error + + Receives data (up to @size bytes) from a socket. + +This function is a variant of [method@Gio.Socket.receive] which returns a +[struct@GLib.Bytes] rather than a plain buffer. + +Pass `-1` to @timeout_us to block indefinitely until data is received (or +the connection is closed, or there is an error). Pass `0` to use the default +timeout from [property@Gio.Socket:timeout], or pass a positive number to wait +for that many microseconds for data before returning `G_IO_ERROR_TIMED_OUT`. + + a bytes buffer containing the + received bytes, or `NULL` on error + + + + + a #GSocket + + + + the number of bytes you want to read from the socket + + + + the timeout to wait for, in microseconds, or `-1` to block + indefinitely + + + + a %GCancellable, or `NULL` + + + + + + Receive data (up to @size bytes) from a socket. + +This function is a variant of [method@Gio.Socket.receive_from] which returns +a [struct@GLib.Bytes] rather than a plain buffer. + +If @address is non-%NULL then @address will be set equal to the +source address of the received packet. + +The @address is owned by the caller. + +Pass `-1` to @timeout_us to block indefinitely until data is received (or +the connection is closed, or there is an error). Pass `0` to use the default +timeout from [property@Gio.Socket:timeout], or pass a positive number to wait +for that many microseconds for data before returning `G_IO_ERROR_TIMED_OUT`. + + a bytes buffer containing the + received bytes, or `NULL` on error + + + + + a #GSocket + + + + return location for a #GSocketAddress + + + + the number of bytes you want to read from the socket + + + + the timeout to wait for, in microseconds, or `-1` to block + indefinitely + + + + a #GCancellable, or `NULL` + + + + Receive data (up to @size bytes) from a socket. @@ -68629,26 +69827,32 @@ of speaking IPv4. - + + Whether I/O on this socket is blocking. Whether the socket should allow sending to broadcast addresses. - + + The socket’s address family. - + + The socket’s file descriptor. - + + Whether to keep the connection alive by sending periodic pings. - + + The number of outstanding connections in the listen queue. - + + The local address the socket is bound to. @@ -68659,10 +69863,12 @@ of speaking IPv4. Time-to-live out outgoing multicast packets - + + The ID of the protocol to use, or `-1` for unknown. - + + The remote address the socket is connected to. @@ -68673,7 +69879,8 @@ of speaking IPv4. Time-to-live for outgoing unicast packets - + + The socket’s type. @@ -68684,9 +69891,10 @@ of speaking IPv4. - #GSocketAddress is the equivalent of struct sockaddr in the BSD -sockets API. This is an abstract class; use #GInetSocketAddress -for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. + `GSocketAddress` is the equivalent of +[`struct sockaddr`](man:sockaddr(3type)) and its subtypes in the BSD sockets +API. This is an abstract class; use [class@Gio.InetSocketAddress] for +internet sockets, or [class@Gio.UnixSocketAddress] for UNIX domain sockets. Creates a #GSocketAddress subclass corresponding to the native @@ -68821,7 +70029,8 @@ struct sockaddr - + + The family of the socket address. @@ -68887,19 +70096,20 @@ struct sockaddr - #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 each #GSocketAddress which could be used to connect to that -#GSocketConnectable. + `GSocketAddressEnumerator` is an enumerator type for +[class@Gio.SocketAddress] instances. It is returned by enumeration functions +such as [method@Gio.SocketConnectable.enumerate], which returns a +`GSocketAddressEnumerator` to list each [class@Gio.SocketAddress] which could +be used to connect to that [iface@Gio.SocketConnectable]. Enumeration is typically a blocking operation, so the asynchronous methods -g_socket_address_enumerator_next_async() and -g_socket_address_enumerator_next_finish() should be used where possible. +[method@Gio.SocketAddressEnumerator.next_async] and +[method@Gio.SocketAddressEnumerator.next_finish] should be used where +possible. -Each #GSocketAddressEnumerator can only be enumerated once. Once -g_socket_address_enumerator_next() has returned %NULL, further -enumeration with that #GSocketAddressEnumerator is not possible, and it can +Each `GSocketAddressEnumerator` can only be enumerated once. Once +[method@Gio.SocketAddressEnumerator.next] has returned `NULL`, further +enumeration with that `GSocketAddressEnumerator` is not possible, and it can be unreffed. Retrieves the next #GSocketAddress from @enumerator. Note that this @@ -69217,18 +70427,18 @@ error handling. - #GSocketClient is a lightweight high-level utility class for connecting to + `GSocketClient` is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type. -You create a #GSocketClient object, set any options you want, and then -call a sync or async connect operation, which returns a #GSocketConnection -subclass on success. +You create a `GSocketClient` object, set any options you want, and then +call a sync or async connect operation, which returns a +[class@Gio.SocketConnection] subclass on success. -The type of the #GSocketConnection object returned depends on the type of -the underlying socket that is in use. For instance, for a TCP/IP connection -it will be a #GTcpConnection. +The type of the [class@Gio.SocketConnection] object returned depends on the +type of the underlying socket that is in use. For instance, for a TCP/IP +connection it will be a [class@Gio.TcpConnection]. -As #GSocketClient is a lightweight object, you don't need to cache it. You +As `GSocketClient` is a lightweight object, you don't need to cache it. You can just create a new one any time you need one. Creates a new #GSocketClient with the default options. @@ -70024,26 +71234,32 @@ information. - + + Enable proxy support. - + + The address family to use for socket construction. - + + The local address constructed sockets will be bound to. - + + The protocol to use for socket construction, or `0` for default. The proxy resolver to use - + + The I/O timeout for sockets, in seconds, or `0` for none. - + + Whether to create TLS connections. @@ -70066,7 +71282,8 @@ connect to #GTlsConnection::accept-certificate. Do not attempt to ignore validation errors. - + + The type to use for socket construction. @@ -70241,12 +71458,12 @@ Additional values may be added to this type in the future. Objects that describe one or more potential socket endpoints -implement #GSocketConnectable. Callers can then use -g_socket_connectable_enumerate() to get a #GSocketAddressEnumerator -to try out each socket address in turn until one succeeds, as shown -in the sample code below. +implement `GSocketConnectable`. Callers can then use +[method@Gio.SocketConnectable.enumerate] to get a +[class@Gio.SocketAddressEnumerator] to try out each socket address in turn +until one succeeds, as shown in the sample code below. -|[<!-- language="C" --> +```c MyConnectionType * connect_to_host (const char *hostname, guint16 port, @@ -70296,7 +71513,7 @@ connect_to_host (const char *hostname, return NULL; } } -]| +``` Creates a #GSocketAddressEnumerator for @connectable. @@ -70451,22 +71668,22 @@ and #GProxyAddressEnumerator - #GSocketConnection is a #GIOStream for a connected socket. They -can be created either by #GSocketClient when connecting to a host, -or by #GSocketListener when accepting a new client. + `GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They +can be created either by [class@Gio.SocketClient] when connecting to a host, +or by [class@Gio.SocketListener] when accepting a new client. -The type of the #GSocketConnection object returned from these calls +The type of the `GSocketConnection` object returned from these calls depends on the type of the underlying socket that is in use. For -instance, for a TCP/IP connection it will be a #GTcpConnection. +instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection]. Choosing what type of object to construct is done with the socket -connection factory, and it is possible for 3rd parties to register +connection factory, and it is possible for third parties to register custom socket connection types for specific combination of socket -family/type/protocol using g_socket_connection_factory_register_type(). +family/type/protocol using [func@Gio.SocketConnection.factory_register_type]. -To close a #GSocketConnection, use g_io_stream_close(). Closing both -substreams of the #GIOStream separately will not close the underlying -#GSocket. +To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both +substreams of the [class@Gio.IOStream] separately will not close the +underlying [class@Gio.Socket]. Looks up the #GType to be used when creating socket connections on sockets with the specified @family, @type and @protocol_id. @@ -70545,6 +71762,10 @@ If no type is registered, the #GSocketConnection base type is returned. This clears the #GSocket:blocking flag on @connection's underlying socket if it is currently set. +If #GSocket:timeout is set, the operation will time out and return +%G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue +indefinitely until operating system timeouts (if any) are hit. + Use g_socket_connection_connect_finish() to retrieve the result. @@ -70653,7 +71874,8 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + + The underlying [class@Gio.Socket]. @@ -70712,26 +71934,26 @@ g_socket_is_connected() on @connection's underlying #GSocket. - A #GSocketControlMessage is a special-purpose utility message that -can be sent to or received from a #GSocket. These types of -messages are often called "ancillary data". + A `GSocketControlMessage` is a special-purpose utility message that +can be sent to or received from a [class@Gio.Socket]. These types of +messages are often called ‘ancillary data’. The message can represent some sort of special instruction to or information from the socket or can represent a special kind of transfer to the peer (for example, sending a file descriptor over a UNIX socket). -These messages are sent with g_socket_send_message() and received -with g_socket_receive_message(). +These messages are sent with [method@Gio.Socket.send_message] and received +with [method@Gio.Socket.receive_message]. To extend the set of control message that can be sent, subclass this -class and override the get_size, get_level, get_type and serialize +class and override the `get_size`, `get_level`, `get_type` and `serialize` methods. To extend the set of control messages that can be received, subclass -this class and implement the deserialize method. Also, make sure your -class is registered with the GType typesystem before calling -g_socket_receive_message() to read such a message. +this class and implement the `deserialize` method. Also, make sure your +class is registered with the [type@GObject.Type] type system before calling +[method@Gio.Socket.receive_message] to read such a message. Tries to deserialize a socket control message of a given @level and @type. This will ask all known (to GType) subclasses @@ -71032,20 +72254,21 @@ if available.) - A #GSocketListener is an object that keeps track of a set + A `GSocketListener` is an object that keeps track of a set of server sockets and helps you accept sockets from any of the socket, either sync or async. -Add addresses and ports to listen on using g_socket_listener_add_address() -and g_socket_listener_add_inet_port(). These will be listened on until -g_socket_listener_close() is called. Dropping your final reference to the -#GSocketListener will not cause g_socket_listener_close() to be called -implicitly, as some references to the #GSocketListener may be held +Add addresses and ports to listen on using +[method@Gio.SocketListener.add_address] and +[method@Gio.SocketListener.add_inet_port]. These will be listened on until +[method@Gio.SocketListener.close] is called. Dropping your final reference to +the `GSocketListener` will not cause [method@Gio.SocketListener.close] to be +called implicitly, as some references to the `GSocketListener` may be held internally. -If you want to implement a network server, also look at #GSocketService -and #GThreadedSocketService which are subclasses of #GSocketListener -that make this even easier. +If you want to implement a network server, also look at +[class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are +subclasses of `GSocketListener` that make this even easier. Creates a new #GSocketListener with no sockets to listen for. New listeners can be added with e.g. g_socket_listener_add_address() @@ -71422,7 +72645,8 @@ See g_socket_set_listen_backlog() for details - + + The number of outstanding connections in the listen queue. @@ -71590,31 +72814,31 @@ use protocols not listed here. - A #GSocketService is an object that represents a service that + A `GSocketService` is an object that represents a service that is provided to the network or over local sockets. When a new -connection is made to the service the #GSocketService::incoming +connection is made to the service the [signal@Gio.SocketService::incoming] signal is emitted. -A #GSocketService is a subclass of #GSocketListener and you need +A `GSocketService` is a subclass of [class@Gio.SocketListener] and you need to add the addresses you want to accept connections on with the -#GSocketListener APIs. +[class@Gio.SocketListener] APIs. There are two options for implementing a network service based on -#GSocketService. The first is to create the service using -g_socket_service_new() and to connect to the #GSocketService::incoming -signal. The second is to subclass #GSocketService and override the -default signal handler implementation. +`GSocketService`. The first is to create the service using +[ctor@Gio.SocketService.new] and to connect to the +[signal@Gio.SocketService::incoming] signal. The second is to subclass +`GSocketService` and override the default signal handler implementation. In either case, the handler must immediately return, or else it will block additional incoming connections from being serviced. If you are interested in writing connection handlers that contain -blocking code then see #GThreadedSocketService. +blocking code then see [class@Gio.ThreadedSocketService]. The socket service runs on the main loop of the -[thread-default context][g-main-context-push-thread-default-context] -of the thread it is created in, and is not -threadsafe in general. However, the calls to start and stop the -service are thread-safe so these can be used from threads that +thread-default context (see +[method@GLib.MainContext.push_thread_default]) of the thread it is +created in, and is not threadsafe in general. However, the calls to start and +stop the service are thread-safe so these can be used from threads that handle incoming clients. Creates a new #GSocketService with no sockets to listen for. @@ -71848,20 +73072,22 @@ all the socket types. - SRV (service) records are used by some network protocols to provide + A single target host/port that a network service is running on. + +SRV (service) records are used by some network protocols to provide service-specific aliasing and load-balancing. For example, XMPP (Jabber) uses SRV records to locate the XMPP server for a domain; -rather than connecting directly to "example.com" or assuming a -specific server hostname like "xmpp.example.com", an XMPP client -would look up the "xmpp-client" SRV record for "example.com", and +rather than connecting directly to ‘example.com’ or assuming a +specific server hostname like ‘xmpp.example.com’, an XMPP client +would look up the `xmpp-client` SRV record for ‘example.com’, and then connect to whatever host was pointed to by that record. -You can use g_resolver_lookup_service() or -g_resolver_lookup_service_async() to find the #GSrvTargets +You can use [method@Gio.Resolver.lookup_service] or +[method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s for a given service. However, if you are simply planning to connect -to the remote service, you can use #GNetworkService's -#GSocketConnectable interface and not need to worry about -#GSrvTarget at all. +to the remote service, you can use [class@Gio.NetworkService]’s +[iface@Gio.SocketConnectable] interface and not need to worry about +`GSrvTarget` at all. Creates a new #GSrvTarget with the given parameters. @@ -72062,12 +73288,12 @@ and is not typically used by other code. - #GSubprocess allows the creation of and interaction with child + `GSubprocess` allows the creation of and interaction with child processes. Processes can be communicated with using standard GIO-style APIs (ie: -#GInputStream, #GOutputStream). There are GIO-style APIs to wait for -process termination (ie: cancellable and with an asynchronous +[class@Gio.InputStream], [class@Gio.OutputStream]). There are GIO-style APIs +to wait for process termination (ie: cancellable and with an asynchronous variant). There is an API to force a process to terminate, as well as a @@ -72075,50 +73301,50 @@ race-free API for sending UNIX signals to a subprocess. One major advantage that GIO brings over the core GLib library is comprehensive API for asynchronous I/O, such -g_output_stream_splice_async(). This makes GSubprocess +[method@Gio.OutputStream.splice_async]. This makes `GSubprocess` significantly more powerful and flexible than equivalent APIs in some other languages such as the `subprocess.py` -included with Python. For example, using #GSubprocess one could +included with Python. For example, using `GSubprocess` one could create two child processes, reading standard output from the first, processing it, and writing to the input stream of the second, all without blocking the main loop. -A powerful g_subprocess_communicate() API is provided similar to the +A powerful [method@Gio.Subprocess.communicate] API is provided similar to the `communicate()` method of `subprocess.py`. This enables very easy interaction with a subprocess that has been opened with pipes. -#GSubprocess defaults to tight control over the file descriptors open -in the child process, avoiding dangling-fd issues that are caused by -a simple fork()/exec(). The only open file descriptors in the +`GSubprocess` defaults to tight control over the file descriptors open +in the child process, avoiding dangling-FD issues that are caused by +a simple `fork()`/`exec()`. The only open file descriptors in the spawned process are ones that were explicitly specified by the -#GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was +`GSubprocess` API (unless `G_SUBPROCESS_FLAGS_INHERIT_FDS` was specified). -#GSubprocess will quickly reap all child processes as they exit, -avoiding "zombie processes" remaining around for long periods of -time. g_subprocess_wait() can be used to wait for this to happen, +`GSubprocess` will quickly reap all child processes as they exit, +avoiding ‘zombie processes’ remaining around for long periods of +time. [method@Gio.Subprocess.wait] can be used to wait for this to happen, but it will happen even without the call being explicitly made. -As a matter of principle, #GSubprocess has no API that accepts +As a matter of principle, `GSubprocess` has no API that accepts shell-style space-separated strings. It will, however, match the -typical shell behaviour of searching the PATH for executables that do +typical shell behaviour of searching the `PATH` for executables that do not contain a directory separator in their name. By default, the `PATH` of the current process is used. You can specify -%G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP to use the `PATH` of the +`G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP` to use the `PATH` of the launcher environment instead. -#GSubprocess attempts to have a very simple API for most uses (ie: +`GSubprocess` attempts to have a very simple API for most uses (ie: spawning a subprocess with arguments and support for most typical -kinds of input and output redirection). See g_subprocess_new(). The -#GSubprocessLauncher API is provided for more complicated cases +kinds of input and output redirection). See [ctor@Gio.Subprocess.new]. The +[class@Gio.SubprocessLauncher] API is provided for more complicated cases (advanced types of redirection, environment variable manipulation, change of working directory, child setup functions, etc). -A typical use of #GSubprocess will involve calling -g_subprocess_new(), followed by g_subprocess_wait_async() or -g_subprocess_wait(). After the process exits, the status can be -checked using functions such as g_subprocess_get_if_exited() (which -are similar to the familiar WIFEXITED-style POSIX macros). +A typical use of `GSubprocess` will involve calling +[ctor@Gio.Subprocess.new], followed by [method@Gio.Subprocess.wait_async] or +[method@Gio.Subprocess.wait]. After the process exits, the status can be +checked using functions such as [method@Gio.Subprocess.get_if_exited] (which +are similar to the familiar `WIFEXITED`-style POSIX macros). Create a new process with the given flags and varargs argument @@ -72738,12 +73964,14 @@ g_subprocess_wait_async(). - + + Argument vector. - + + Subprocess flags. @@ -72809,7 +74037,7 @@ example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and such as where its standard input and output will be directed, the argument list, the environment, and more. -While the #GSubprocess class has high level functions covering +While the [class@Gio.Subprocess] class has high level functions covering popular cases, use of this class allows access to more advanced options. It can also be used to launch multiple subprocesses with a similar configuration. @@ -73040,8 +74268,9 @@ This feature is only available on UNIX. a #GSubprocessLauncher - - + + a filename or %NULL + @@ -73293,7 +74522,8 @@ containing '='. On Windows, it should be in UTF-8. - + + [flags@Gio.SubprocessFlags] for launched processes. @@ -73565,514 +74795,516 @@ is the most common purpose in use. Used by TLS clients. - A #GTask represents and manages a cancellable "task". + A `GTask` represents and manages a cancellable ‘task’. ## Asynchronous operations -The most common usage of #GTask is as a #GAsyncResult, to +The most common usage of `GTask` is as a [iface@Gio.AsyncResult], to manage data during an asynchronous operation. You call -g_task_new() in the "start" method, followed by -g_task_set_task_data() and the like if you need to keep some +[ctor@Gio.Task.new] in the ‘start’ method, followed by +[method@Gio.Task.set_task_data] and the like if you need to keep some additional data associated with the task, and then pass the task object around through your asynchronous operation. Eventually, you will call a method such as -g_task_return_pointer() or g_task_return_error(), which will -save the value you give it and then invoke the task's callback -function in the -[thread-default main context][g-main-context-push-thread-default] +[method@Gio.Task.return_pointer] or [method@Gio.Task.return_error], which +will save the value you give it and then invoke the task’s callback +function in the thread-default main context (see +[method@GLib.MainContext.push_thread_default]) where it was created (waiting until the next iteration of the main -loop first, if necessary). The caller will pass the #GTask back to -the operation's finish function (as a #GAsyncResult), and you can -use g_task_propagate_pointer() or the like to extract the +loop first, if necessary). The caller will pass the `GTask` back to +the operation’s finish function (as a [iface@Gio.AsyncResult]), and you can +use [method@Gio.Task.propagate_pointer] or the like to extract the return value. -Using #GTask requires the thread-default #GMainContext from when the -#GTask was constructed to be running at least until the task has completed -and its data has been freed. +Using `GTask` requires the thread-default [struct@GLib.MainContext] from when +the `GTask` was constructed to be running at least until the task has +completed and its data has been freed. -If a #GTask has been constructed and its callback set, it is an error to +If a `GTask` has been constructed and its callback set, it is an error to not call `g_task_return_*()` on it. GLib will warn at runtime if this happens (since 2.76). -Here is an example for using GTask as a GAsyncResult: -|[<!-- language="C" --> - typedef struct { - CakeFrostingType frosting; - char *message; - } DecorationData; +Here is an example for using `GTask` as a [iface@Gio.AsyncResult]: +```c +typedef struct { + CakeFrostingType frosting; + char *message; +} DecorationData; + +static void +decoration_data_free (DecorationData *decoration) +{ + g_free (decoration->message); + g_slice_free (DecorationData, decoration); +} - static void - decoration_data_free (DecorationData *decoration) +static void +baked_cb (Cake *cake, + gpointer user_data) +{ + GTask *task = user_data; + DecorationData *decoration = g_task_get_task_data (task); + GError *error = NULL; + + if (cake == NULL) { - g_free (decoration->message); - g_slice_free (DecorationData, decoration); + g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + "Go to the supermarket"); + g_object_unref (task); + return; } - static void - baked_cb (Cake *cake, - gpointer user_data) + if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) { - GTask *task = user_data; - DecorationData *decoration = g_task_get_task_data (task); - GError *error = NULL; + g_object_unref (cake); + // g_task_return_error() takes ownership of error + g_task_return_error (task, error); + g_object_unref (task); + return; + } - if (cake == NULL) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - g_object_unref (task); - return; - } + g_task_return_pointer (task, cake, g_object_unref); + g_object_unref (task); +} - if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) - { - g_object_unref (cake); - // g_task_return_error() takes ownership of error - g_task_return_error (task, error); - g_object_unref (task); - return; - } +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + GTask *task; + DecorationData *decoration; + Cake *cake; - g_task_return_pointer (task, cake, g_object_unref); + task = g_task_new (self, cancellable, callback, user_data); + if (radius < 3) + { + g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, + "%ucm radius cakes are silly", + radius); g_object_unref (task); + return; } - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); + if (cake != NULL) { - GTask *task; - DecorationData *decoration; - Cake *cake; - - task = g_task_new (self, cancellable, callback, user_data); - if (radius < 3) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_TOO_SMALL, - "%ucm radius cakes are silly", - radius); - g_object_unref (task); - return; - } - - cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); - if (cake != NULL) - { - // _baker_get_cached_cake() returns a reffed cake - g_task_return_pointer (task, cake, g_object_unref); - g_object_unref (task); - return; - } + // _baker_get_cached_cake() returns a reffed cake + g_task_return_pointer (task, cake, g_object_unref); + g_object_unref (task); + return; + } - decoration = g_slice_new (DecorationData); - decoration->frosting = frosting; - decoration->message = g_strdup (message); - g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); + decoration = g_slice_new (DecorationData); + decoration->frosting = frosting; + decoration->message = g_strdup (message); + g_task_set_task_data (task, decoration, (GDestroyNotify) decoration_data_free); - _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); - } + _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); +} - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); +Cake * +baker_bake_cake_finish (Baker *self, + GAsyncResult *result, + GError **error) +{ + g_return_val_if_fail (g_task_is_valid (result, self), NULL); - return g_task_propagate_pointer (G_TASK (result), error); - } -]| + return g_task_propagate_pointer (G_TASK (result), error); +} +``` ## Chained asynchronous operations -#GTask also tries to simplify asynchronous operations that +`GTask` also tries to simplify asynchronous operations that internally chain together several smaller asynchronous -operations. g_task_get_cancellable(), g_task_get_context(), -and g_task_get_priority() allow you to get back the task's -#GCancellable, #GMainContext, and [I/O priority][io-priority] -when starting a new subtask, so you don't have to keep track -of them yourself. g_task_attach_source() simplifies the case +operations. [method@Gio.Task.get_cancellable], [method@Gio.Task.get_context], +and [method@Gio.Task.get_priority] allow you to get back the task’s +[class@Gio.Cancellable], [struct@GLib.MainContext], and +[I/O priority](iface.AsyncResult.html#io-priority) +when starting a new subtask, so you don’t have to keep track +of them yourself. [method@Gio.Task.attach_source] simplifies the case of waiting for a source to fire (automatically using the correct -#GMainContext and priority). +[struct@GLib.MainContext] and priority). Here is an example for chained asynchronous operations: - |[<!-- language="C" --> - typedef struct { - Cake *cake; - CakeFrostingType frosting; - char *message; - } BakingData; - - static void - decoration_data_free (BakingData *bd) - { - if (bd->cake) - g_object_unref (bd->cake); - g_free (bd->message); - g_slice_free (BakingData, bd); - } +```c +typedef struct { + Cake *cake; + CakeFrostingType frosting; + char *message; +} BakingData; - static void - decorated_cb (Cake *cake, - GAsyncResult *result, - gpointer user_data) - { - GTask *task = user_data; - GError *error = NULL; +static void +decoration_data_free (BakingData *bd) +{ + if (bd->cake) + g_object_unref (bd->cake); + g_free (bd->message); + g_slice_free (BakingData, bd); +} - if (!cake_decorate_finish (cake, result, &error)) - { - g_object_unref (cake); - g_task_return_error (task, error); - g_object_unref (task); - return; - } +static void +decorated_cb (Cake *cake, + GAsyncResult *result, + gpointer user_data) +{ + GTask *task = user_data; + GError *error = NULL; - // baking_data_free() will drop its ref on the cake, so we have to - // take another here to give to the caller. - g_task_return_pointer (task, g_object_ref (cake), g_object_unref); + if (!cake_decorate_finish (cake, result, &error)) + { + g_object_unref (cake); + g_task_return_error (task, error); g_object_unref (task); + return; } - static gboolean - decorator_ready (gpointer user_data) - { - GTask *task = user_data; - BakingData *bd = g_task_get_task_data (task); - - cake_decorate_async (bd->cake, bd->frosting, bd->message, - g_task_get_cancellable (task), - decorated_cb, task); + // baking_data_free() will drop its ref on the cake, so we have to + // take another here to give to the caller. + g_task_return_pointer (task, g_object_ref (cake), g_object_unref); + g_object_unref (task); +} - return G_SOURCE_REMOVE; - } +static gboolean +decorator_ready (gpointer user_data) +{ + GTask *task = user_data; + BakingData *bd = g_task_get_task_data (task); - static void - baked_cb (Cake *cake, - gpointer user_data) - { - GTask *task = user_data; - BakingData *bd = g_task_get_task_data (task); - GError *error = NULL; + cake_decorate_async (bd->cake, bd->frosting, bd->message, + g_task_get_cancellable (task), + decorated_cb, task); - if (cake == NULL) - { - g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, - "Go to the supermarket"); - g_object_unref (task); - return; - } + return G_SOURCE_REMOVE; +} - bd->cake = cake; +static void +baked_cb (Cake *cake, + gpointer user_data) +{ + GTask *task = user_data; + BakingData *bd = g_task_get_task_data (task); + GError *error = NULL; - // Bail out now if the user has already cancelled - if (g_task_return_error_if_cancelled (task)) - { - g_object_unref (task); - return; - } + if (cake == NULL) + { + g_task_return_new_error (task, BAKER_ERROR, BAKER_ERROR_NO_FLOUR, + "Go to the supermarket"); + g_object_unref (task); + return; + } - if (cake_decorator_available (cake)) - decorator_ready (task); - else - { - GSource *source; + bd->cake = cake; - source = cake_decorator_wait_source_new (cake); - // Attach @source to @task's GMainContext and have it call - // decorator_ready() when it is ready. - g_task_attach_source (task, source, decorator_ready); - g_source_unref (source); - } + // Bail out now if the user has already cancelled + if (g_task_return_error_if_cancelled (task)) + { + g_object_unref (task); + return; } - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - gint priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + if (cake_decorator_available (cake)) + decorator_ready (task); + else { - GTask *task; - BakingData *bd; + GSource *source; - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_priority (task, priority); + source = cake_decorator_wait_source_new (cake); + // Attach @source to @task’s GMainContext and have it call + // decorator_ready() when it is ready. + g_task_attach_source (task, source, decorator_ready); + g_source_unref (source); + } +} - bd = g_slice_new0 (BakingData); - bd->frosting = frosting; - bd->message = g_strdup (message); - g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + gint priority, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + GTask *task; + BakingData *bd; - _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); - } + task = g_task_new (self, cancellable, callback, user_data); + g_task_set_priority (task, priority); - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); + bd = g_slice_new0 (BakingData); + bd->frosting = frosting; + bd->message = g_strdup (message); + g_task_set_task_data (task, bd, (GDestroyNotify) baking_data_free); - return g_task_propagate_pointer (G_TASK (result), error); - } -]| + _baker_begin_cake (self, radius, flavor, cancellable, baked_cb, task); +} + +Cake * +baker_bake_cake_finish (Baker *self, + GAsyncResult *result, + GError **error) +{ + g_return_val_if_fail (g_task_is_valid (result, self), NULL); + + return g_task_propagate_pointer (G_TASK (result), error); +} +``` ## Asynchronous operations from synchronous ones -You can use g_task_run_in_thread() to turn a synchronous +You can use [method@Gio.Task.run_in_thread] to turn a synchronous operation into an asynchronous one, by running it in a thread. -When it completes, the result will be dispatched to the -[thread-default main context][g-main-context-push-thread-default] -where the #GTask was created. +When it completes, the result will be dispatched to the thread-default main +context (see [method@GLib.MainContext.push_thread_default]) where the `GTask` +was created. Running a task in a thread: - |[<!-- language="C" --> - typedef struct { - guint radius; - CakeFlavor flavor; - CakeFrostingType frosting; - char *message; - } CakeData; - - static void - cake_data_free (CakeData *cake_data) - { - g_free (cake_data->message); - g_slice_free (CakeData, cake_data); - } +```c +typedef struct { + guint radius; + CakeFlavor flavor; + CakeFrostingType frosting; + char *message; +} CakeData; - static void - bake_cake_thread (GTask *task, - gpointer source_object, - gpointer task_data, - GCancellable *cancellable) - { - Baker *self = source_object; - CakeData *cake_data = task_data; - Cake *cake; - GError *error = NULL; - - cake = bake_cake (baker, cake_data->radius, cake_data->flavor, - cake_data->frosting, cake_data->message, - cancellable, &error); - if (cake) - g_task_return_pointer (task, cake, g_object_unref); - else - g_task_return_error (task, error); - } +static void +cake_data_free (CakeData *cake_data) +{ + g_free (cake_data->message); + g_slice_free (CakeData, cake_data); +} - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) - { - CakeData *cake_data; - GTask *task; - - cake_data = g_slice_new (CakeData); - cake_data->radius = radius; - cake_data->flavor = flavor; - cake_data->frosting = frosting; - cake_data->message = g_strdup (message); - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_run_in_thread (task, bake_cake_thread); - g_object_unref (task); - } +static void +bake_cake_thread (GTask *task, + gpointer source_object, + gpointer task_data, + GCancellable *cancellable) +{ + Baker *self = source_object; + CakeData *cake_data = task_data; + Cake *cake; + GError *error = NULL; + + cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + cake_data->frosting, cake_data->message, + cancellable, &error); + if (cake) + g_task_return_pointer (task, cake, g_object_unref); + else + g_task_return_error (task, error); +} - Cake * - baker_bake_cake_finish (Baker *self, - GAsyncResult *result, - GError **error) - { - g_return_val_if_fail (g_task_is_valid (result, self), NULL); +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + CakeData *cake_data; + GTask *task; - return g_task_propagate_pointer (G_TASK (result), error); - } -]| + cake_data = g_slice_new (CakeData); + cake_data->radius = radius; + cake_data->flavor = flavor; + cake_data->frosting = frosting; + cake_data->message = g_strdup (message); + task = g_task_new (self, cancellable, callback, user_data); + g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + g_task_run_in_thread (task, bake_cake_thread); + g_object_unref (task); +} + +Cake * +baker_bake_cake_finish (Baker *self, + GAsyncResult *result, + GError **error) +{ + g_return_val_if_fail (g_task_is_valid (result, self), NULL); + + return g_task_propagate_pointer (G_TASK (result), error); +} +``` ## Adding cancellability to uncancellable tasks -Finally, g_task_run_in_thread() and g_task_run_in_thread_sync() -can be used to turn an uncancellable operation into a -cancellable one. If you call g_task_set_return_on_cancel(), -passing %TRUE, then if the task's #GCancellable is cancelled, -it will return control back to the caller immediately, while -allowing the task thread to continue running in the background -(and simply discarding its result when it finally does finish). +Finally, [method@Gio.Task.run_in_thread] and +[method@Gio.Task.run_in_thread_sync] can be used to turn an uncancellable +operation into a cancellable one. If you call +[method@Gio.Task.set_return_on_cancel], passing `TRUE`, then if the task’s +[class@Gio.Cancellable] is cancelled, it will return control back to the +caller immediately, while allowing the task thread to continue running in the +background (and simply discarding its result when it finally does finish). Provided that the task thread is careful about how it uses locks and other externally-visible resources, this allows you -to make "GLib-friendly" asynchronous and cancellable +to make ‘GLib-friendly’ asynchronous and cancellable synchronous variants of blocking APIs. Cancelling a task: - |[<!-- language="C" --> - static void - bake_cake_thread (GTask *task, - gpointer source_object, - gpointer task_data, - GCancellable *cancellable) +```c +static void +bake_cake_thread (GTask *task, + gpointer source_object, + gpointer task_data, + GCancellable *cancellable) +{ + Baker *self = source_object; + CakeData *cake_data = task_data; + Cake *cake; + GError *error = NULL; + + cake = bake_cake (baker, cake_data->radius, cake_data->flavor, + cake_data->frosting, cake_data->message, + &error); + if (error) { - Baker *self = source_object; - CakeData *cake_data = task_data; - Cake *cake; - GError *error = NULL; - - cake = bake_cake (baker, cake_data->radius, cake_data->flavor, - cake_data->frosting, cake_data->message, - &error); - if (error) - { - g_task_return_error (task, error); - return; - } - - // If the task has already been cancelled, then we don't want to add - // the cake to the cake cache. Likewise, we don't want to have the - // task get cancelled in the middle of updating the cache. - // g_task_set_return_on_cancel() will return %TRUE here if it managed - // to disable return-on-cancel, or %FALSE if the task was cancelled - // before it could. - if (g_task_set_return_on_cancel (task, FALSE)) - { - // If the caller cancels at this point, their - // GAsyncReadyCallback won't be invoked until we return, - // so we don't have to worry that this code will run at - // the same time as that code does. But if there were - // other functions that might look at the cake cache, - // then we'd probably need a GMutex here as well. - baker_add_cake_to_cache (baker, cake); - g_task_return_pointer (task, cake, g_object_unref); - } + g_task_return_error (task, error); + return; } - void - baker_bake_cake_async (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + // If the task has already been cancelled, then we don’t want to add + // the cake to the cake cache. Likewise, we don’t want to have the + // task get cancelled in the middle of updating the cache. + // g_task_set_return_on_cancel() will return %TRUE here if it managed + // to disable return-on-cancel, or %FALSE if the task was cancelled + // before it could. + if (g_task_set_return_on_cancel (task, FALSE)) { - CakeData *cake_data; - GTask *task; + // If the caller cancels at this point, their + // GAsyncReadyCallback won’t be invoked until we return, + // so we don’t have to worry that this code will run at + // the same time as that code does. But if there were + // other functions that might look at the cake cache, + // then we’d probably need a GMutex here as well. + baker_add_cake_to_cache (baker, cake); + g_task_return_pointer (task, cake, g_object_unref); + } +} - cake_data = g_slice_new (CakeData); +void +baker_bake_cake_async (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) +{ + CakeData *cake_data; + GTask *task; - ... + cake_data = g_slice_new (CakeData); - task = g_task_new (self, cancellable, callback, user_data); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_set_return_on_cancel (task, TRUE); - g_task_run_in_thread (task, bake_cake_thread); - } + ... - Cake * - baker_bake_cake_sync (Baker *self, - guint radius, - CakeFlavor flavor, - CakeFrostingType frosting, - const char *message, - GCancellable *cancellable, - GError **error) - { - CakeData *cake_data; - GTask *task; - Cake *cake; + task = g_task_new (self, cancellable, callback, user_data); + g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + g_task_set_return_on_cancel (task, TRUE); + g_task_run_in_thread (task, bake_cake_thread); +} - cake_data = g_slice_new (CakeData); +Cake * +baker_bake_cake_sync (Baker *self, + guint radius, + CakeFlavor flavor, + CakeFrostingType frosting, + const char *message, + GCancellable *cancellable, + GError **error) +{ + CakeData *cake_data; + GTask *task; + Cake *cake; - ... + cake_data = g_slice_new (CakeData); - task = g_task_new (self, cancellable, NULL, NULL); - g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); - g_task_set_return_on_cancel (task, TRUE); - g_task_run_in_thread_sync (task, bake_cake_thread); + ... - cake = g_task_propagate_pointer (task, error); - g_object_unref (task); - return cake; - } -]| + task = g_task_new (self, cancellable, NULL, NULL); + g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); + g_task_set_return_on_cancel (task, TRUE); + g_task_run_in_thread_sync (task, bake_cake_thread); + + cake = g_task_propagate_pointer (task, error); + g_object_unref (task); + return cake; +} +``` -## Porting from GSimpleAsyncResult +## Porting from [class@Gio.SimpleAsyncResult] -#GTask's API attempts to be simpler than #GSimpleAsyncResult's +`GTask`’s API attempts to be simpler than [class@Gio.SimpleAsyncResult]’s in several ways: -- You can save task-specific data with g_task_set_task_data(), and - retrieve it later with g_task_get_task_data(). This replaces the - abuse of g_simple_async_result_set_op_res_gpointer() for the same - purpose with #GSimpleAsyncResult. -- In addition to the task data, #GTask also keeps track of the - [priority][io-priority], #GCancellable, and - #GMainContext associated with the task, so tasks that consist of - a chain of simpler asynchronous operations will have easy access + +- You can save task-specific data with [method@Gio.Task.set_task_data], and + retrieve it later with [method@Gio.Task.get_task_data]. This replaces the + abuse of [method@Gio.SimpleAsyncResult.set_op_res_gpointer] for the same + purpose with [class@Gio.SimpleAsyncResult]. +- In addition to the task data, `GTask` also keeps track of the + [priority](iface.AsyncResult.html#io-priority), [class@Gio.Cancellable], + and [struct@GLib.MainContext] associated with the task, so tasks that + consist of a chain of simpler asynchronous operations will have easy access to those values when starting each sub-task. -- g_task_return_error_if_cancelled() provides simplified +- [method@Gio.Task.return_error_if_cancelled] provides simplified handling for cancellation. In addition, cancellation - overrides any other #GTask return value by default, like - #GSimpleAsyncResult does when - g_simple_async_result_set_check_cancellable() is called. - (You can use g_task_set_check_cancellable() to turn off that - behavior.) On the other hand, g_task_run_in_thread() + overrides any other `GTask` return value by default, like + [class@Gio.SimpleAsyncResult] does when + [method@Gio.SimpleAsyncResult.set_check_cancellable] is called. + (You can use [method@Gio.Task.set_check_cancellable] to turn off that + behavior.) On the other hand, [method@Gio.Task.run_in_thread] guarantees that it will always run your - `task_func`, even if the task's #GCancellable + `task_func`, even if the task’s [class@Gio.Cancellable] is already cancelled before the task gets a chance to run; you can start your `task_func` with a - g_task_return_error_if_cancelled() check if you need the + [method@Gio.Task.return_error_if_cancelled] check if you need the old behavior. -- The "return" methods (eg, g_task_return_pointer()) - automatically cause the task to be "completed" as well, and - there is no need to worry about the "complete" vs "complete - in idle" distinction. (#GTask automatically figures out - whether the task's callback can be invoked directly, or - if it needs to be sent to another #GMainContext, or delayed - until the next iteration of the current #GMainContext.) -- The "finish" functions for #GTask based operations are generally - much simpler than #GSimpleAsyncResult ones, normally consisting - of only a single call to g_task_propagate_pointer() or the like. - Since g_task_propagate_pointer() "steals" the return value from - the #GTask, it is not necessary to juggle pointers around to +- The ‘return’ methods (eg, [method@Gio.Task.return_pointer]) + automatically cause the task to be ‘completed’ as well, and + there is no need to worry about the ‘complete’ vs ‘complete in idle’ + distinction. (`GTask` automatically figures out + whether the task’s callback can be invoked directly, or + if it needs to be sent to another [struct@GLib.MainContext], or delayed + until the next iteration of the current [struct@GLib.MainContext].) +- The ‘finish’ functions for `GTask` based operations are generally + much simpler than [class@Gio.SimpleAsyncResult] ones, normally consisting + of only a single call to [method@Gio.Task.propagate_pointer] or the like. + Since [method@Gio.Task.propagate_pointer] ‘steals’ the return value from + the `GTask`, it is not necessary to juggle pointers around to prevent it from being freed twice. -- With #GSimpleAsyncResult, it was common to call - g_simple_async_result_propagate_error() from the +- With [class@Gio.SimpleAsyncResult], it was common to call + [method@Gio.SimpleAsyncResult.propagate_error] from the `_finish()` wrapper function, and have virtual method implementations only deal with successful returns. This behavior is deprecated, because it makes it - difficult for a subclass to chain to a parent class's async + difficult for a subclass to chain to a parent class’s async methods. Instead, the wrapper function should just be a simple wrapper, and the virtual method should call an appropriate `g_task_propagate_` function. Note that wrapper methods can now use - g_async_result_legacy_propagate_error() to do old-style - #GSimpleAsyncResult error-returning behavior, and - g_async_result_is_tagged() to check if a result is tagged as + [method@Gio.AsyncResult.legacy_propagate_error] to do old-style + [class@Gio.SimpleAsyncResult] error-returning behavior, and + [method@Gio.AsyncResult.is_tagged] to check if a result is tagged as having come from the `_async()` wrapper - function (for "short-circuit" results, such as when passing - 0 to g_input_stream_read_async()). + function (for ‘short-circuit’ results, such as when passing + `0` to [method@Gio.InputStream.read_async]). ## Thread-safety considerations Due to some infelicities in the API design, there is a -thread-safety concern that users of GTask have to be aware of: +thread-safety concern that users of `GTask` have to be aware of: If the `main` thread drops its last reference to the source object or the task data before the task is finalized, then the finalizers @@ -74082,7 +75314,6 @@ This is a problem if the finalizers use non-threadsafe API, and can lead to hard-to-debug crashes. Possible workarounds include: - Clear task data in a signal handler for `notify::completed` - - Keep iterating a main context in the main thread and defer dropping the reference to the source object to that main context when the task is finalized @@ -74237,8 +75468,9 @@ See also g_task_report_error(). A utility function for dealing with async operations where you need to wait for a #GSource to trigger. Attaches @source to @task's -#GMainContext with @task's [priority][io-priority], and sets @source's -callback to @callback, with @task as the callback's `user_data`. +#GMainContext with @task's [priority](iface.AsyncResult.html#io-priority), +and sets @source's callback to @callback, with @task as the callback's +`user_data`. It will set the @source’s name to the task’s name (as set with g_task_set_name()), if one has been set on the task and the source doesn’t @@ -74528,7 +75760,8 @@ you cannot assume that @error is still valid after calling this. Call g_error_copy() on the error if you need to keep a local copy as well. -See also g_task_return_new_error(). +See also [method@Gio.Task.return_new_error], +[method@Gio.Task.return_new_error_literal]. @@ -74610,6 +75843,36 @@ See also g_task_return_error(). + + Sets @task’s result to a new [type@GLib.Error] created from @domain, @code, +@message and completes the task. + +See [method@Gio.Task.return_pointer] for more discussion of exactly what +‘completing the task’ means. + +See also [method@Gio.Task.return_new_error]. + + + + + + a #GTask. + + + + a #GQuark. + + + + an error code. + + + + an error message + + + + Sets @task's result to @result and completes the task. If @result is not %NULL, then @result_destroy will be used to free @result if @@ -74648,6 +75911,41 @@ reference on it. + + Sets @task's result to @error (which @task assumes ownership of), with +the message prefixed according to @format, and completes the task +(see g_task_return_pointer() for more discussion of exactly what this +means). + +Note that since the task takes ownership of @error, and since the +task may be completed before returning from g_task_return_prefixed_error(), +you cannot assume that @error is still valid after calling this. +Call g_error_copy() on the error if you need to keep a local copy +as well. + +See also g_task_return_error(), g_prefix_error(). + + + + + + a #GTask. + + + + the #GError result of a task function. + + + + a string with format characters. + + + + a list of values to insert into @format. + + + + Sets @task's result to @result (by copying it) and completes the task. @@ -74809,7 +76107,7 @@ g_task_get_priority(). - the [priority][io-priority] of the request + the [priority](iface.AsyncResult.html#io-priority) of the request @@ -74979,7 +76277,7 @@ Other than in that case, @task will be completed when the - This is the subclass of #GSocketConnection that is created + This is the subclass of [class@Gio.SocketConnection] that is created for TCP/IP sockets. Checks if graceful disconnects are used. See @@ -75019,7 +76317,8 @@ take a while. For this reason it is disabled by default. - + + Whether [method@Gio.IOStream.close] does a graceful disconnect. @@ -75036,11 +76335,12 @@ take a while. For this reason it is disabled by default. - A #GTcpWrapperConnection can be used to wrap a #GIOStream that is -based on a #GSocket, but which is not actually a -#GSocketConnection. This is used by #GSocketClient so that it can -always return a #GSocketConnection, even when the connection it has -actually created is not directly a #GSocketConnection. + A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is +based on a [class@Gio.Socket], but which is not actually a +[class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so +that it can always return a [class@Gio.SocketConnection], even when the +connection it has actually created is not directly a +[class@Gio.SocketConnection]. Wraps @base_io_stream and @socket together as a #GSocketConnection. @@ -75071,7 +76371,8 @@ actually created is not directly a #GSocketConnection. - + + The wrapped [class@Gio.IOStream]. @@ -75088,21 +76389,21 @@ actually created is not directly a #GSocketConnection. - A helper class for testing code which uses D-Bus without touching the user's + A helper class for testing code which uses D-Bus without touching the user’s session bus. -Note that #GTestDBus modifies the user’s environment, calling setenv(). -This is not thread-safe, so all #GTestDBus calls should be completed before -threads are spawned, or should have appropriate locking to ensure no access -conflicts to environment variables shared between #GTestDBus and other -threads. +Note that `GTestDBus` modifies the user’s environment, calling +[`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus` +calls should be completed before threads are spawned, or should have +appropriate locking to ensure no access conflicts to environment variables +shared between `GTestDBus` and other threads. -## Creating unit tests using GTestDBus +## Creating unit tests using `GTestDBus` Testing of D-Bus services can be tricky because normally we only ever run D-Bus services over an existing instance of the D-Bus daemon thus we -usually don't activate D-Bus services that are not yet installed into the -target system. The #GTestDBus object makes this easier for us by taking care +usually don’t activate D-Bus services that are not yet installed into the +target system. The `GTestDBus` object makes this easier for us by taking care of the lower level tasks such as running a private D-Bus daemon and looking up uninstalled services in customizable locations, typically in your source code tree. @@ -75115,20 +76416,24 @@ The service file should list your service along with an absolute path to the uninstalled service executable in your source tree. Using autotools we would achieve this by adding a file such as `my-server.service.in` in the services directory and have it processed by configure. -|[ - [D-BUS Service] - Name=org.gtk.GDBus.Examples.ObjectManager - Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server -]| + +``` +[D-BUS Service] +Name=org.gtk.GDBus.Examples.ObjectManager +Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server +``` + You will also need to indicate this service directory in your test fixtures, so you will need to pass the path while compiling your test cases. Typically this is done with autotools with an added preprocessor flag specified to compile your tests such as: -|[ - -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" -]| - Once you have a service definition file which is local to your source tree, -you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. + +``` +-DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" +``` + +Once you have a service definition file which is local to your source tree, +you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding. An example of a test fixture for D-Bus services can be found here: @@ -75137,29 +76442,32 @@ here: Note that these examples only deal with isolating the D-Bus aspect of your service. To successfully run isolated unit tests on your service you may need some additional modifications to your test case fixture. For example; if your -service uses GSettings and installs a schema then it is important that your test service -not load the schema in the ordinary installed location (chances are that your service -and schema files are not yet installed, or worse; there is an older version of the -schema file sitting in the install location). +service uses [class@Gio.Settings] and installs a schema then it is important +that your test service not load the schema in the ordinary installed location +(chances are that your service and schema files are not yet installed, or +worse; there is an older version of the schema file sitting in the install +location). Most of the time we can work around these obstacles using the environment. Since the environment is inherited by the D-Bus daemon -created by #GTestDBus and then in turn inherited by any services the +created by `GTestDBus` and then in turn inherited by any services the D-Bus daemon activates, using the setup routine for your fixture is a practical place to help sandbox your runtime environment. For the rather typical GSettings case we can work around this by setting `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas -in the above fixture_setup() routine. +in the above `fixture_setup()` routine. -The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved -by compiling the schemas locally as a step before running test cases, an autotools setup might -do the following in the directory holding schemas: -|[ +The GSettings schemas need to be locally pre-compiled for this to work. This +can be achieved by compiling the schemas locally as a step before running +test cases, an autotools setup might do the following in the directory +holding schemas: + +``` all-am: $(GLIB_COMPILE_SCHEMAS) . CLEANFILES += gschemas.compiled -]| +``` Create a new #GTestDBus object. @@ -75293,11 +76601,13 @@ must be called after g_test_run(). - #GThemedIcon is an implementation of #GIcon that supports icon themes. -#GThemedIcon contains a list of all of the icons present in an icon -theme, so that icons can be looked up quickly. #GThemedIcon does + `GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon +themes. + +`GThemedIcon` contains a list of all of the icons present in an icon +theme, so that icons can be looked up quickly. `GThemedIcon` does not provide actual pixmaps for icons, just the icon names. -Ideally something like gtk_icon_theme_choose_icon() should be used to +Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to resolve the list of names so that fallback icons work nicely with themes that inherit other themes. @@ -75444,22 +76754,32 @@ would become + + #GThreadedResolver is an implementation of #GResolver which calls the libc +lookup functions in threads to allow them to run asynchronously. + + + + + + - A #GThreadedSocketService is a simple subclass of #GSocketService + A `GThreadedSocketService` is a simple subclass of [class@Gio.SocketService] that handles incoming connections by creating a worker thread and dispatching the connection to it by emitting the -#GThreadedSocketService::run signal in the new thread. +[signal@Gio.ThreadedSocketService::run signal] in the new thread. -The signal handler may perform blocking IO and need not return +The signal handler may perform blocking I/O and need not return until the connection is closed. The service is implemented using a thread pool, so there is a limited amount of threads available to serve incoming requests. -The service automatically stops the #GSocketService from accepting +The service automatically stops the [class@Gio.SocketService] from accepting new connections when all threads are busy. -As with #GSocketService, you may connect to #GThreadedSocketService::run, -or subclass and override the default handler. +As with [class@Gio.SocketService], you may connect to +[signal@Gio.ThreadedSocketService::run], or subclass and override the default +handler. Creates a new #GThreadedSocketService with no listeners. Listeners must be added with one of the #GSocketListener "add" methods. @@ -75491,7 +76811,8 @@ must be added with one of the #GSocketListener "add" methods. - + + The maximum number of threads handling clients for this service. @@ -75593,7 +76914,9 @@ not return until the connection is closed. - TLS (Transport Layer Security, aka SSL) and DTLS backend. + TLS (Transport Layer Security, aka SSL) and DTLS backend. This is an +internal type used to coordinate the different classes implemented +by a TLS backend. Gets the default #GTlsBackend for the system. @@ -75890,7 +77213,7 @@ support is available, and vice-versa. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a -#GTlsServerConnection). +[iface@Gio.TlsServerConnection]). Creates a #GTlsCertificate from the data in @file. @@ -76610,8 +77933,8 @@ binding type is not currently implemented. - #GTlsClientConnection is the client-side subclass of -#GTlsConnection, representing a client-side TLS connection. + `GTlsClientConnection` is the client-side subclass of +[class@Gio.TlsConnection], representing a client-side TLS connection. Creates a new #GTlsClientConnection wrapping @base_io_stream (which @@ -76945,12 +78268,13 @@ connect to #GTlsConnection::accept-certificate. - #GTlsConnection is the base TLS connection class type, which wraps -a #GIOStream and provides TLS encryption on top of it. Its -subclasses, #GTlsClientConnection and #GTlsServerConnection, -implement client-side and server-side TLS, respectively. + `GTlsConnection` is the base TLS connection class type, which wraps +a [class@Gio.IOStream] and provides TLS encryption on top of it. Its +subclasses, [iface@Gio.TlsClientConnection] and +[iface@Gio.TlsServerConnection], implement client-side and server-side TLS, +respectively. -For DTLS (Datagram TLS) support, see #GDtlsConnection. +For DTLS (Datagram TLS) support, see [iface@Gio.DtlsConnection]. @@ -77929,15 +79253,15 @@ case @error will be set. - #GTlsDatabase is used to look up 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. -A #GTlsDatabase may be accessed from multiple threads by the TLS backend. +A `GTlsDatabase` may be accessed from multiple threads by the TLS backend. All implementations are required to be fully thread-safe. Most common client applications will not directly interact with -#GTlsDatabase. It is used internally by #GTlsConnection. +`GTlsDatabase`. It is used internally by [class@Gio.TlsConnection]. Create a handle string for the certificate. The database will only be able to create a handle for certificates that originate from the database. In @@ -79421,8 +80745,8 @@ TLS-related routine. - #GTlsFileDatabase is implemented by #GTlsDatabase objects which load -their certificate information from a file. It is an interface which + `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which +load their certificate information from a file. It is an interface which TLS library specific subtypes implement. @@ -79463,25 +80787,25 @@ via the g_tls_database_verify_chain() operation. - #GTlsInteraction provides a mechanism for the TLS connection and database + `GTlsInteraction` provides a mechanism for the TLS connection and database code to interact with the user. It can be used to ask the user for passwords. -To use a #GTlsInteraction with a TLS connection use -g_tls_connection_set_interaction(). +To use a `GTlsInteraction` with a TLS connection use +[method@Gio.TlsConnection.set_interaction]. Callers should instantiate a derived class that implements the various interaction methods to show the required dialogs. Callers should use the 'invoke' functions like -g_tls_interaction_invoke_ask_password() to run interaction methods. These -functions make sure that the interaction is invoked in the main loop +[method@Gio.TlsInteraction.invoke_ask_password] to run interaction methods. +These functions make sure that the interaction is invoked in the main loop and not in the current thread, if the current thread is not running the main loop. -Derived classes can choose to implement whichever interactions methods they'd +Derived classes can choose to implement whichever interactions methods they’d like to support by overriding those virtual methods in their class initialization function. Any interactions not implemented will return -%G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, +`G_TLS_INTERACTION_UNHANDLED`. If a derived class implements an async method, it must also implement the corresponding finish method. Run synchronous interaction to ask the user for a password. In general, @@ -80171,7 +81495,8 @@ when finishing an interaction request. - Holds a password used in TLS. + An abstract interface representing a password used in TLS. Often used in +user interaction such as unlocking a key storage token. Create a new #GTlsPassword object. @@ -80216,7 +81541,7 @@ certain fixed length.) a #GTlsPassword object - + location to place the length of the password. @@ -80299,7 +81624,7 @@ certain fixed length.) a #GTlsPassword object - + location to place the length of the password. @@ -80432,13 +81757,16 @@ g_tls_password_get_flags(). - + + Description of what the password is for. - + + Flags about the password. - + + Warning about the password. @@ -80466,7 +81794,7 @@ g_tls_password_get_flags(). a #GTlsPassword object - + location to place the length of the password. @@ -80600,8 +81928,8 @@ g_tls_connection_set_rehandshake_mode(). - #GTlsServerConnection is the server-side subclass of #GTlsConnection, -representing a server-side TLS connection. + `GTlsServerConnection` is the server-side subclass of +[class@Gio.TlsConnection], representing a server-side TLS connection. Creates a new #GTlsServerConnection wrapping @base_io_stream (which @@ -80640,6 +81968,22 @@ rehandshake with a different mode from the initial handshake. + + + + + + + + + + + + + + + + @@ -80779,13 +82123,13 @@ rehandshake with a different mode from the initial handshake. - This is the subclass of #GSocketConnection that is created + This is the subclass of [class@Gio.SocketConnection] that is created for UNIX domain sockets. It contains functions to do some of the UNIX socket specific functionality like passing file descriptors. -Since GLib 2.72, #GUnixConnection is available on all platforms. It requires +Since GLib 2.72, `GUnixConnection` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. Before GLib 2.72, `<gio/gunixconnection.h>` belonged to the UNIX-specific GIO @@ -81024,19 +82368,19 @@ implementations. - This #GSocketControlMessage contains a #GCredentials instance. 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_FAMILY_UNIX family). + This [class@Gio.SocketControlMessage] contains a [class@Gio.Credentials] +instance. It may be sent using [method@Gio.Socket.send_message] and received +using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in +the `G_SOCKET_FAMILY_UNIX` family). For an easier way to send and receive credentials over stream-oriented UNIX sockets, see -g_unix_connection_send_credentials() and -g_unix_connection_receive_credentials(). To receive credentials of +[method@Gio.UnixConnection.send_credentials] and +[method@Gio.UnixConnection.receive_credentials]. To receive credentials of a foreign process connected to a socket, use -g_socket_get_credentials(). +[method@Gio.Socket.get_credentials]. -Since GLib 2.72, #GUnixCredentialMessage is available on all platforms. It +Since GLib 2.72, `GUnixCredentialMessage` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. @@ -81116,12 +82460,13 @@ when using it. This is no longer necessary since GLib 2.72. - A #GUnixFDList contains a list of file descriptors. It owns the file + A `GUnixFDList` contains a list of file descriptors. It owns the file descriptors that it contains, closing them when finalized. -It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in -the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() -and received using g_socket_receive_message(). +It may be wrapped in a [class@Gio.UnixFDMessage] and sent over a +[class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using +[method@Gio.Socket.send_message] and received using +[method@Gio.Socket.receive_message]. Before 2.74, `<gio/gunixfdlist.h>` belonged to the UNIX-specific GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when @@ -81352,15 +82697,15 @@ descriptors contained in @list, an empty array is returned. - 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_FAMILY_UNIX family). The file descriptors are copied + This [class@Gio.SocketControlMessage] contains a [class@Gio.UnixFDList]. +It may be sent using [method@Gio.Socket.send_message] and received using +[method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in the +`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 -stream-oriented UNIX sockets, see g_unix_connection_send_fd() and -g_unix_connection_receive_fd(). +stream-oriented UNIX sockets, see [method@Gio.UnixConnection.send_fd] and +[method@Gio.UnixConnection.receive_fd]. Note that `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config @@ -81462,7 +82807,8 @@ descriptors contained in @message, an empty array is returned. - + + The [class@Gio.UnixFDList] object to send with the message. @@ -81493,9 +82839,9 @@ descriptors contained in @message, an empty array is returned. - #GUnixInputStream implements #GInputStream for reading from a UNIX + `GUnixInputStream` implements [class@Gio.InputStream] for reading from a UNIX file descriptor, including asynchronous operations. (If the file -descriptor refers to a socket or pipe, this will use poll() to do +descriptor refers to a socket or pipe, this will use `poll()` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) @@ -81910,9 +83256,9 @@ is found. - #GUnixOutputStream implements #GOutputStream for writing to a UNIX + `GUnixOutputStream` implements [class@Gio.OutputStream] for writing to a UNIX file descriptor, including asynchronous operations. (If the file -descriptor refers to a socket or pipe, this will use poll() to do +descriptor refers to a socket or pipe, this will use `poll()` to do asynchronous I/O. If it refers to a regular file, it will fall back to doing asynchronous I/O in another thread.) @@ -82042,18 +83388,19 @@ when the stream is closed. - Support for UNIX-domain (also known as local) sockets. + Support for UNIX-domain (also known as local) sockets, corresponding to +`struct sockaddr_un`. UNIX domain sockets are generally visible in the filesystem. However, some systems support abstract socket names which are not visible in the filesystem and not affected by the filesystem permissions, visibility, etc. Currently this is only supported under Linux. If you attempt to use abstract sockets on other -systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED -errors. You can use g_unix_socket_address_abstract_names_supported() +systems, function calls may return `G_IO_ERROR_NOT_SUPPORTED` +errors. You can use [func@Gio.UnixSocketAddress.abstract_names_supported] to see if abstract names are supported. -Since GLib 2.72, #GUnixSocketAddress is available on all platforms. It +Since GLib 2.72, `GUnixSocketAddress` is available on all platforms. It requires underlying system support (such as Windows 10 with `AF_UNIX`) at run time. @@ -82225,13 +83572,16 @@ distinguishes between zero-padded and non-zero-padded abstract addresses. - + + The type of Unix socket address. - + + Unix socket path. - + + Unix socket path, as a byte array. @@ -83052,47 +84402,47 @@ created for @uri, or %NULL to continue with the default implementation. - The #GVolume interface represents user-visible objects that can be -mounted. Note, when porting from GnomeVFS, #GVolume is the moral -equivalent of #GnomeVFSDrive. - -Mounting a #GVolume instance is an asynchronous operation. For more -information about asynchronous operations, see #GAsyncResult and -#GTask. To mount a #GVolume, first call g_volume_mount() with (at -least) the #GVolume instance, optionally a #GMountOperation object -and a #GAsyncReadyCallback. - -Typically, one will only want to pass %NULL for the -#GMountOperation if automounting all volumes when a desktop session -starts since it's not desirable to put up a lot of dialogs asking + The `GVolume` interface represents user-visible objects that can be +mounted. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), +`GVolume` is the moral equivalent of `GnomeVFSDrive`. + +Mounting a `GVolume` instance is an asynchronous operation. For more +information about asynchronous operations, see [iface@Gio.AsyncResult] and +[class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount] +with (at least) the `GVolume` instance, optionally a +[class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback]. + +Typically, one will only want to pass `NULL` for the +[class@Gio.MountOperation] if automounting all volumes when a desktop session +starts since it’s not desirable to put up a lot of dialogs asking for credentials. The callback will be fired when the operation has resolved (either -with success or failure), and a #GAsyncResult instance will be +with success or failure), and a [iface@Gio.AsyncResult] instance will be passed to the callback. That callback should then call -g_volume_mount_finish() with the #GVolume instance and the -#GAsyncResult data to see if the operation was completed -successfully. If an @error is present when g_volume_mount_finish() -is called, then it will be filled with any error information. +[method@Gio.Volume.mount_finish] with the `GVolume` instance and the +[iface@Gio.AsyncResult] data to see if the operation was completed +successfully. If a [type@GLib.Error] is present when +[method@Gio.Volume.mount_finish] is called, then it will be filled with any +error information. -## Volume Identifiers # {#volume-identifier} +## Volume Identifiers It is sometimes necessary to directly access the underlying operating system object behind a volume (e.g. for passing a volume -to an application via the commandline). For this purpose, GIO -allows to obtain an 'identifier' for the volume. There can be +to an application via the command line). For this purpose, GIO +allows to obtain an ‘identifier’ for the volume. There can be different kinds of identifiers, such as Hal UDIs, filesystem labels, traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined strings as names for the different kinds of identifiers: -%G_VOLUME_IDENTIFIER_KIND_UUID, %G_VOLUME_IDENTIFIER_KIND_LABEL, etc. -Use g_volume_get_identifier() to obtain an identifier for a volume. - +`G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc. +Use [method@Gio.Volume.get_identifier] to obtain an identifier for a volume. -Note that %G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available -when the gvfs hal volume monitor is in use. Other volume monitors -will generally be able to provide the %G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE +Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available +when the GVFS hal volume monitor is in use. Other volume monitors +will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` identifier, which can be used to obtain a hal device by means of -libhal_manager_find_device_string_match(). +`libhal_manager_find_device_string_match()`. Checks if a volume can be ejected. @@ -83233,7 +84583,7 @@ and #GAsyncResult data returned in the @callback. - Gets the kinds of [identifiers][volume-identifier] that @volume has. + Gets the kinds of [identifiers](#volume-identifiers) that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. a %NULL-terminated array @@ -83320,7 +84670,7 @@ g_mount_is_shadowed() for more details. Gets the identifier of the given kind for @volume. -See the [introduction][volume-identifier] for more +See the [introduction](#volume-identifiers) for more information about volume identifiers. a newly allocated string containing the @@ -83625,7 +84975,7 @@ and #GAsyncResult data returned in the @callback. - Gets the kinds of [identifiers][volume-identifier] that @volume has. + Gets the kinds of [identifiers](#volume-identifiers) that @volume has. Use g_volume_get_identifier() to obtain the identifiers themselves. a %NULL-terminated array @@ -83712,7 +85062,7 @@ g_mount_is_shadowed() for more details. Gets the identifier of the given kind for @volume. -See the [introduction][volume-identifier] for more +See the [introduction](#volume-identifiers) for more information about volume identifiers. a newly allocated string containing the @@ -84278,14 +85628,14 @@ release them so the object can be finalized. - #GVolumeMonitor is for listing the user interesting devices and volumes + `GVolumeMonitor` is for listing the user interesting devices and volumes on the computer. In other words, what a file selector or file manager would show in a sidebar. -#GVolumeMonitor is not -[thread-default-context aware][g-main-context-push-thread-default], -and so should not be used other than from the main thread, with no -thread-default-context active. +`GVolumeMonitor` is not +thread-default-context aware (see +[method@GLib.MainContext.push_thread_default]), and so should not be used +other than from the main thread, with no thread-default-context active. In order to receive updates about volumes and mounts monitored through GVFS, a main loop must be running. @@ -85205,7 +86555,7 @@ GIO was used to unmount. - #GZlibCompressor is an implementation of #GConverter that + `GZlibCompressor` is an implementation of [iface@Gio.Converter] that compresses data using zlib. @@ -85267,10 +86617,13 @@ or after resetting it with g_converter_reset(). and modification time from the file info to the GZIP header. - + + The format of the compressed data. - + + The level of compression from `0` (no compression) to `9` (most +compression). `-1` for the default level. @@ -85293,7 +86646,7 @@ and #GZlibCompressor. - #GZlibDecompressor is an implementation of #GConverter that + `GZlibDecompressor` is an implementation of [iface@Gio.Converter] that decompresses data compressed with zlib. @@ -85333,7 +86686,8 @@ fully processed, is not present at all, or the compressor's #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP. - + + The format of the compressed data. @@ -85890,7 +87244,7 @@ the #GDBusConnection:exit-on-close property set to %TRUE. - + Starts acquiring @name on the bus specified by @bus_type and calls @name_acquired_handler and @name_lost_handler when the name is acquired respectively lost. Callbacks will be invoked in the @@ -85958,16 +87312,19 @@ unregister the objects (if any) in @name_lost_handler. a set of flags from the #GBusNameOwnerFlags enumeration - - handler to invoke when connected to the bus of type @bus_type or %NULL + + handler to invoke when + connected to the bus of type @bus_type or %NULL - - handler to invoke when @name is acquired or %NULL + + handler to invoke when + @name is acquired or %NULL - handler to invoke when @name is lost or %NULL + handler to invoke when @name + is lost or %NULL @@ -85980,7 +87337,7 @@ unregister the objects (if any) in @name_lost_handler. - + Like g_bus_own_name() but takes a #GDBusConnection instead of a #GBusType. @@ -86001,12 +87358,14 @@ unregister the objects (if any) in @name_lost_handler. a set of flags from the #GBusNameOwnerFlags enumeration - - handler to invoke when @name is acquired or %NULL + + handler to invoke when + @name is acquired or %NULL - handler to invoke when @name is lost or %NULL + handler to invoke when @name + is lost or %NULL @@ -86128,7 +87487,7 @@ after it’s stopped being iterated. - + Starts watching @name on the bus specified by @bus_type and calls @name_appeared_handler and @name_vanished_handler when the name is known to have an owner respectively known to lose its @@ -86176,12 +87535,14 @@ g_bus_unwatch_name() to stop watching the name. Flags from the #GBusNameWatcherFlags enumeration. - - Handler to invoke when @name is known to exist or %NULL. + + Handler to invoke when + @name is known to exist or %NULL. - Handler to invoke when @name is known to not exist or %NULL. + Handler to invoke when + @name is known to not exist or %NULL. @@ -86194,7 +87555,7 @@ g_bus_unwatch_name() to stop watching the name. - + Like g_bus_watch_name() but takes a #GDBusConnection instead of a #GBusType. @@ -86215,12 +87576,14 @@ g_bus_unwatch_name() to stop watching the name. Flags from the #GBusNameWatcherFlags enumeration. - - Handler to invoke when @name is known to exist or %NULL. + + Handler to invoke when + @name is known to exist or %NULL. - Handler to invoke when @name is known to not exist or %NULL. + Handler to invoke when + @name is known to not exist or %NULL. @@ -87255,59 +88618,6 @@ assumed to communicate with the server identified by @server_identity. - - #GIOExtensionPoint provides a mechanism for modules to extend the -functionality of the library or application that loaded it in an -organized fashion. - -An extension point is identified by a name, and it may optionally -require that any implementation must be of a certain type (or derived -thereof). Use g_io_extension_point_register() to register an -extension point, and g_io_extension_point_set_required_type() to -set a required type. - -A module can implement an extension point by specifying the #GType -that implements the functionality. Additionally, each implementation -of an extension point has a name, and a priority. Use -g_io_extension_point_implement() to implement an extension point. - - |[<!-- language="C" --> - GIOExtensionPoint *ep; - - // Register an extension point - ep = g_io_extension_point_register ("my-extension-point"); - g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); - ]| - - |[<!-- language="C" --> - // Implement an extension point - G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) - g_io_extension_point_implement ("my-extension-point", - my_example_impl_get_type (), - "my-example", - 10); - ]| - - It is up to the code that registered the extension point how - it uses the implementations that have been associated with it. - Depending on the use case, it may use all implementations, or - only the one with the highest priority, or pick a specific - one by name. - - To avoid opening all modules just to find out what extension - points they implement, GIO makes use of a caching mechanism, - see [gio-querymodules][gio-querymodules]. - You are expected to run this command after installing a - GIO module. - - The `GIO_EXTRA_MODULES` environment variable can be used to - specify additional directories to automatically load modules - from. This environment variable has the same syntax as the - `PATH`. If two modules have the same base name in different - directories, then the latter one will be ignored. If additional - directories are specified GIO will load modules from the built-in - directory last. - Constructs a #GFile from a vector of elements using the correct separator for filenames. @@ -87561,359 +88871,6 @@ the @parse_name cannot be parsed. - - These functions support exporting a #GActionGroup on D-Bus. -The D-Bus interface that is used is a private implementation -detail. - -To access an exported #GActionGroup remotely, use -g_dbus_action_group_get() to obtain a #GDBusActionGroup. - - - A content type is a platform specific string that defines the type -of a file. On UNIX it is a -[MIME type](http://www.wikipedia.org/wiki/Internet_media_type) -like `text/plain` or `image/png`. -On Win32 it is an extension string like `.doc`, `.txt` or a perceived -string like `audio`. Such strings can be looked up in the registry at -`HKEY_CLASSES_ROOT`. -On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) -such as `com.apple.application`. - - - Routines for working with D-Bus addresses. A D-Bus address is a string -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. - -Since GLib 2.72, `unix:` addresses are supported on Windows with `AF_UNIX` -support (Windows 10). - - - All facilities that return errors from remote methods (such as -g_dbus_connection_call_sync()) use #GError to represent both D-Bus -errors (e.g. errors returned from the other peer) and locally -in-process generated errors. - -To check if a returned #GError is an error from a remote peer, use -g_dbus_error_is_remote_error(). To get the actual D-Bus error name, -use g_dbus_error_get_remote_error(). Before presenting an error, -always use g_dbus_error_strip_remote_error(). - -In addition, facilities used to return errors to a remote peer also -use #GError. See g_dbus_method_invocation_return_error() for -discussion about how the D-Bus error name is set. - -Applications can associate a #GError error domain with a set of D-Bus errors in order to -automatically map from D-Bus errors to #GError and back. This -is typically done in the function returning the #GQuark for the -error domain: -|[<!-- language="C" --> -// foo-bar-error.h: - -#define FOO_BAR_ERROR (foo_bar_error_quark ()) -GQuark foo_bar_error_quark (void); - -typedef enum -{ - FOO_BAR_ERROR_FAILED, - FOO_BAR_ERROR_ANOTHER_ERROR, - FOO_BAR_ERROR_SOME_THIRD_ERROR, - FOO_BAR_N_ERRORS / *< skip >* / -} FooBarError; - -// foo-bar-error.c: - -static const GDBusErrorEntry foo_bar_error_entries[] = -{ - {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, - {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, - {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, -}; - -// Ensure that every error code has an associated D-Bus error name -G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); - -GQuark -foo_bar_error_quark (void) -{ - static gsize quark = 0; - g_dbus_error_register_error_domain ("foo-bar-error-quark", - &quark, - foo_bar_error_entries, - G_N_ELEMENTS (foo_bar_error_entries)); - return (GQuark) quark; -} -]| -With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and -other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError. - -If the other peer is using GDBus, and has registered the association with -g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark -generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead -of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover -org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). - -Note that the %G_DBUS_ERROR error domain is intended only -for returning errors from a remote message bus process. Errors -generated locally in-process by e.g. #GDBusConnection should use the -%G_IO_ERROR domain. - - - Various data structures and convenience routines to parse and -generate D-Bus introspection XML. Introspection information is -used when registering objects with g_dbus_connection_register_object(). - -The format of D-Bus introspection XML is specified in the -[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) - - - Convenience API for owning bus names. - -A simple example for owning a name can be found in -[gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c) - - - Convenience API for watching bus names. - -A simple example for watching a name can be found in -[gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c) - - - Various utility routines related to D-Bus. - - - File attributes in GIO consist of a list of key-value pairs. - -Keys are strings that contain a key namespace and a key name, separated -by a colon, e.g. "namespace::keyname". Namespaces are included to sort -key-value pairs by namespaces for relevance. Keys can be retrieved -using wildcards, e.g. "standard::*" will return all of the keys in the -"standard" namespace. - -The list of possible attributes for a filesystem (pointed to by a #GFile) is -available as a #GFileAttributeInfoList. This list is queryable by key names -as indicated earlier. - -Information is stored within the list in #GFileAttributeInfo structures. -The info structure can store different types, listed in the enum -#GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will -be set to %G_FILE_ATTRIBUTE_TYPE_INVALID. - -Classes that implement #GFileIface will create a #GFileAttributeInfoList and -install default keys and values for their given file system, architecture, -and other possible implementation details (e.g., on a UNIX system, a file -attribute key will be registered for the user id for a given file). - -## Default Namespaces - -- `"standard"`: The "Standard" namespace. General file information that - any application may need should be put in this namespace. Examples - include the file's name, type, and size. -- `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key - in this namespace is "value", which contains the value of the current - entity tag. -- `"id"`: The "Identification" namespace. This namespace is used by file - managers and applications that list directories to check for loops and - to uniquely identify files. -- `"access"`: The "Access" namespace. Used to check if a user has the - proper privileges to access files and perform file operations. Keys in - this namespace are made to be generic and easily understood, e.g. the - "can_read" key is %TRUE if the current user has permission to read the - file. UNIX permissions and NTFS ACLs in Windows should be mapped to - these values. -- `"mountable"`: The "Mountable" namespace. Includes simple boolean keys - for checking if a file or path supports mount operations, e.g. mount, - unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. -- `"time"`: The "Time" namespace. Includes file access, changed, created - times. -- `"unix"`: The "Unix" namespace. Includes UNIX-specific information and - may not be available for all files. Examples include the UNIX "UID", - "GID", etc. -- `"dos"`: The "DOS" namespace. Includes DOS-specific information and may - not be available for all files. Examples include "is_system" for checking - if a file is marked as a system file, and "is_archive" for checking if a - file is marked as an archive file. -- `"owner"`: The "Owner" namespace. Includes information about who owns a - file. May not be available for all file systems. Examples include "user" - for getting the user name of the file owner. This information is often - mapped from some backend specific data such as a UNIX UID. -- `"thumbnail"`: The "Thumbnail" namespace. Includes information about file - thumbnails and their location within the file system. Examples of keys in - this namespace include "path" to get the location of a thumbnail, "failed" - to check if thumbnailing of the file failed, and "is-valid" to check if - the thumbnail is outdated. -- `"filesystem"`: The "Filesystem" namespace. Gets information about the - file system where a file is located, such as its type, how much space is - left available, and the overall size of the file system. -- `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information - about the current GVFS backend in use. -- `"xattr"`: The "xattr" namespace. Gets information about extended - user attributes. See attr(5). The "user." prefix of the extended user - attribute name is stripped away when constructing keys in this namespace, - e.g. "xattr::mime_type" for the extended attribute with the name - "user.mime_type". Note that this information is only available if - GLib has been built with extended attribute support. -- `"xattr-sys"`: The "xattr-sys" namespace. Gets information about - extended attributes which are not user-specific. See attr(5). Note - that this information is only available if GLib has been built with - extended attribute support. -- `"selinux"`: The "SELinux" namespace. Includes information about the - SELinux context of files. Note that this information is only available - if GLib has been built with SELinux support. - -Please note that these are not all of the possible namespaces. -More namespaces can be added from GIO modules or by individual applications. -For more information about writing GIO modules, see #GIOModule. - -<!-- TODO: Implementation note about using extended attributes on supported -file systems --> - -## Default Keys - -For a list of the built-in keys and their types, see the -[GFileInfo][GFileInfo] documentation. - -Note that there are no predefined keys in the "xattr" and "xattr-sys" -namespaces. Keys for the "xattr" namespace are constructed by stripping -away the "user." prefix from the extended user attribute, and prepending -"xattr::". Keys for the "xattr-sys" namespace are constructed by -concatenating "xattr-sys::" with the extended attribute name. All extended -attribute values are returned as hex-encoded strings in which bytes outside -the ASCII range are encoded as escape sequences of the form \x`nn` -where `nn` is a 2-digit hexadecimal number. - - - Contains helper functions for reporting errors to the user. - - - As of GLib 2.36, #GIOScheduler is deprecated in favor of -#GThreadPool and #GTask. - -Schedules asynchronous I/O operations. #GIOScheduler integrates -into the main event loop (#GMainLoop) and uses threads. - - - These functions support exporting a #GMenuModel on D-Bus. -The D-Bus interface that is used is a private implementation -detail. - -To access an exported #GMenuModel remotely, use -g_dbus_menu_model_get() to obtain a #GDBusMenuModel. - - - The `<gio/gnetworking.h>` header can be included to get -various low-level networking-related system headers, automatically -taking care of certain portability issues for you. - -This can be used, for example, if you want to call setsockopt() -on a #GSocket. - -Note that while WinSock has many of the same APIs as the -traditional UNIX socket API, most of them behave at least slightly -differently (particularly with respect to error handling). If you -want your code to work under both UNIX and Windows, you will need -to take these differences into account. - -Also, under GNU libc, certain non-portable functions are only visible -in the headers if you define %_GNU_SOURCE before including them. Note -that this symbol must be defined before including any headers, or it -may not take effect. - - - Utility functions for #GPollableInputStream and -#GPollableOutputStream implementations. - - - #GTlsConnection and related classes provide TLS (Transport Layer -Security, previously known as SSL, Secure Sockets Layer) support for -gio-based network streams. - -#GDtlsConnection and related classes provide DTLS (Datagram TLS) support for -GIO-based network sockets, using the #GDatagramBased interface. The TLS and -DTLS APIs are almost identical, except TLS is stream-based and DTLS is -datagram-based. They share certificate and backend infrastructure. - -In the simplest case, for a client TLS connection, you can just set the -#GSocketClient:tls flag on a #GSocketClient, and then any -connections created by that client will have TLS negotiated -automatically, using appropriate default settings, and rejecting -any invalid or self-signed certificates (unless you change that -default by setting the #GSocketClient:tls-validation-flags -property). The returned object will be a #GTcpWrapperConnection, -which wraps the underlying #GTlsClientConnection. - -For greater control, you can create your own #GTlsClientConnection, -wrapping a #GSocketConnection (or an arbitrary #GIOStream with -pollable input and output streams) and then connect to its signals, -such as #GTlsConnection::accept-certificate, before starting the -handshake. - -Server-side TLS is similar, using #GTlsServerConnection. At the -moment, there is no support for automatically wrapping server-side -connections in the way #GSocketClient does for client-side -connections. - - - Routines for managing mounted UNIX mount points and paths. - -Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO -interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config -file when using it. - - - #GWin32InputStream implements #GInputStream for reading from a -Windows file handle. - -Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO -interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file -when using it. - - - #GWin32OutputStream implements #GOutputStream for writing to a -Windows file handle. - -Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO -interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file -when using it. - - - #GWin32RegistryKey represents a single Windows Registry key. - -#GWin32RegistryKey is used by a number of helper functions that read -Windows Registry. All keys are opened with read-only access, and at -the moment there is no API for writing into registry keys or creating -new ones. - -#GWin32RegistryKey implements the #GInitable interface, so if it is manually -constructed by e.g. g_object_new() you must call g_initable_init() and check -the results before using the object. This is done automatically -in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these -functions can return %NULL. - -To increase efficiency, a UTF-16 variant is available for all functions -that deal with key or value names in the registry. Use these to perform -deep registry queries or other operations that require querying a name -of a key or a value and then opening it (or querying its data). The use -of UTF-16 functions avoids the overhead of converting names to UTF-8 and -back. - -All functions operate in current user's context (it is not possible to -access registry tree of a different user). - -Key paths must use '\\' as a separator, '/' is not supported. Key names -must not include '\\', because it's used as a separator. Value names -can include '\\'. - -Key and value names are not case sensitive. - -Full key name (excluding the pre-defined ancestor's name) can't exceed -255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 -characters. Tree depth is limited to 512 levels. - Deserializes a #GIcon previously serialized using g_icon_serialize(). @@ -87979,15 +88936,27 @@ g_initable_init() instead. See #GParameter for more information. - Converts errno.h error codes into GIO error codes. The fallback -value %G_IO_ERROR_FAILED is returned for error codes not currently -handled (but note that future GLib releases may return a more + Converts `errno.h` error codes into GIO error codes. + +The fallback value %G_IO_ERROR_FAILED is returned for error codes not +currently handled (but note that future GLib releases may return a more specific value instead). -As %errno is global and may be modified by intermediate function -calls, you should save its value as soon as the call which sets it +As `errno` is global and may be modified by intermediate function +calls, you should save its value immediately after the call returns, +and use the saved value instead of `errno`: + + +|[<!-- language="C" --> + int saved_errno; + + ret = read (blah); + saved_errno = errno; + + g_io_error_from_errno (saved_errno); +]| - #GIOErrorEnum value for the given errno.h error number. + #GIOErrorEnum value for the given `errno.h` error number @@ -88178,7 +89147,7 @@ use g_io_modules_load_all_in_directory(). - + Cancels all cancellable I/O jobs. A job is cancellable if a #GCancellable was passed into @@ -88190,7 +89159,7 @@ gioscheduler. - + Schedules the I/O job to run in another thread. @notify will be called on @user_data after @job_func has returned, @@ -88556,6 +89525,16 @@ the specified protocol. + + + + + + + + + + Gets the #GResource Error Quark. diff --git a/Graphene-1.0.gir b/Graphene-1.0.gir index 566417d2..f87169c5 100644 --- a/Graphene-1.0.gir +++ b/Graphene-1.0.gir @@ -550,12 +550,6 @@ The returned value is owned by Graphene and should not be modified or freed. - - - - - - @@ -3200,23 +3194,6 @@ or graphene_point_init_from_point(), e.g.: - - Computes the squared distance between @a and @b. - - the distance between the two points, squared - - - - - a #graphene_point_t - - - - a #graphene_point_t - - - - Checks if the two points @a and @b point to the same coordinates. diff --git a/Gsk-4.0.gir b/Gsk-4.0.gir index eaceb4fb..16db3a1d 100644 --- a/Gsk-4.0.gir +++ b/Gsk-4.0.gir @@ -1655,6 +1655,12 @@ code, and what the corresponding C type is on the Gtk side. + + + + + + @@ -2065,11 +2071,8 @@ the 'mask value' with the alpha of the source. - - Same as gsk_gl_renderer_new(). - Use gsk_gl_renderer_new() + - a new GL renderer @@ -2296,7 +2299,7 @@ After creation, you cannot change the types it represents. Instead, new `GskPath` objects have to be created. The [struct@Gsk.PathBuilder] structure is meant to help in this endeavor. -Conceptually, a path consists of zero or more contours (continous, connected +Conceptually, a path consists of zero or more contours (continuous, connected curves), each of which may or may not be closed. Contours are typically constructed from Bézier segments. @@ -4467,17 +4470,20 @@ node to a file for later inspection. A node that uses OpenGL fragment shaders to render - - A node drawing a `GdkTexture` scaled and filtered (Since: 4.10) + + A node drawing a `GdkTexture` scaled and filtered. + + + A node that masks one child with another. - - A node that masks one child with another (Since: 4.10) + + A node that fills a path. - - A node that fills a path + + A node that strokes a path. - - A node that strokes a path + + A node that possibly redirects part of the scene graph to a subsurface. @@ -4547,6 +4553,8 @@ graph. Since GTK 4.6, the surface may be `NULL`, which allows using renderers without having to create a surface. +Since GTK 4.14, it is recommended to use [method@Gsk.Renderer.realize_for_display] +instead. Note that it is mandatory to call [method@Gsk.Renderer.unrealize] before destroying the renderer. @@ -4565,6 +4573,27 @@ destroying the renderer. + + Creates the resources needed by the @renderer to render the scene +graph. + +Note that it is mandatory to call [method@Gsk.Renderer.unrealize] before +destroying the renderer. + + Whether the renderer was successfully realized + + + + + a `GskRenderer` + + + + the `GdkDisplay` renderer will be used on + + + + Renders the scene graph, described by a tree of `GskRenderNode` instances to the renderer's surface, ensuring that the given @region gets redrawn. @@ -5831,6 +5860,57 @@ the @node. + + A render node that potentially diverts a part of the scene graph to a subsurface. + + Creates a `GskRenderNode` that will possibly divert the child +node to a subsurface. + +Note: Since subsurfaces are currently private, these nodes cannot +currently be created outside of GTK. See +[GtkGraphicsOffload](../gtk4/class.GraphicsOffload.html). + + A new `GskRenderNode` + + + + + The child to divert to a subsurface + + + + the subsurface to use + + + + + + Gets the subsurface that was set on this node + + the subsurface + + + + + a debug `GskRenderNode` + + + + + + Gets the child node that is getting drawn by the given @node. + + the child `GskRenderNode` + + + + + a debug `GskRenderNode` + + + + + A render node drawing a set of glyphs. @@ -6767,7 +6847,9 @@ with the given @transform. - A GSK renderer that is using Vulkan. + A GSK renderer that is using Vulkan. + +This renderer will fail to realize if Vulkan is not supported. diff --git a/Gtk-3.0.gir b/Gtk-3.0.gir index 21008e4e..8289a61c 100644 --- a/Gtk-3.0.gir +++ b/Gtk-3.0.gir @@ -9105,7 +9105,7 @@ container that has been allocated. - + Like gtk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -63095,7 +63095,7 @@ against at application run time. - + Like gtk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. diff --git a/Gtk-4.0.gir b/Gtk-4.0.gir index a63c9700..d159f329 100644 --- a/Gtk-4.0.gir +++ b/Gtk-4.0.gir @@ -1901,7 +1901,7 @@ roles: If that is not the case, a warning will be issued at run time. -In addition to this interface, its implementors are expected to provide the +In addition to this interface, its implementers are expected to provide the correct values for the following properties: - `GTK_ACCESSIBLE_PROPERTY_VALUE_MAX` @@ -2314,15 +2314,27 @@ developers must not use abstract roles in their code. Abstract role for windows. - - A type of push button - which stays pressed until depressed by a second activation. - Since: 4.10 + + A type of push button which stays pressed until depressed by a second +activation. - + A toplevel element of a graphical user interface. - This is the role that GTK uses by default for windows. - Since: 4.12 + +This is the role that GTK uses by default for windows. + + + A paragraph of content. + + + A section of content that is quoted from another source. + + + A section of a page that consists of a composition that forms an independent +part of a document, page, or site. + + + A comment contains content expressing reaction to other content. @@ -2381,10 +2393,9 @@ accessible property. A “selected” state; set when a widget is selected. Value type: boolean or undefined - - Indicates that a widget with the - GTK_ACCESSIBLE_ROLE_LINK has been visited. Value type: boolean. - Since: 4.12 + + Indicates that a widget with the GTK_ACCESSIBLE_ROLE_LINK has been visited. +Value type: boolean. @@ -3805,15 +3816,15 @@ positions the widget to line up the baselines, where that is supported. center natural width of widget inside the allocation - - a different name for `GTK_ALIGN_BASELINE`. Since 4.12 + + a different name for `GTK_ALIGN_BASELINE`. - align the widget according to the baseline. - See [class@Gtk.Widget]. Deprecated: 4.12: Use `GTK_ALIGN_BASELINE_FILL` instead + align the widget according to the baseline. + Use `GTK_ALIGN_BASELINE_FILL` instead - - stretch to fill all space, but align the baseline. Since 4.12 + + stretch to fill all space, but align the baseline. @@ -6561,7 +6572,7 @@ See gtk_assistant_commit() for details. add its own buttons through gtk_assistant_add_action_widget(). - + Like [func@get_binary_age], but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -16920,7 +16931,7 @@ accepted by GTK are allowed, and the accelerators are rendered in the same way as they are in menus. - + The modifier mask of the accelerator. @@ -16957,7 +16968,7 @@ configuration should assign keyvals to all keys. - the new acclerator modifier mask + the new accelerator modifier mask @@ -20130,7 +20141,7 @@ later. The button will be insensitive until that happens. This function is what should be used to obtain the color that was chosen by the user. To get -informed about changes, listen to "notify::color". +informed about changes, listen to "notify::rgba". the color @@ -25162,10 +25173,11 @@ only available when GTK has been configured with `-Ddebug=true`. Information about accessibility state changes - - Information about icon fallback. Since: 4.2 + + Information about icon fallback. - + + Inverts the default text-direction. @@ -27027,6 +27039,10 @@ Here is a UI definition example for `GtkDropDown` with a simple model: </object> ``` +If a `GtkDropDown` is created in this manner, or with +[ctor@Gtk.DropDown.new_from_strings], for instance, the object returned from +[method@Gtk.DropDown.get_selected_item] will be a [class@Gtk.StringObject]. + To learn more about the list widget framework, see the [overview](section-list-widget.html). @@ -33974,7 +33990,7 @@ property, or in a `<binding name="property">` tag to bind a property to an To create a property expression, use the `<lookup>` element. It can have a `type` attribute to specify the object type, and a `name` attribute to specify the property -to look up. The content of `<lookup>` can either be an element specfiying the expression +to look up. The content of `<lookup>` can either be an element specifying the expression to use the object, or a string that specifies the name of the object to use. Example: @@ -33983,6 +33999,11 @@ Example: <lookup name='search'>string_filter</lookup> ``` +Since the `<lookup>` element creates an expression and its element content can +itself be an expression, this means that `<lookup>` tags can also be nested. +This is a common idiom when dealing with `GtkListItem`s. See +[class@Gtk.BuilderListItemFactory] for an example of this technique. + To create a constant expression, use the `<constant>` element. If the type attribute is specified, the element content is interpreted as a value of that type. Otherwise, it is assumed to be an object. For instance: @@ -36706,6 +36727,19 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. + + Returns whether to make the file writable for the handler. + + `TRUE` if the file will be made writable + + + + + a `GtkFileLauncher` + + + + Launch an application to open the file. @@ -36846,6 +36880,22 @@ If `FALSE`, the file might be opened with a default app or the previous choice.< + + Sets whether to make the file writable for the handler. + + + + + + a `GtkFileLauncher` + + + + a `gboolean` + + + + @@ -36859,6 +36909,12 @@ the file might be opened with a default app or the previous choice. The file to launch. + + + + Whether to make the file writable for the handler. + + @@ -36934,7 +36990,7 @@ Depending on the @change parameter, not all items need to be changed, but only some. Refer to the [enum@Gtk.FilterChange] documentation for details. -This function is intended for implementors of `GtkFilter` +This function is intended for implementers of `GtkFilter` subclasses and should not be called from other functions. @@ -40183,15 +40239,15 @@ call and returns the resulting font description and font features. a `GAsyncResult` - + return location for font description - + return location for font features - + return location for the language @@ -41253,6 +41309,8 @@ of the frame as a title. `GtkGLArea` sets up its own [class@Gdk.GLContext], and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering. +The completed rendering is integrated into the larger GTK scene graph as +a texture. In order to draw, you have to connect to the [signal@Gtk.GLArea::render] signal, or subclass `GtkGLArea` and override the GtkGLAreaClass.render @@ -41270,6 +41328,8 @@ create a widget instance and connect to the [signal@Gtk.GLArea::render] signal: The `render()` function will be called when the `GtkGLArea` is ready for you to draw its content: +The initial contents of the framebuffer are transparent. + ```c static gboolean render (GtkGLArea *area, GdkGLContext *context) @@ -43343,7 +43403,7 @@ input devices. Sets the state of stylus-only -If true, the gesture will exclusivly handle events from stylus input deivces, +If true, the gesture will exclusively handle events from stylus input devices, otherwise it'll handle events from any pointing device. @@ -43354,7 +43414,7 @@ otherwise it'll handle events from any pointing device. - whether the gesture is used exclusivly for stylus events + whether the gesture is used exclusively for stylus events @@ -43542,6 +43602,142 @@ active, 1 is returned. + + A widget that allows to bypass gsk rendering for its child by passing the content +directly to the compositor. + +Graphics offload is an optimization to reduce overhead and battery use that is +most useful for video content. It only works on some platforms and in certain +situations. GTK will automatically fall back to normal rendering if it doesn't. + +Graphics offload is most efficient if there are no controls drawn on top of the +video content. + +You should consider using graphics offload for your main widget if it shows +frequently changing content (such as a video, or a VM display) and you provide +the content in the form of dmabuf textures (see [class@Gdk.DmabufTextureBuilder]), +in particular if it may be fullscreen. + +Numerous factors can prohibit graphics offload: + +- Unsupported platforms. Currently, graphics offload only works on Linux with Wayland. + +- Clipping, such as rounded corners that cause the video content to not be rectangular + +- Unsupported dmabuf formats (see [method@Gdk.Display.get_dmabuf_formats]) + +- Translucent video content (content with an alpha channel, even if it isn't used) + +- Transforms that are more complex than translations and scales + +- Filters such as opacity, grayscale or similar + +To investigate problems related graphics offload, GTK offers debug flags to print +out information about graphics offload and dmabuf use: + + GDK_DEBUG=offload + GDK_DEBUG=dmabuf + +The GTK inspector provides a visual debugging tool for graphics offload. + + + + + Creates a new GtkGraphicsOffload widget. + + the new widget + + + + + the child widget + + + + + + Gets the child of @self. + + the child widget + + + + + a `GtkGraphicsOffload` + + + + + + Returns whether offload is enabled for @self. + + whether offload is enabled + + + + + a `GtkGraphicsOffload` + + + + + + Sets the child of @self. + + + + + + a `GtkGraphicsOffload` + + + + the child widget + + + + + + Sets whether this GtkGraphicsOffload widget will attempt +to offload the content of its child widget. + + + + + + a `GtkGraphicsOffload` + + + + whether to enable offload + + + + + + + + The child widget. + + + + + + Whether graphics offload is enabled. + + + + + + + + + + + + + + `GtkGrid` is a container which arranges its child widgets in rows and columns. @@ -52321,7 +52517,7 @@ triggering @self. The key value for the trigger. - + The key modifiers for the trigger. @@ -52468,7 +52664,7 @@ such as a [class@Button]. ![An example GtkLabel](label.png) -# CSS nodes +## CSS nodes ``` label @@ -52489,15 +52685,16 @@ If the label has links, there is one subnode per link. These subnodes carry the link or visited state depending on whether they have been visited. In this case, label node also gets a .link style class. -# GtkLabel as GtkBuildable +## GtkLabel as GtkBuildable The GtkLabel implementation of the GtkBuildable interface supports a custom `<attributes>` element, which supports any number of `<attribute>` -elements. The <attribute> element has attributes named “name“, “value“, +elements. The `<attribute>` element has attributes named “name“, “value“, “start“ and “end“ and allows you to specify [struct@Pango.Attribute] values for this label. An example of a UI definition fragment specifying Pango attributes: + ```xml <object class="GtkLabel"> <attributes> @@ -52513,11 +52710,11 @@ applied to the whole text. Note that specifying ranges does not make much sense with translatable attributes. Use markup embedded in the translatable content instead. -# Accessibility +## Accessibility `GtkLabel` uses the %GTK_ACCESSIBLE_ROLE_LABEL role. -# Mnemonics +## Mnemonics Labels may contain “mnemonics”. Mnemonics are underlined characters in the label, used for keyboard navigation. Mnemonics are created by providing a @@ -52528,8 +52725,9 @@ to the functions [ctor@Gtk.Label.new_with_mnemonic] or Mnemonics automatically activate any activatable widget the label is inside, such as a [class@Gtk.Button]; if the label is not inside the mnemonic’s target widget, you have to tell the label about the target -using [class@Gtk.Label.set_mnemonic_widget]. Here’s a simple example where -the label is inside a button: +using [method@Gtk.Label.set_mnemonic_widget]. + +Here’s a simple example where the label is inside a button: ```c // Pressing Alt+H will activate this button @@ -52557,7 +52755,7 @@ GtkWidget *label = gtk_label_new_with_mnemonic ("_Hello"); gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); ``` -# Markup (styled text) +## Markup (styled text) To make it easy to format text in a label (changing colors, fonts, etc.), label text can be provided in a simple @@ -52587,14 +52785,14 @@ to [0, %G_MAXINT)). The reason is that specifying the start_index and end_index for a [struct@Pango.Attribute] requires knowledge of the exact string being displayed, so translations will cause problems. -# Selectable labels +## Selectable labels Labels can be made selectable with [method@Gtk.Label.set_selectable]. Selectable labels allow the user to copy the label contents to -the clipboard. Only labels that contain useful-to-copy information -— such as error messages — should be made selectable. +the clipboard. Only labels that contain useful-to-copy information—such +as error messages—should be made selectable. -# Text layout +## Text layout A label can contain any number of paragraphs, but will have performance problems if it contains more than a small number. @@ -52617,7 +52815,7 @@ width-chars is used as the minimum width, if specified, and max-width-chars is used as the natural width. Even if max-width-chars specified, wrapping labels will be rewrapped to use all of the available width. -# Links +## Links GTK supports markup for clickable hyperlinks in addition to regular Pango markup. The markup for links is borrowed from HTML, using the `<a>` with @@ -52626,7 +52824,7 @@ way they appear in web browsers, with colored, underlined text. The “titl attribute is displayed as a tooltip on the link. The “class“ attribute is used as style class on the CSS node for the link. -An example looks like this: +An example of inline links looks like this: ```c const char *text = @@ -54960,6 +55158,9 @@ This enumeration can be expanded at later date. The Mozilla Public License, version 2.0 + + Zero-Clause BSD license + A `GtkLinkButton` is a button with a hyperlink. @@ -58206,7 +58407,7 @@ against at application run time. - + Like [func@get_micro_version], but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -61370,7 +61571,7 @@ renderer, use [method@Gtk.Native.get_renderer]. Returns the renderer that is used for this `GtkNative`. - + the renderer for @self @@ -61383,7 +61584,7 @@ renderer, use [method@Gtk.Native.get_renderer]. Returns the surface of this `GtkNative`. - + the surface of @self @@ -63417,7 +63618,7 @@ For converting such a value to a `GtkOrdering` value, use the first value is larger than the second - + Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value. @@ -67378,11 +67579,7 @@ The created buttons are connected to actions found in the action groups that are accessible from the parent widget. This includes the `GtkApplicationWindow` to which the popover belongs. Actions can also be added using [method@Gtk.Widget.insert_action_group] -on the parent widget or on any of its parent widgets. - -The only flag that is supported currently is -%GTK_POPOVER_MENU_NESTED, which makes GTK create traditional, -nested submenus instead of the default sliding submenus. +on the parent widget or on any of its parent widgets. the new `GtkPopoverMenu` @@ -67509,7 +67706,7 @@ to @model. - + The flags that @popover uses to create/display a menu from its model. @@ -67658,13 +67855,16 @@ The model should only contain submenus as toplevel elements. - + Flags that affect how [class@Gtk.PopoverMenu] widgets built from a [class@Gio.MenuModel] are created and displayed. + + Submenus are presented as sliding submenus that + replace the main menu. + - Create submenus as nested - popovers. Without this flag, submenus are created as - sliding pages that replace the main menu. + Submenus are presented as traditional, nested + popovers. @@ -67981,6 +68181,401 @@ case. + + A `GtkPrintDialog` object collects the arguments that +are needed to present a print dialog to the user, such +as a title for the dialog and whether it should be modal. + +The dialog is shown with the [method@Gtk.PrintDialog.setup] function. +The actual printing can be done with [method@Gtk.PrintDialog.print] or +[method@Gtk.PrintDialog.print_file]. These APIs follows the GIO async pattern, +and the results can be obtained by calling the corresponding finish methods. + + Creates a new `GtkPrintDialog` object. + + the new `GtkPrintDialog` + + + + + Returns the label that will be shown on the +accept button of the print dialog. + + the accept label + + + + + a `GtkPrintDialog` + + + + + + Returns whether the print dialog blocks +interaction with the parent window while +it is presented. + + whether the print dialog is modal + + + + + a `GtkPrintDialog` + + + + + + Returns the page setup. + + the page setup + + + + + a `GtkPrintDialog` + + + + + + Returns the print settings for the print dialog. + + the settings + + + + + a `GtkPrintDialog` + + + + + + Returns the title that will be shown on the +print dialog. + + the title + + + + + a `GtkPrintDialog` + + + + + + This function prints content from a stream. + +If you pass `NULL` as @setup, then this method will present a print dialog. +Otherwise, it will attempt to print directly, without user interaction. + +The @callback will be called when the printing is done. It should call +[method@Gtk.PrintDialog.print_finish] to obtain the results. + + + + + + a `GtkPrintDialog` + + + + the parent `GtkWindow` + + + + the `GtkPrintSetup` to use + + + + a `GCancellable` to cancel the operation + + + + a callback to call when the operation is complete + + + + data to pass to @callback + + + + + + This function prints a file. + +If you pass `NULL` as @setup, then this method will present a print dialog. +Otherwise, it will attempt to print directly, without user interaction. + +The @callback will be called when the printing is done. It should call +[method@Gtk.PrintDialog.print_file_finish] to obtain the results. + + + + + + a `GtkPrintDialog` + + + + the parent `GtkWindow` + + + + the `GtkPrintSetup` to use + + + + the `GFile` to print + + + + a `GCancellable` to cancel the operation + + + + a callback to call when the operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.PrintDialog.print_file] call and +returns the results. + + Whether the call was successful + + + + + a `GtkPrintDialog` + + + + a `GAsyncResult` + + + + + + Finishes the [method@Gtk.PrintDialog.print] call and +returns the results. + +If the call was successful, the content to be printed should be +written to the returned output stream. Otherwise, `NULL` is returned. + +The overall results of the print operation will be returned in the +[method@Gio.OutputStream.close] call, so if you are interested in the +results, you need to explicitly close the output stream (it will be +closed automatically if you just unref it). Be aware that the close +call may not be instant as it operation will for the printer to finish +printing. + + a [class@Gio.OutputStream] + + + + + a `GtkPrintDialog` + + + + a `GAsyncResult` + + + + + + Sets the label that will be shown on the +accept button of the print dialog shown for +[method@Gtk.PrintDialog.setup]. + + + + + + a `GtkPrintDialog` + + + + the new accept label + + + + + + Sets whether the print dialog blocks +interaction with the parent window while +it is presented. + + + + + + a `GtkPrintDialog` + + + + the new value + + + + + + Set the page setup for the print dialog. + + + + + + a `GtkPrintDialog` + + + + the new page setup + + + + + + Sets the print settings for the print dialog. + + + + + + a `GtkPrintDialog` + + + + the new print settings + + + + + + Sets the title that will be shown on the print dialog. + + + + + + a `GtkPrintDialog` + + + + the new title + + + + + + This function presents a print dialog to let the user select a printer, +and set up print settings and page setup. + +The @callback will be called when the dialog is dismissed. +It should call [method@Gtk.PrintDialog.setup_finish] +to obtain the results in the form of a [struct@Gtk.PrintSetup], +that can then be passed to [method@Gtk.PrintDialog.print] +or [method@Gtk.PrintDialog.print_file]. + +One possible use for this method is to have the user select a printer, +then show a page setup UI in the application (e.g. to arrange images +on a page), then call [method@Gtk.PrintDialog.print] on @self +to do the printing without further user interaction. + + + + + + a `GtkPrintDialog` + + + + the parent `GtkWindow` + + + + a `GCancellable` to cancel the operation + + + + a callback to call when the operation is complete + + + + data to pass to @callback + + + + + + Finishes the [method@Gtk.PrintDialog.setup] call. + +If the call was successful, it returns a [struct@Gtk.PrintSetup] +which contains the print settings and page setup information that +will be used to print. + + The `GtkPrintSetup` object that resulted from the call, + or `NULL` if the call was not successful + + + + + a `GtkPrintDialog` + + + + a `GAsyncResult` + + + + + + + + A label that may be shown on the accept button of a print dialog +that is presented by [method@Gtk.PrintDialog.setup]. + + + + + + Whether the print dialog is modal. + + + + + + The page setup to use. + + + + + + The print settings to use. + + + + + + A title that may be shown on the print dialog that is +presented by [method@Gtk.PrintDialog.setup]. + + + + + + + + See also gtk_print_settings_set_duplex(). @@ -71808,6 +72403,78 @@ This has the same effect as setting the value to %NULL. + + A `GtkPrintSetup` is an auxiliary object for printing that allows decoupling +the setup from the printing. + +A print setup is obtained by calling [method@Gtk.PrintDialog.setup], +and can later be passed to print functions such as [method@Gtk.PrintDialog.print]. + +Print setups can be reused for multiple print calls. + +Applications may wish to store the page_setup and print_settings from the print setup +and copy them to the PrintDialog if they want to keep using them. + + Returns the page setup of @setup. + +It may be different from the `GtkPrintDialog`'s page setup +if the user changed it during the setup process. + + the page setup, or `NULL` + + + + + a `GtkPrintSetup` + + + + + + Returns the print settings of @setup. + +They may be different from the `GtkPrintDialog`'s settings +if the user changed them during the setup process. + + the print settings, or `NULL` + + + + + a `GtkPrintSetup` + + + + + + Increase the reference count of @setup. + + the print setup + + + + + a `GtkPrintSetup` + + + + + + Decrease the reference count of @setup. + +If the reference count reaches zero, +the object is freed. + + + + + + a `GtkPrintSetup` + + + + + The status gives a rough indication of the completion of a running print operation. @@ -76970,7 +77637,11 @@ Starting from GTK 4.12, `GtkScrolledWindow` uses the `GTK_ACCESSIBLE_ROLE_GENERI - Gets the child widget of @scrolled_window. + Gets the child widget of @scrolled_window. + +If the scrolled window automatically added a [class@Gtk.Viewport], this +function will return the viewport widget, and you can retrieve its child +using [method@Gtk.Viewport.get_child]. the child widget of @scrolled_window @@ -77211,7 +77882,11 @@ scrollbar to the child widget’s vertical scroll functionality. - Sets the child widget of @scrolled_window. + Sets the child widget of @scrolled_window. + +If @child does not implement the [iface@Gtk.Scrollable] interface, +the scrolled window will add @child to a [class@Gtk.Viewport] instance +and then add the viewport as its child widget. @@ -77513,7 +78188,11 @@ it defaults to %GTK_CORNER_TOP_LEFT. - The child widget. + The child widget. + +When setting this property, if the child widget does not implement +[iface@Gtk.Scrollable], the scrolled window will add the child to +a [class@Gtk.Viewport] and then set the viewport as the child. @@ -79582,6 +80261,10 @@ the desktop folder, %FALSE if not. the menubar, %FALSE if the app should display it itself. + + When %TRUE, widgets like switches include shapes to indicate their on/off state. + + The XDG sound theme to use for event sounds. @@ -83015,9 +83698,10 @@ For a rotation in 2D space, use [method@Gsk.Transform.rotate]. on an internal stack. When [method@Gtk.Snapshot.restore] is called, @snapshot will -be restored to the saved state. Multiple calls to -[method@Snapshot.save] and [class@Snapshot.restore] can be nested; -each call to `gtk_snapshot_restore()` restores the state from +be restored to the saved state. + +Multiple calls to [method@Gtk.Snapshot.save] and [method@Gtk.Snapshot.restore] +can be nested; each call to `gtk_snapshot_restore()` restores the state from the matching paired `gtk_snapshot_save()`. It is necessary to clear all saved states with corresponding @@ -83547,7 +84231,7 @@ Depending on the @change parameter, it may be possible to update the sort order without a full resorting. Refer to the [enum@Gtk.SorterChange] documentation for details. -This function is intended for implementors of `GtkSorter` +This function is intended for implementers of `GtkSorter` subclasses and should not be called from other functions. @@ -83979,6 +84663,20 @@ are updated accordingly. + + + Retrieves the value set by [method@Gtk.SpinButton.set_activates_default]. + + %TRUE if the spin button will activate the default widget + + + + + a `GtkSpinButton` + + + + Get the adjustment associated with a `GtkSpinButton`. @@ -84153,6 +84851,26 @@ exceeded. + + + Sets whether activating the spin button will activate the default +widget for the window containing the spin button. + +See [signal@Gtk.SpinButton::activate] for what counts as activation. + + + + + + a `GtkSpinButton` + + + + %TRUE to activate window’s default widget on activation + + + + Replaces the `GtkAdjustment` associated with @spin_button. @@ -84380,6 +85098,14 @@ direction by a specified amount. + + + + Whether to activate the default widget when the spin button is activated. + +See [signal@Gtk.SpinButton::activate] for what counts as activation. + + @@ -84430,6 +85156,18 @@ is acceptable. Whether a spin button should wrap upon reaching its limits. + + Emitted when the spin button is activated. + +The keybindings for this signal are all forms of the <kbd>Enter</kbd> key. + +If the <kbd>Enter</kbd> key results in the value being committed to the +spin button, then activation does not occur until <kbd>Enter</kbd> is +pressed again. + + + + Emitted when the user initiates a value change. @@ -86289,6 +87027,14 @@ gtk_string_list_take (self, g_strdup_print ("%d dollars", lots)); + + The type of items. See [method@Gio.ListModel.get_item_type]. + + + + The number of items. See [method@Gio.ListModel.get_n_items]. + + @@ -86741,12 +87487,11 @@ through [func@Gtk.StyleContext.add_provider_for_display]. - + Returns the scale used for assets. + Use [method@Gtk.Widget.get_scale_factor] instead - the scale - -Deprecated 4.10: Use [method@Gtk.Widget.get_scale_factor] instead + the scale @@ -107579,6 +108324,22 @@ a file. + + + Returns whether graphics offload is enabled. + +See [class@Gtk.GraphicsOffload] for more information on graphics offload. + + the graphics offload status + + + + + a `GtkVideo` + + + + Returns %TRUE if videos have been set to loop. @@ -107660,6 +108421,25 @@ This is a utility function that calls gtk_video_set_file(), + + + Sets whether to enable graphics offload. + +See [class@Gtk.GraphicsOffload] for more information on graphics offload. + + + + + + a `GtkVideo` + + + + the new graphics offload status + + + + Sets whether new files loaded by @self should be set to loop. @@ -107731,6 +108511,12 @@ This is a utility function that calls [method@Gtk.Video.set_file]. The file played by this video if the video is playing a file. + + + + Whether to enable graphics offload. + + @@ -108236,7 +109022,13 @@ Additionally, `<object>` tags can also be added before and after the initi which might be referenced by other widgets declared as children of the `<template>` tag. -An example of a template definition: +Since, unlike the `<object>` tag, the `<template>` tag does not contain an +“id” attribute, if you need to refer to the instance of the object itself that +the template will create, simply refer to the template class name in an +applicable element content. + +Here is an example of a template definition, which includes an example of +this in the `<signal>` tag: ```xml <interface> @@ -116903,7 +117695,7 @@ See [func@Gtk.init]. - + Converts the result of a `GCompareFunc` like strcmp() to a `GtkOrdering` value.