diff --git a/GLib-2.0.gir b/GLib-2.0.gir index 68dd486..0a894f0 100644 --- a/GLib-2.0.gir +++ b/GLib-2.0.gir @@ -2658,7 +2658,11 @@ together. Create byte array containing the data. The data will be owned by the array -and will be freed with g_free(), i.e. it could be allocated using g_strdup(). +and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + +Do not use it if @len is greater than %G_MAXUINT. #GByteArray +stores the length of its data in #guint, which may be shorter than +#gsize. a new #GByteArray @@ -3230,7 +3234,11 @@ the same byte data. As an optimization, the byte data is transferred to the array without copying if this was the last reference to bytes and bytes was created with g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all -other cases the data is copied. +other cases the data is copied. + +Do not use it if @bytes contains more than %G_MAXUINT +bytes. #GByteArray stores the length of its data in #guint, which +may be shorter than #gsize, that @bytes is using. a new mutable #GByteArray containing the same byte data @@ -3322,7 +3330,7 @@ vector of raw bytes. Once either g_checksum_get_string() or g_checksum_get_digest() have been called on a #GChecksum, the checksum will be closed and it won't be possible to call g_checksum_update() on it anymore. - + the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. @@ -3339,8 +3347,8 @@ on it anymore. g_checksum_get_string() or g_checksum_get_digest(), the copied checksum will be closed as well. - the copy of the passed #GChecksum. Use g_checksum_free() - when finished using it. + the copy of the passed #GChecksum. Use + g_checksum_free() when finished using it. @@ -6044,6 +6052,25 @@ February on a non-leap year, the day will be clamped to 28th February. + + A comparison function for #GDateTimes that is suitable +as a #GCompareFunc. Both #GDateTimes must be non-%NULL. + + -1, 0 or 1 if @dt1 is less than, equal to or greater + than @dt2. + + + + + first #GDateTime to compare + + + + second #GDateTime to compare + + + + Calculates the difference in time between @end and @begin. The #GTimeSpan that is returned is effectively @end - @begin (ie: @@ -6064,6 +6091,26 @@ positive if the first parameter is larger). + + Checks to see if @dt1 and @dt2 are equal. + +Equal here means that they represent the same moment after converting +them to the same time zone. + + %TRUE if @dt1 and @dt2 are equal + + + + + a #GDateTime + + + + a #GDateTime + + + + Creates a newly allocated string representing the requested @format. @@ -6485,6 +6532,19 @@ if 4 or more days of that week are contained within the new year. + + Hashes @datetime into a #guint, suitable for use within #GHashTable. + + a #guint containing the hash + + + + + a #GDateTime + + + + Determines if daylight savings time is in effect at the time and in the time zone of @datetime. @@ -6634,58 +6694,6 @@ When the reference count reaches zero, the resources allocated by - - A comparison function for #GDateTimes that is suitable -as a #GCompareFunc. Both #GDateTimes must be non-%NULL. - - -1, 0 or 1 if @dt1 is less than, equal to or greater - than @dt2. - - - - - first #GDateTime to compare - - - - second #GDateTime to compare - - - - - - Checks to see if @dt1 and @dt2 are equal. - -Equal here means that they represent the same moment after converting -them to the same time zone. - - %TRUE if @dt1 and @dt2 are equal - - - - - a #GDateTime - - - - a #GDateTime - - - - - - Hashes @datetime into a #guint, suitable for use within #GHashTable. - - a #guint containing the hash - - - - - a #GDateTime - - - - Enumeration representing a day of the week; #G_DATE_MONDAY, @@ -10996,7 +11004,7 @@ the line breaks between lines, but does not include the final line break. a group name, or %NULL - + a key @@ -11325,7 +11333,7 @@ be %NULL. Returns the name of the start group of the file. - + The start group of the key file. @@ -13441,7 +13449,7 @@ linked against at application run time. The maximum value which can be held in a #guint8. - + The micro version number of the GLib library. Like #gtk_micro_version, but from the headers used at @@ -13535,7 +13543,10 @@ a typical event source will use g_source_add_unix_fd() instead. - Passes the results of polling back to the main loop. + Passes the results of polling back to the main loop. You should be +careful to pass @fds and its length @n_fds as received from +g_main_context_query(), as this functions relies on assumptions +on how @fds is filled. You must have successfully acquired the context with g_main_context_acquire() before you may call this function. @@ -13882,7 +13893,10 @@ see g_file_supports_thread_contexts(). - Determines information necessary to poll this main loop. + Determines information necessary to poll this main loop. You should +be careful to pass the resulting @fds array and its length @n_fds +as is when calling g_main_context_check(), as this function relies +on assumptions made when the array is filled. You must have successfully acquired the context with g_main_context_acquire() before you may call this function. @@ -14040,7 +14054,7 @@ loop with a termination condition, computed from multiple threads: |[<!-- language="C" --> #define NUM_TASKS 10 - static volatile gint tasks_remaining = NUM_TASKS; + static gint tasks_remaining = NUM_TASKS; // (atomic) ... while (g_atomic_int_get (&tasks_remaining) != 0) @@ -14086,7 +14100,7 @@ always return %NULL if you are running in the default thread.) If you need to hold a reference on the context, use g_main_context_ref_thread_default() instead. - + the thread-default #GMainContext, or %NULL if the thread-default context is the global default context. @@ -16247,7 +16261,10 @@ like this: } // use initialization_value here -]| +]| + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. %TRUE if the initialization section should be entered, %FALSE and blocks otherwise @@ -16266,7 +16283,10 @@ like this: 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter() on this -initialization variable. +initialization variable. + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. @@ -17752,9 +17772,9 @@ function has been set for @array. This function is not thread-safe. If using a #GPtrArray from multiple threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() functions. - - the pointer array if @free_seg is %FALSE, otherwise %NULL. - The pointer array should be freed using g_free(). + + the pointer array if @free_seg is + %FALSE, otherwise %NULL. The pointer array should be freed using g_free(). @@ -19241,13 +19261,19 @@ to undefined behaviour. Obtain a read lock on @rw_lock. If another thread currently holds -the write lock on @rw_lock, the current thread will block. If another thread -does not hold the write lock, but is waiting for it, it is implementation -defined whether the reader or writer will block. Read locks can be taken +the write lock on @rw_lock, the current thread will block until the +write lock was (held and) released. If another thread does not hold +the write lock, but is waiting for it, it is implementation defined +whether the reader or writer will block. Read locks can be taken recursively. -It is implementation-defined how many threads are allowed to -hold read locks on the same lock simultaneously. If the limit is hit, +Calling g_rw_lock_reader_lock() while the current thread already +owns a write lock leads to undefined behaviour. Read locks however +can be taken recursively, in which case you need to make sure to +call g_rw_lock_reader_unlock() the same amount of times. + +It is implementation-defined how many read locks are allowed to be +held on the same lock simultaneously. If the limit is hit, or if a deadlock is detected, a critical warning will be emitted. @@ -19290,9 +19316,12 @@ by the current thread leads to undefined behaviour. - Obtain a write lock on @rw_lock. If any thread already holds + Obtain a write lock on @rw_lock. If another thread currently holds a read or write lock on @rw_lock, the current thread will block -until all other threads have dropped their locks on @rw_lock. +until all other threads have dropped their locks on @rw_lock. + +Calling g_rw_lock_writer_lock() while the current thread already +owns a read or write lock on @rw_lock leads to undefined behaviour. @@ -19304,8 +19333,9 @@ until all other threads have dropped their locks on @rw_lock. - Tries to obtain a write lock on @rw_lock. If any other thread holds -a read or write lock on @rw_lock, it immediately returns %FALSE. + Tries to obtain a write lock on @rw_lock. If another thread +currently holds a read or write lock on @rw_lock, it immediately +returns %FALSE. Otherwise it locks @rw_lock and returns %TRUE. %TRUE if @rw_lock could be locked @@ -22734,9 +22764,9 @@ than the number of items in @seq, the end iterator is returned. - Returns the length of @seq. Note that this method is O(h) where `h' is the -height of the tree. It is thus more efficient to use g_sequence_is_empty() -when comparing the length to zero. + Returns the positive length (>= 0) of @seq. Note that this method is +O(h) where `h' is the height of the tree. It is thus more efficient +to use g_sequence_is_empty() when comparing the length to zero. the length of @seq @@ -23786,7 +23816,7 @@ is unique within the #GMainContext instance passed to g_source_attach(). Gets a name for the source, used in debugging and profiling. The name may be #NULL if it has never been set with g_source_set_name(). - + the name of the source @@ -23859,10 +23889,10 @@ idle_callback (gpointer data) { SomeWidget *self = data; - GDK_THREADS_ENTER (); + g_mutex_lock (&self->idle_id_mutex); // do stuff with self self->idle_id = 0; - GDK_THREADS_LEAVE (); + g_mutex_unlock (&self->idle_id_mutex); return G_SOURCE_REMOVE; } @@ -23870,9 +23900,19 @@ idle_callback (gpointer data) static void some_widget_do_stuff_later (SomeWidget *self) { + g_mutex_lock (&self->idle_id_mutex); self->idle_id = g_idle_add (idle_callback, self); + g_mutex_unlock (&self->idle_id_mutex); } +static void +some_widget_init (SomeWidget *self) +{ + g_mutex_init (&self->idle_id_mutex); + + // ... +} + static void some_widget_finalize (GObject *object) { @@ -23881,6 +23921,8 @@ some_widget_finalize (GObject *object) if (self->idle_id) g_source_remove (self->idle_id); + g_mutex_clear (&self->idle_id_mutex); + G_OBJECT_CLASS (parent_class)->finalize (object); } ]| @@ -23897,12 +23939,12 @@ idle_callback (gpointer data) { SomeWidget *self = data; - GDK_THREADS_ENTER (); + g_mutex_lock (&self->idle_id_mutex); if (!g_source_is_destroyed (g_main_current_source ())) { // do stuff with self } - GDK_THREADS_LEAVE (); + g_mutex_unlock (&self->idle_id_mutex); return FALSE; } @@ -26609,71 +26651,15 @@ g_date_time_unref (dt); #GTimeZone is an opaque structure whose members cannot be accessed directly. - - Creates a #GTimeZone corresponding to @identifier. + + A version of g_time_zone_new_identifier() which returns the UTC time zone +if @identifier could not be parsed or loaded. -@identifier can either be an RFC3339/ISO 8601 time offset or -something that would pass as a valid value for the `TZ` environment -variable (including %NULL). - -In Windows, @identifier can also be the unlocalized name of a time -zone for standard time, for example "Pacific Standard Time". - -Valid RFC3339 time offsets are `"Z"` (for UTC) or -`"±hh:mm"`. ISO 8601 additionally specifies -`"±hhmm"` and `"±hh"`. Offsets are -time values to be added to Coordinated Universal Time (UTC) to get -the local time. - -In UNIX, the `TZ` environment variable typically corresponds -to the name of a file in the zoneinfo database, an absolute path to a file -somewhere else, or a string in -"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. -There are no spaces in the specification. The name of standard -and daylight savings time zone must be three or more alphabetic -characters. Offsets are time values to be added to local time to -get Coordinated Universal Time (UTC) and should be -`"[±]hh[[:]mm[:ss]]"`. Dates are either -`"Jn"` (Julian day with n between 1 and 365, leap -years not counted), `"n"` (zero-based Julian day -with n between 0 and 365) or `"Mm.w.d"` (day d -(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day -0 is a Sunday). Times are in local wall clock time, the default is -02:00:00. - -In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also -accepts POSIX format. The Windows format uses US rules for all time -zones; daylight savings time is 60 minutes behind the standard time -with date and time of change taken from Pacific Standard Time. -Offsets are time values to be added to the local time to get -Coordinated Universal Time (UTC). - -g_time_zone_new_local() calls this function with the value of the -`TZ` environment variable. This function itself is independent of -the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` -will be consulted to discover the correct time zone on UNIX and the -registry will be consulted or GetTimeZoneInformation() will be used -to get the local time zone on Windows. - -If intervals are not available, only time zone rules from `TZ` -environment variable or other means, then they will be computed -from year 1900 to 2037. If the maximum year for the rules is -available and it is greater than 2037, then it will followed -instead. - -See -[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) -for a precise definition of valid RFC3339 time offsets -(the `time-offset` expansion) and ISO 8601 for the -full list of valid time offsets. See -[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) -for an explanation of the possible -values of the `TZ` environment variable. See -[Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) -for the list of time zones on Windows. - -You should release the return value by calling g_time_zone_unref() -when you are done with it. +If you need to check whether @identifier was loaded successfully, use +g_time_zone_new_identifier(). + Use g_time_zone_new_identifier() instead, as it provides + error reporting. Change your code to handle a potentially %NULL return + value. the requested timezone @@ -27400,17 +27386,8 @@ If the root node has children the height is 2, etc. Inserts a key/value pair into a #GTree. -If the given key already exists in the #GTree its corresponding value -is set to the new value. If you supplied a @value_destroy_func when -creating the #GTree, the old value is freed using that function. If -you supplied a @key_destroy_func when creating the #GTree, the passed -key is freed using that function. - -The tree is automatically 'balanced' as new key/value pairs are added, -so that the distance from the root to every leaf is as small as possible. -The cost of maintaining a balanced tree while inserting new key/value -result in a O(n log(n)) operation where most of the other operations -are O(log(n)). +Inserts a new key and value into a #GTree as g_tree_insert_node() does, +only this function does not return the inserted or set node. @@ -27533,15 +27510,8 @@ are O(log(n)). - Inserts a new key and value into a #GTree similar to g_tree_insert(). -The difference is that if the key already exists in the #GTree, it gets -replaced by the new key. If you supplied a @value_destroy_func when -creating the #GTree, the old value is freed using that function. If you -supplied a @key_destroy_func when creating the #GTree, the old key is -freed using that function. - -The tree is automatically 'balanced' as new key/value pairs are added, -so that the distance from the root to every leaf is as small as possible. + Inserts a new key and value into a #GTree as g_tree_replace_node() does, +only this function does not return the inserted or set node. @@ -28657,11 +28627,12 @@ g_filename_to_uri() if you want to properly convert between Note that there is no `g_uri_equal ()` function, because comparing URIs usefully requires scheme-specific knowledge that #GUri does -not have. For example, `http://example.com/` and -`http://EXAMPLE.COM:80` have exactly the same meaning according -to the HTTP specification, and `data:,foo` and -`data:;base64,Zm9v` resolve to the same thing according to the -`data:` URI specification. +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. +For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same +thing according to the `data:` URI specification which GLib does not +handle. Gets @uri's authentication parameters, which may contain `%`-encoding, depending on the flags with which @uri was created. @@ -28718,7 +28689,7 @@ that address, without the brackets around it that are necessary in the string form of the URI. Note that in this case there may also be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or `fe80::1234%``25em1` if the string is still encoded). - + @uri's host. @@ -28838,7 +28809,7 @@ the flags with which @uri was created. If the result is not a valid absolute URI, it will be discarded, and an error returned. - a new #GUri. + a new #GUri, or NULL on error. @@ -28883,8 +28854,8 @@ If @uri might contain sensitive details, such as authentication parameters, or private data in its query string, and the returned string is going to be logged, then consider using g_uri_to_string_partial() to redact parts. - a string representing @uri, which the caller - must free. + a string representing @uri, + which the caller must free. @@ -28898,8 +28869,8 @@ logged, then consider using g_uri_to_string_partial() to redact parts. Returns a string representing @uri, subject to the options in @flags. See g_uri_to_string() and #GUriHideFlags for more details. - a string representing @uri, which the caller - must free. + a string representing + @uri, which the caller must free. @@ -29046,8 +29017,8 @@ portions of a URI. Though technically incorrect, this will also allow escaping nul bytes as `%``00`. - an escaped version of @unescaped. The returned - string should be freed when no longer needed. + an escaped version of @unescaped. + The returned string should be freed when no longer needed. @@ -29078,8 +29049,8 @@ they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI. - an escaped version of @unescaped. The returned string -should be freed when no longer needed. + an escaped version of @unescaped. The +returned string should be freed when no longer needed. @@ -29259,7 +29230,7 @@ discarding any comments. The URIs are not validated. valid [absolute URI][relative-absolute-uris], it will be discarded, and an error returned. - a new #GUri. + a new #GUri, or NULL on error. @@ -29299,9 +29270,9 @@ the returned attributes. If @params cannot be parsed (for example, it contains two @separators characters in a row), then @error is set and %NULL is returned. - A hash table of - attribute/value pairs, with both names and values fully-decoded; or %NULL - on error. + + A hash table of attribute/value pairs, with both names and values + fully-decoded; or %NULL on error. @@ -29384,7 +29355,8 @@ discarded, and an error returned. (If @base_uri_string is %NULL, this just returns @uri_ref, or %NULL if @uri_ref is invalid or not absolute.) - the resolved URI string. + the resolved URI string, +or NULL on error. @@ -29593,9 +29565,9 @@ returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - an unescaped version of @escaped_string or %NULL on - error (if decoding failed, using %G_URI_ERROR_FAILED error code). The - returned #GBytes should be unreffed when no longer needed. + an unescaped version of @escaped_string + or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error + code). The returned #GBytes should be unreffed when no longer needed. @@ -29626,11 +29598,11 @@ escaped path element, which might confuse pathname handling. Note: `NUL` byte is not accepted in the output, in contrast to g_uri_unescape_bytes(). - - an unescaped version of @escaped_string or %NULL on error. -The returned string should be freed when no longer needed. As a -special case if %NULL is given for @escaped_string, this function -will return %NULL. + + an unescaped version of @escaped_string, +or %NULL on error. The returned string should be freed when no longer +needed. As a special case if %NULL is given for @escaped_string, this +function will return %NULL. @@ -29658,9 +29630,9 @@ character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - - an unescaped version of @escaped_string. The returned string -should be freed when no longer needed. + + an unescaped version of @escaped_string. +The returned string should be freed when no longer needed. @@ -30068,7 +30040,7 @@ 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 DBus, or when saving settings using GSettings. +sending method parameters in D-Bus, or when saving settings using GSettings. 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. @@ -33734,7 +33706,7 @@ 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 -are of the same form as those found in DBus. Note, however: D-Bus +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" are a concatenation of the strings of the type of each argument in a @@ -36097,7 +36069,10 @@ Think of this operation as an atomic version of This call acts as a full compiler and hardware memory barrier. Before version 2.30, this function did not return a value -(but g_atomic_int_exchange_and_add() did, and had the same meaning). +(but g_atomic_int_exchange_and_add() did, and had the same meaning). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. the value of @atomic before the add, signed @@ -36120,7 +36095,10 @@ storing the result back in @atomic. This call acts as a full compiler and hardware memory barrier. Think of this operation as an atomic version of -`{ tmp = *atomic; *atomic &= val; return tmp; }`. +`{ tmp = *atomic; *atomic &= val; return tmp; }`. + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. the value of @atomic before the operation, unsigned @@ -36145,7 +36123,10 @@ This compare and exchange is done atomically. Think of this operation as an atomic version of `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. -This call acts as a full compiler and hardware memory barrier. +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`. %TRUE if the exchange took place @@ -36171,7 +36152,10 @@ This call acts as a full compiler and hardware memory barrier. Think of this operation as an atomic version of `{ *atomic -= 1; return (*atomic == 0); }`. -This call acts as a full compiler and hardware memory barrier. +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`. %TRUE if the resultant value is zero @@ -36207,7 +36191,10 @@ compatibility reasons. Don't use this function in new code. Gets the current value of @atomic. This call acts as a full compiler and hardware -memory barrier (before the get). +memory barrier (before the get). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. the value of the integer @@ -36224,7 +36211,10 @@ memory barrier (before the get). Think of this operation as an atomic version of `{ *atomic += 1; }`. -This call acts as a full compiler and hardware memory barrier. +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`. @@ -36242,7 +36232,10 @@ storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic |= val; return tmp; }`. -This call acts as a full compiler and hardware memory barrier. +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 value of @atomic before the operation, unsigned @@ -36262,7 +36255,10 @@ This call acts as a full compiler and hardware memory barrier. Sets the value of @atomic to @newval. This call acts as a full compiler and hardware -memory barrier (after the set). +memory barrier (after the set). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. @@ -36284,7 +36280,10 @@ storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic ^= val; return tmp; }`. -This call acts as a full compiler and hardware memory barrier. +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 value of @atomic before the operation, unsigned @@ -36343,7 +36342,10 @@ perform the operations normally and then release the lock. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic += val; return tmp; }`. -This call acts as a full compiler and hardware memory barrier. +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 value of @atomic before the add, signed @@ -36366,7 +36368,10 @@ storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic &= val; return tmp; }`. -This call acts as a full compiler and hardware memory barrier. +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 value of @atomic before the operation, unsigned @@ -36391,7 +36396,10 @@ This compare and exchange is done atomically. Think of this operation as an atomic version of `{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }`. -This call acts as a full compiler and hardware memory barrier. +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`. %TRUE if the exchange took place @@ -36415,7 +36423,10 @@ This call acts as a full compiler and hardware memory barrier. Gets the current value of @atomic. This call acts as a full compiler and hardware -memory barrier (before the get). +memory barrier (before the get). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. the value of the pointer @@ -36434,7 +36445,10 @@ storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic |= val; return tmp; }`. -This call acts as a full compiler and hardware memory barrier. +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 value of @atomic before the operation, unsigned @@ -36454,7 +36468,10 @@ This call acts as a full compiler and hardware memory barrier. Sets the value of @atomic to @newval. This call acts as a full compiler and hardware -memory barrier (after the set). +memory barrier (after the set). + +While @atomic has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. @@ -36476,7 +36493,10 @@ storing the result back in @atomic. Think of this operation as an atomic version of `{ tmp = *atomic; *atomic ^= val; return tmp; }`. -This call acts as a full compiler and hardware memory barrier. +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 value of @atomic before the operation, unsigned @@ -37309,7 +37329,11 @@ together. Create byte array containing the data. The data will be owned by the array -and will be freed with g_free(), i.e. it could be allocated using g_strdup(). +and will be freed with g_free(), i.e. it could be allocated using g_strdup(). + +Do not use it if @len is greater than %G_MAXUINT. #GByteArray +stores the length of its data in #guint, which may be shorter than +#gsize. a new #GByteArray @@ -37652,7 +37676,7 @@ due to limitations in POSIX process interfaces: * the application must not wait for @pid to exit by any other mechanism, including `waitpid(pid, ...)` or a second child-watch source for the same @pid -* the application must not ignore SIGCHILD +* the application must not ignore `SIGCHLD` If any of those conditions are not met, this and related APIs will not work correctly. This can often be diagnosed via a GLib warning @@ -37799,9 +37823,11 @@ convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free(). The hexadecimal string returned will be in lower case. - - the digest of the binary data as a string in hexadecimal. - The returned string should be freed with g_free() when done using it. + + the digest of the binary data as a + string in hexadecimal, or %NULL if g_checksum_new() fails for + @checksum_type. The returned string should be freed with g_free() when + done using it. @@ -37821,9 +37847,11 @@ convenience wrapper for g_checksum_new(), g_checksum_get_string() and g_checksum_free(). The hexadecimal string returned will be in lower case. - - the digest of the binary data as a string in hexadecimal. - The returned string should be freed with g_free() when done using it. + + the digest of the binary data as a + string in hexadecimal, or %NULL if g_checksum_new() fails for + @checksum_type. The returned string should be freed with g_free() when + done using it. @@ -37847,8 +37875,9 @@ The hexadecimal string returned will be in lower case. Computes the checksum of a string. The hexadecimal string returned will be in lower case. - - the checksum as a hexadecimal string. The returned string + + the checksum as a hexadecimal string, + or %NULL if g_checksum_new() fails for @checksum_type. The returned string should be freed with g_free() when done using it. @@ -39088,58 +39117,6 @@ where the C library only complies to C89. - - A comparison function for #GDateTimes that is suitable -as a #GCompareFunc. Both #GDateTimes must be non-%NULL. - - -1, 0 or 1 if @dt1 is less than, equal to or greater - than @dt2. - - - - - first #GDateTime to compare - - - - second #GDateTime to compare - - - - - - Checks to see if @dt1 and @dt2 are equal. - -Equal here means that they represent the same moment after converting -them to the same time zone. - - %TRUE if @dt1 and @dt2 are equal - - - - - a #GDateTime - - - - a #GDateTime - - - - - - Hashes @datetime into a #guint, suitable for use within #GHashTable. - - a #guint containing the hash - - - - - a #GDateTime - - - - Returns %TRUE if the day of the month is valid (a day is valid if it's between 1 and 31 inclusive). @@ -39886,14 +39863,14 @@ 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 "...". + 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 +- 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 +- 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. @@ -39907,11 +39884,13 @@ Summary of rules for use of #GError: - 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 +- 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 + 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(). @@ -39919,12 +39898,12 @@ Summary of rules for use of #GError: - 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, + 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. + #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 deprecated because of this. If %FALSE is returned, the error must + 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. @@ -39941,7 +39920,122 @@ Summary of rules for use of #GError: - 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);`). + `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) + +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; +} + +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; +} + +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; + } + + return send_one (request, error); +} +]| + +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. Gets a #GFileError constant based on the passed-in @err_no. @@ -40056,7 +40150,7 @@ for filenames. Use g_filename_to_utf8() to convert it to UTF-8. Writes all of @contents to a file named @filename. This is a convenience -wrapper around calling g_file_set_contents() with `flags` set to +wrapper around calling g_file_set_contents_full() with `flags` set to `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and `mode` set to `0666`. @@ -40993,7 +41087,10 @@ This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the CSIDL_COMMON_APPDATA folder. This information will not roam and is available -to anyone using the computer. +to anyone using the computer. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime. a %NULL-terminated array of strings owned by GLib that must not be @@ -41034,7 +41131,10 @@ folder's name is "bin", its parent is used, otherwise the folder itself. Note that on Windows the returned list can vary depending on where -this function is called. +this function is called. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime. a %NULL-terminated array of strings owned by GLib that must not be @@ -41077,7 +41177,10 @@ On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is de If `XDG_CACHE_HOME` is undefined, the directory that serves as a common repository for temporary Internet files is used instead. A typical path is `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`. -See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache). +See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache). + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. @@ -41098,7 +41201,10 @@ If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the [documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). Note that in this case on Windows it will be the same -as what g_get_user_data_dir() returns. +as what g_get_user_data_dir() returns. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. @@ -41119,7 +41225,10 @@ is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the [documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). Note that in this case on Windows it will be the same -as what g_get_user_config_dir() returns. +as what g_get_user_config_dir() returns. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. @@ -41146,7 +41255,10 @@ in the This is the directory specified in the `XDG_RUNTIME_DIR` environment variable. In the case that this variable is not set, we return the value of -g_get_user_cache_dir(), after verifying that it exists. +g_get_user_cache_dir(), after verifying that it exists. + +The return value is cached and modifying it at runtime is not supported, as +it’s not thread-safe to modify environment variables at runtime. a string owned by GLib that must not be modified or freed. @@ -41212,6 +41324,19 @@ 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".) + + + #GStrvBuilder is a method of easily building dynamically sized +NULL-terminated string arrays. + +The following example shows how to build a two element array: + +|[<!-- language="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); +]| Most of GLib is intended to be portable; in contrast, this set of @@ -41845,9 +41970,9 @@ g_hostname_is_ascii_encoded() to both return %TRUE for a name. Converts @hostname to its canonical ASCII form; an ASCII-only string containing no uppercase letters and not ending with a trailing dot. - - an ASCII hostname, which must be freed, or %NULL if -@hostname is in some way invalid. + + an ASCII hostname, which must be freed, + or %NULL if @hostname is in some way invalid. @@ -41865,9 +41990,9 @@ and not ending with a trailing dot. Of course if @hostname is not an internationalized hostname, then the canonical presentation form will be entirely ASCII. - - a UTF-8 hostname, which must be freed, or %NULL if -@hostname is in some way invalid. + + a UTF-8 hostname, which must be freed, + or %NULL if @hostname is in some way invalid. @@ -42822,7 +42947,8 @@ environment variables: 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. +the rest, unless stderr was requested by +g_log_writer_default_set_use_stderr(). This has no effect if structured logging is enabled; see [Using Structured Logging][using-structured-logging]. @@ -43283,7 +43409,11 @@ if no other is set using g_log_set_writer_func(). As with g_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. + +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 +up to the writer function to determine which log messages are fatal. %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise @@ -43411,7 +43541,9 @@ defined, but will always return %G_LOG_WRITER_UNHANDLED. 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 -are sent to `stdout`; all other log levels are sent to `stderr`. Only fields +are sent to `stdout`, or to `stderr` if requested by +g_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. @@ -43656,7 +43788,7 @@ always return %NULL if you are running in the default thread.) If you need to hold a reference on the context, use g_main_context_ref_thread_default() instead. - + the thread-default #GMainContext, or %NULL if the thread-default context is the global default context. @@ -43677,7 +43809,7 @@ is the global default context, this will return that #GMainContext Returns the currently firing source for this thread. - + The currently firing source or %NULL. @@ -44095,9 +44227,12 @@ profiling tools instead - + Allocates @byte_size bytes of memory, and copies @byte_size bytes into it from @mem. If @mem is %NULL it returns %NULL. + Use g_memdup2() instead, as it accepts a #gsize argument + for @byte_size, avoiding the possibility of overflow in a #gsize → #guint + conversion a pointer to the newly-allocated copy of the memory, or %NULL if @mem is %NULL. @@ -44325,7 +44460,8 @@ are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to 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. +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} @@ -44845,7 +44981,10 @@ like this: } // use initialization_value here -]| +]| + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. %TRUE if the initialization section should be entered, %FALSE and blocks otherwise @@ -44864,7 +45003,10 @@ like this: 0-initialized initialization variable, and an initialization value other than 0. Sets the variable to the initialization value, and releases concurrent threads blocking in g_once_init_enter() on this -initialization variable. +initialization variable. + +While @location has a `volatile` qualifier, this is a historical artifact and +the pointer passed to it should not be `volatile`. @@ -47812,24 +47954,8 @@ are different concepts on Windows. - Identical to g_spawn_async_with_pipes() but instead of -creating pipes for the stdin/stdout/stderr, you can pass existing -file descriptors into this function through the @stdin_fd, -@stdout_fd and @stderr_fd parameters. The following @flags -also have their behaviour slightly tweaked as a result: - -%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output -will be discarded, instead of going to the same location as the parent's -standard output. If you use this flag, @standard_output must be -1. -%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error -will be discarded, instead of going to the same location as the parent's -standard error. If you use this flag, @standard_error must be -1. -%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's -standard input (by default, the child's standard input is attached to -/dev/null). If you use this flag, @standard_input must be -1. - -It is valid to pass the same fd in multiple parameters (e.g. you can pass -a single fd for both stdout and stderr). + Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, +so no FD assignments are used. %TRUE on success, %FALSE if an error was set @@ -47868,186 +47994,22 @@ a single fd for both stdout and stderr). - file descriptor to use for child's stdin, or -1 + file descriptor to use for child's stdin, or `-1` - file descriptor to use for child's stdout, or -1 + file descriptor to use for child's stdout, or `-1` - file descriptor to use for child's stderr, or -1 + file descriptor to use for child's stderr, or `-1` - Executes a child program asynchronously (your program will not -block waiting for the child to exit). The child program is -specified by the only argument that must be provided, @argv. -@argv should be a %NULL-terminated array of strings, to be passed -as the argument vector for the child. The first string in @argv -is of course the name of the program to execute. By default, the -name of the program must be a full path. If @flags contains the -%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is -used to search for the executable. If @flags contains the -%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from -@envp is used to search for the executable. If both the -%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags -are set, the `PATH` variable from @envp takes precedence over -the environment variable. - -If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not -used, then the program will be run from the current directory (or -@working_directory, if specified); this might be unexpected or even -dangerous in some cases when the current directory is world-writable. - -On Windows, note that all the string or string vector arguments to -this function and the other g_spawn*() functions are in UTF-8, the -GLib file name encoding. Unicode characters that are not part of -the system codepage passed in these arguments will be correctly -available in the spawned program only if it uses wide character API -to retrieve its command line. For C programs built with Microsoft's -tools it is enough to make the program have a wmain() instead of -main(). wmain() has a wide character argument vector as parameter. - -At least currently, mingw doesn't support wmain(), so if you use -mingw to develop the spawned program, it should call -g_win32_get_command_line() to get arguments in UTF-8. - -On Windows the low-level child process creation API CreateProcess() -doesn't use argument vectors, but a command line. The C runtime -library's spawn*() family of functions (which g_spawn_async_with_pipes() -eventually calls) paste the argument vector elements together into -a command line, and the C runtime startup code does a corresponding -reconstruction of an argument vector from the command line, to be -passed to main(). Complications arise when you have argument vector -elements that contain spaces or double quotes. The `spawn*()` functions -don't do any quoting or escaping, but on the other hand the startup -code does do unquoting and unescaping in order to enable receiving -arguments with embedded spaces or double quotes. To work around this -asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on -argument vector elements that need it before calling the C runtime -spawn() function. - -The returned @child_pid on Windows is a handle to the child -process, not its identifier. Process handles and process -identifiers are different concepts on Windows. - -@envp is a %NULL-terminated array of strings, where each string -has the form `KEY=VALUE`. This will become the child's environment. -If @envp is %NULL, the child inherits its parent's environment. - -@flags should be the bitwise OR of any flags you want to affect the -function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the -child will not automatically be reaped; you must use a child watch -(g_child_watch_add()) to be notified about the death of the child process, -otherwise it will stay around as a zombie process until this process exits. -Eventually you must call g_spawn_close_pid() on the @child_pid, in order to -free resources which may be associated with the child process. (On Unix, -using a child watch is equivalent to calling waitpid() or handling -the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid() -is equivalent to calling CloseHandle() on the process handle returned -in @child_pid). See g_child_watch_add(). - -Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically -closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that -other open file descriptors will be inherited by the child; otherwise all -descriptors except stdin/stdout/stderr will be closed before calling exec() -in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an -absolute path, it will be looked for in the `PATH` environment -variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an -absolute path, it will be looked for in the `PATH` variable from -@envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP -are used, the value from @envp takes precedence over the environment. -%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output -will be discarded, instead of going to the same location as the parent's -standard output. If you use this flag, @standard_output must be %NULL. -%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error -will be discarded, instead of going to the same location as the parent's -standard error. If you use this flag, @standard_error must be %NULL. -%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's -standard input (by default, the child's standard input is attached to -`/dev/null`). If you use this flag, @standard_input must be %NULL. -%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is -the file to execute, while the remaining elements are the actual -argument vector to pass to the file. Normally g_spawn_async_with_pipes() -uses @argv[0] as the file to execute, and passes all of @argv to the child. - -@child_setup and @user_data are a function and user data. On POSIX -platforms, the function is called in the child after GLib has -performed all the setup it plans to perform (including creating -pipes, closing file descriptors, etc.) but before calling exec(). -That is, @child_setup is called just before calling exec() in the -child. Obviously actions taken in this function will only affect -the child, not the parent. - -On Windows, there is no separate fork() and exec() functionality. -Child processes are created and run with a single API call, -CreateProcess(). There is no sensible thing @child_setup -could be used for on Windows so it is ignored and not called. - -If non-%NULL, @child_pid will on Unix be filled with the child's -process ID. You can use the process ID to send signals to the child, -or to use g_child_watch_add() (or waitpid()) if you specified the -%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be -filled with a handle to the child process only if you specified the -%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child -process using the Win32 API, for example wait for its termination -with the WaitFor*() functions, or examine its exit code with -GetExitCodeProcess(). You should close the handle with CloseHandle() -or g_spawn_close_pid() when you no longer need it. - -If non-%NULL, the @standard_input, @standard_output, @standard_error -locations will be filled with file descriptors for writing to the child's -standard input or reading from its standard output or standard error. -The caller of g_spawn_async_with_pipes() must close these file descriptors -when they are no longer in use. If these parameters are %NULL, the -corresponding pipe won't be created. - -If @standard_input is %NULL, the child's standard input is attached to -`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set. - -If @standard_error is NULL, the child's standard error goes to the same -location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL -is set. - -If @standard_output is NULL, the child's standard output goes to the same -location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL -is set. - -@error can be %NULL to ignore errors, or non-%NULL to report errors. -If an error is set, the function returns %FALSE. Errors are reported -even if they occur in the child (for example if the executable in -@argv[0] is not found). Typically the `message` field of returned -errors should be displayed to users. Possible errors are those from -the #G_SPAWN_ERROR domain. - -If an error occurs, @child_pid, @standard_input, @standard_output, -and @standard_error will not be filled with valid values. - -If @child_pid is not %NULL and an error does not occur then the returned -process reference must be closed using g_spawn_close_pid(). - -On modern UNIX platforms, GLib can use an efficient process launching -codepath driven internally by posix_spawn(). This has the advantage of -avoiding the fork-time performance costs of cloning the parent process -address space, and avoiding associated memory overcommit checks that are -not relevant in the context of immediately executing a distinct process. -This optimized codepath will be used provided that the following conditions -are met: - -1. %G_SPAWN_DO_NOT_REAP_CHILD is set -2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set -3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set -4. @working_directory is %NULL -5. @child_setup is %NULL -6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. - -If you are writing a GTK+ application, and the program you are spawning is a -graphical application too, then to ensure that the spawned program opens its -windows on the right screen, you may want to use #GdkAppLaunchContext, -#GAppLaunchContext, or set the %DISPLAY environment variable. + Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, +so no FD assignments are used. %TRUE on success, %FALSE if an error was set @@ -49405,7 +49367,8 @@ to @haystack_len. - the maximum length of @haystack + the maximum length of @haystack in bytes. A length of -1 + can be used to mean "search the entire string", like g_strrstr(). @@ -49529,13 +49492,12 @@ to @haystack_len. - a string + a nul-terminated string - the maximum length of @haystack. Note that -1 is - a valid length, if @haystack is nul-terminated, meaning it will - search through the whole string. + the maximum length of @haystack in bytes. A length of -1 + can be used to mean "search the entire string", like `strstr()`. @@ -53153,8 +53115,8 @@ portions of a URI. Though technically incorrect, this will also allow escaping nul bytes as `%``00`. - an escaped version of @unescaped. The returned - string should be freed when no longer needed. + an escaped version of @unescaped. + The returned string should be freed when no longer needed. @@ -53185,8 +53147,8 @@ they are not escaped. This is useful for the "reserved" characters in the URI specification, since those are allowed unescaped in some portions of a URI. - an escaped version of @unescaped. The returned string -should be freed when no longer needed. + an escaped version of @unescaped. The +returned string should be freed when no longer needed. @@ -53366,7 +53328,7 @@ discarding any comments. The URIs are not validated. valid [absolute URI][relative-absolute-uris], it will be discarded, and an error returned. - a new #GUri. + a new #GUri, or NULL on error. @@ -53406,9 +53368,9 @@ the returned attributes. If @params cannot be parsed (for example, it contains two @separators characters in a row), then @error is set and %NULL is returned. - A hash table of - attribute/value pairs, with both names and values fully-decoded; or %NULL - on error. + + A hash table of attribute/value pairs, with both names and values + fully-decoded; or %NULL on error. @@ -53491,7 +53453,8 @@ discarded, and an error returned. (If @base_uri_string is %NULL, this just returns @uri_ref, or %NULL if @uri_ref is invalid or not absolute.) - the resolved URI string. + the resolved URI string, +or NULL on error. @@ -53700,9 +53663,9 @@ returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - an unescaped version of @escaped_string or %NULL on - error (if decoding failed, using %G_URI_ERROR_FAILED error code). The - returned #GBytes should be unreffed when no longer needed. + an unescaped version of @escaped_string + or %NULL on error (if decoding failed, using %G_URI_ERROR_FAILED error + code). The returned #GBytes should be unreffed when no longer needed. @@ -53733,11 +53696,11 @@ escaped path element, which might confuse pathname handling. Note: `NUL` byte is not accepted in the output, in contrast to g_uri_unescape_bytes(). - - an unescaped version of @escaped_string or %NULL on error. -The returned string should be freed when no longer needed. As a -special case if %NULL is given for @escaped_string, this function -will return %NULL. + + an unescaped version of @escaped_string, +or %NULL on error. The returned string should be freed when no longer +needed. As a special case if %NULL is given for @escaped_string, this +function will return %NULL. @@ -53765,9 +53728,9 @@ character appears as an escaped character in @escaped_string, then that is an error and %NULL will be returned. This is useful if you want to avoid for instance having a slash being expanded in an escaped path element, which might confuse pathname handling. - - an unescaped version of @escaped_string. The returned string -should be freed when no longer needed. + + an unescaped version of @escaped_string. +The returned string should be freed when no longer needed. @@ -54995,7 +54958,7 @@ the Single Unix Specification. a standard printf() format string, but notice - string precision pitfalls][string-precision] + [string precision pitfalls][string-precision] diff --git a/GObject-2.0.gir b/GObject-2.0.gir index 0e61d65..edaf7b3 100644 --- a/GObject-2.0.gir +++ b/GObject-2.0.gir @@ -238,10 +238,21 @@ binding, source, and target instances to drop. - - Retrieves the #GObject instance used as the source of the binding. - - the source #GObject + + Retrieves the #GObject instance used as the source of the binding. + +A #GBinding can outlive the source #GObject as the binding does not hold a +strong reference to the source. If the source is destroyed before the +binding then this function will return %NULL. + +Use g_binding_dup_source() if the source or binding are used from different +threads as otherwise the pointer returned from this function might become +invalid if the source is finalized from another thread in the meantime. + Use g_binding_dup_source() for a safer version of this +function. + + the source #GObject, or %NULL if the + source does not exist any more. @@ -265,10 +276,21 @@ of the binding. - - Retrieves the #GObject instance used as the target of the binding. - - the target #GObject + + Retrieves the #GObject instance used as the target of the binding. + +A #GBinding can outlive the target #GObject as the binding does not hold a +strong reference to the target. If the target is destroyed before the +binding then this function will return %NULL. + +Use g_binding_dup_target() if the target or binding are used from different +threads as otherwise the pointer returned from this function might become +invalid if the target is finalized from another thread in the meantime. + Use g_binding_dup_target() for a safer version of this +function. + + the target #GObject, or %NULL if the + target does not exist any more. @@ -297,9 +319,13 @@ of the binding. property expressed by @binding. This function will release the reference that is being held on -the @binding instance; if you want to hold on to the #GBinding instance -after calling g_binding_unbind(), you will need to hold a reference -to it. +the @binding instance if the binding is still bound; if you want to hold on +to the #GBinding instance after calling g_binding_unbind(), you will need +to hold a reference to it. + +Note however that this function does not take ownership of @binding, it +only unrefs the reference that was initially created by +g_object_bind_property() and is owned by the binding. @@ -4984,6 +5010,13 @@ The binding will automatically be removed when either the @source or the @source and the @target you can just call g_object_unref() on the returned #GBinding instance. +Removing the binding by calling g_object_unref() on it must only be done if +the binding, @source and @target are only used from a single thread and it +is clear that both @source and @target outlive the binding. Especially it +is not safe to rely on this if the binding, @source or @target can be +finalized from different threads. Keep another reference to the binding and +use g_binding_unbind() instead to be on the safe side. + A #GObject can have multiple bindings. the #GBinding instance representing the @@ -6133,7 +6166,7 @@ use this @object as closure data. Adds a weak reference callback to an object. Weak references are -used for notification when an object is finalized. They are called +used for notification when an object is disposed. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive). @@ -7049,7 +7082,8 @@ for use as a label for the property in a property editor, and the @blurb, which should be a somewhat longer description, suitable for e.g. a tooltip. The @nick and @blurb should ideally be localized. - a newly allocated #GParamSpec instance + (transfer floating): a newly allocated + #GParamSpec instance, which is initially floating @@ -7147,7 +7181,7 @@ the rules for valid names. Get the short description of a #GParamSpec. - + the short description of @pspec. @@ -7240,7 +7274,7 @@ type while preserving all the properties from the parent type. Redirection is established by creating a property of type #GParamSpecOverride. See g_object_class_override_property() for an example of the use of this capability. - + paramspec to which requests on this paramspec should be redirected, or %NULL if none. @@ -7254,7 +7288,7 @@ for an example of the use of this capability. Increments the reference count of @pspec. - + the #GParamSpec that was passed into this function @@ -7267,7 +7301,7 @@ for an example of the use of this capability. Convenience function to ref and sink a #GParamSpec. - + the #GParamSpec that was passed into this function @@ -7325,7 +7359,7 @@ g_param_spec_set_qdata() with the same @quark. an opaque user data pointer - + function to invoke with @data as argument, when @data needs to be freed @@ -7794,7 +7828,7 @@ the pool. Looks up a #GParamSpec in the pool. - + The found #GParamSpec, or %NULL if no matching #GParamSpec was found. @@ -7835,14 +7869,14 @@ matching #GParamSpec was found. - + Creates a new #GParamSpecPool. If @type_prefixing is %TRUE, lookups in the newly created pool will allow to specify the owner as a colon-separated prefix of the property name, like "GtkContainer:border-width". This feature is deprecated, so you should always set @type_prefixing to %FALSE. - + a newly allocated #GParamSpecPool. @@ -9716,7 +9750,7 @@ function outside of the GObject type system itself. - the #GType of an instantiable type to which the interface + the #GType of an instantiatable type to which the interface is added @@ -10366,9 +10400,9 @@ its reference count. If the contents of the #GValue are %NULL, then Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. - - #GParamSpec content of @value, should be unreferenced when - no longer needed. + + #GParamSpec content of @value, should be + unreferenced when no longer needed. @@ -12825,8 +12859,8 @@ connected to. The @handler_id_ptr is then set to zero, which is never a valid ha If the handler ID is 0 then this function does nothing. -A macro is also included that allows this function to be used without -pointer casts. +There is also a macro version of this function so that the code +will be inlined. @@ -12836,7 +12870,8 @@ pointer casts. - The instance to remove the signal handler from. + The instance to remove the signal handler from. + This pointer may be %NULL or invalid, if the handler ID is zero. @@ -12902,7 +12937,7 @@ my_enum_complete_type_info (GTypePlugin *plugin, Returns the #GEnumValue for a value. - + the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration @@ -12920,7 +12955,7 @@ my_enum_complete_type_info (GTypePlugin *plugin, Looks up a #GEnumValue by name. - + the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name @@ -12939,7 +12974,7 @@ my_enum_complete_type_info (GTypePlugin *plugin, Looks up a #GEnumValue by nickname. - + the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname @@ -13055,7 +13090,7 @@ g_enum_complete_type_info() above. Returns the first #GFlagsValue which is set in @value. - + the first #GFlagsValue which is set in @value, or %NULL if none is set @@ -13073,7 +13108,7 @@ g_enum_complete_type_info() above. Looks up a #GFlagsValue by name. - + the #GFlagsValue with name @name, or %NULL if there is no flag with that name @@ -13091,7 +13126,7 @@ g_enum_complete_type_info() above. Looks up a #GFlagsValue by nickname. - + the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname @@ -13296,8 +13331,8 @@ 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 [Instantiable classed types: -Objects][gtype-instantiable-classed]. +For the high-level concepts behind GObject, read [Instantiatable classed types: +Objects][gtype-instantiatable-classed]. ## Floating references # {#floating-ref} @@ -13892,24 +13927,6 @@ See g_param_spec_internal() for details on property names. - - Creates a new #GParamSpecPool. - -If @type_prefixing is %TRUE, lookups in the newly created pool will -allow to specify the owner as a colon-separated prefix of the -property name, like "GtkContainer:border-width". This feature is -deprecated, so you should always set @type_prefixing to %FALSE. - - a newly allocated #GParamSpecPool. - - - - - Whether the pool will support type-prefixed property names. - - - - Creates a new #GParamSpecString instance. @@ -14520,11 +14537,11 @@ for signals which don't have #G_SIGNAL_NO_HOOKS flag set. a #GSignalEmissionHook function. - + user data for @hook_func. - + a #GDestroyNotify for @hook_data. @@ -14695,11 +14712,11 @@ used. Specify @connect_flags if you need `..._after()` or the #GCallback to connect. - + data to pass to @c_handler calls. - + a #GClosureNotify for @data. @@ -14907,8 +14924,9 @@ specified signal returns a value, but may be ignored otherwise. Returns the invocation hint of the innermost signal emission of instance. - - the invocation hint of the innermost signal emission. + + the invocation hint of the innermost + signal emission, or %NULL if not found. @@ -14998,7 +15016,7 @@ If no handler was found, 0 is returned. The C closure callback of the handler (useless for non-C closures). - + The closure data of the handler's closure. @@ -15101,7 +15119,7 @@ otherwise. The C closure callback of the handlers (useless for non-C closures). - + The closure data of the handlers' closures. @@ -15185,7 +15203,7 @@ disconnected handlers otherwise. The C closure callback of the handlers (useless for non-C closures). - + The closure data of the handlers' closures. @@ -15244,7 +15262,7 @@ not currently blocked. The C closure callback of the handlers (useless for non-C closures). - + The closure data of the handlers' closures. @@ -15361,7 +15379,7 @@ See g_signal_new() for details on allowed signal names. Given the signal's identifier, finds its name. Two different signals may have the same name, if they have differing types. - + the signal name, or %NULL if the signal number was invalid. @@ -15423,11 +15441,11 @@ be used. not associate a class method slot with this signal. - + the accumulator for this signal; may be %NULL. - + user data for the @accumulator. @@ -15488,17 +15506,17 @@ 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. - + user data for the @accumulator. @@ -15549,15 +15567,15 @@ the marshaller for this signal. %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - + The closure to invoke on signal emission; may be %NULL. - + the accumulator for this signal; may be %NULL. - + user data for the @accumulator. @@ -15617,7 +15635,7 @@ the marshaller for this signal. the accumulator for this signal; may be %NULL - + user data for the @accumulator @@ -15636,9 +15654,9 @@ the marshaller for this signal. the length of @param_types - + an array of types, one for - each parameter + each parameter (may be %NULL if @n_params is zero) @@ -16086,7 +16104,7 @@ interfaces. - Adds @interface_type to the dynamic @instantiable_type. The information + Adds @interface_type to the dynamic @instance_type. The information contained in the #GTypePlugin structure pointed to by @plugin is used to manage the relationship. @@ -16094,7 +16112,7 @@ is used to manage the relationship. - #GType value of an instantiable type + #GType value of an instantiatable type @@ -16108,7 +16126,7 @@ is used to manage the relationship. - Adds @interface_type to the static @instantiable_type. + Adds @interface_type to the static @instance_type. The information contained in the #GInterfaceInfo structure pointed to by @info is used to manage the relationship. @@ -16116,7 +16134,7 @@ pointed to by @info is used to manage the relationship. - #GType value of an instantiable type + #GType value of an instantiatable type @@ -16715,11 +16733,11 @@ whether @type conforms to it. - type to check anchestry for + type to check ancestry for - possible anchestor of @type or interface that @type + possible ancestor of @type or interface that @type could conform to @@ -16764,14 +16782,14 @@ not be passed in and will most likely lead to a crash. Given a @leaf_type and a @root_type which is contained in its -anchestry, return the type that @root_type is the immediate parent +ancestry, return the type that @root_type is the immediate parent of. In other words, this function determines the type that is derived directly from @root_type which is also a base class of @leaf_type. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type. - immediate child of @root_type and anchestor of @leaf_type + immediate child of @root_type and ancestor of @leaf_type diff --git a/Gio-2.0.gir b/Gio-2.0.gir index b751cf4..6c39646 100644 --- a/Gio-2.0.gir +++ b/Gio-2.0.gir @@ -374,7 +374,7 @@ given by g_action_get_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required. - + the current state of the action @@ -544,7 +544,7 @@ given by g_action_get_state_type(). The return value (if non-%NULL) should be freed with g_variant_unref() when it is no longer required. - + the current state of the action @@ -840,7 +840,34 @@ This function should only be called by #GActionGroup implementations. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no parameters then @parameter must be %NULL. See -g_action_group_get_action_parameter_type(). +g_action_group_get_action_parameter_type(). + +If the #GActionGroup implementation supports asynchronous remote +activation over D-Bus, this call may return before the relevant +D-Bus traffic has been sent, or any replies have been received. In +order to block on such asynchronous activation calls, +g_dbus_connection_flush() should be called prior to the code, which +depends on the result of the action activation. Without flushing +the D-Bus connection, there is no guarantee that the action would +have been activated. + +The following code which runs in a remote app instance, shows an +example of a "quit" action being activated on the primary app +instance over D-Bus. Here g_dbus_connection_flush() is called +before `exit()`. Without g_dbus_connection_flush(), the "quit" action +may fail to be activated on the primary instance. + +|[<!-- language="C" --> +// call "quit" action on primary instance +g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); + +// make sure the action is activated now +g_dbus_connection_flush (...); + +g_debug ("application has been terminated. exiting."); + +exit (0); +]| @@ -1213,7 +1240,34 @@ This function should only be called by #GActionGroup implementations. If the action is expecting a parameter, then the correct type of parameter must be given as @parameter. If the action is expecting no parameters then @parameter must be %NULL. See -g_action_group_get_action_parameter_type(). +g_action_group_get_action_parameter_type(). + +If the #GActionGroup implementation supports asynchronous remote +activation over D-Bus, this call may return before the relevant +D-Bus traffic has been sent, or any replies have been received. In +order to block on such asynchronous activation calls, +g_dbus_connection_flush() should be called prior to the code, which +depends on the result of the action activation. Without flushing +the D-Bus connection, there is no guarantee that the action would +have been activated. + +The following code which runs in a remote app instance, shows an +example of a "quit" action being activated on the primary app +instance over D-Bus. Here g_dbus_connection_flush() is called +before `exit()`. Without g_dbus_connection_flush(), the "quit" action +may fail to be activated on the primary instance. + +|[<!-- language="C" --> +// call "quit" action on primary instance +g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL); + +// make sure the action is activated now +g_dbus_connection_flush (...); + +g_debug ("application has been terminated. exiting."); + +exit (0); +]| @@ -1925,7 +1979,7 @@ actions in the group - + the current state of the action @@ -2007,7 +2061,7 @@ The action map takes its own reference on @action. Looks up the action with the name @action_name in @action_map. If no such action exists, returns %NULL. - + a #GAction, or %NULL @@ -2128,7 +2182,7 @@ create_action_group (void) Looks up the action with the name @action_name in @action_map. If no such action exists, returns %NULL. - + a #GAction, or %NULL @@ -2169,7 +2223,7 @@ If no action of this name is in the map then nothing happens. - + a #GAction, or %NULL @@ -2575,7 +2629,7 @@ See g_app_info_can_delete(). Checks if two #GAppInfos are equal. -Note that the check <emphasis>may not</emphasis> compare each individual +Note that the check *may not* compare each individual field, and only does an identity check. In case detecting changes in the contents is needed, program code must additionally compare relevant fields. @@ -2593,19 +2647,24 @@ contents is needed, program code must additionally compare relevant fields. - - - + + Gets the commandline with which the application will be +started. + + a string containing the @appinfo's commandline, + or %NULL if this information is not available + + a #GAppInfo Gets a human-readable description of an installed application. - + a string containing a description of the application @appinfo, or %NULL if none. @@ -2632,19 +2691,23 @@ no display name is available. - + + Gets the executable's name for the installed application. - + a string containing the @appinfo's application +binaries name + + a #GAppInfo Gets the icon for the application. - + the default #GIcon for @appinfo or %NULL if there is no default icon. @@ -2664,7 +2727,7 @@ desktop file id from the xdg menu specification. Note that the returned ID may be %NULL, depending on how the @appinfo has been constructed. - + a string containing the application's ID. @@ -3037,7 +3100,7 @@ See g_app_info_can_delete(). Checks if two #GAppInfos are equal. -Note that the check <emphasis>may not</emphasis> compare each individual +Note that the check *may not* compare each individual field, and only does an identity check. In case detecting changes in the contents is needed, program code must additionally compare relevant fields. @@ -3058,7 +3121,7 @@ contents is needed, program code must additionally compare relevant fields. Gets the commandline with which the application will be started. - + a string containing the @appinfo's commandline, or %NULL if this information is not available @@ -3072,7 +3135,7 @@ started. Gets a human-readable description of an installed application. - + a string containing a description of the application @appinfo, or %NULL if none. @@ -3115,7 +3178,7 @@ binaries name Gets the icon for the application. - + the default #GIcon for @appinfo or %NULL if there is no default icon. @@ -3135,7 +3198,7 @@ desktop file id from the xdg menu specification. Note that the returned ID may be %NULL, depending on how the @appinfo has been constructed. - + a string containing the application's ID. @@ -3485,7 +3548,7 @@ list available applications. - + a string containing the application's ID. @@ -3513,7 +3576,7 @@ list available applications. - + a string containing a description of the application @appinfo, or %NULL if none. @@ -3529,10 +3592,13 @@ application @appinfo, or %NULL if none. - + a string containing the @appinfo's application +binaries name + + a #GAppInfo @@ -3540,7 +3606,7 @@ application @appinfo, or %NULL if none. - + the default #GIcon for @appinfo or %NULL if there is no default icon. @@ -3761,11 +3827,14 @@ if there is no default icon. - - + + a string containing the @appinfo's commandline, + or %NULL if this information is not available + + a #GAppInfo @@ -3932,7 +4001,7 @@ instead you instantiate a subclass of this, such as #GdkAppLaunchContext. Gets the display string for the @context. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. - + a display string for the display. @@ -3959,7 +4028,7 @@ application, by setting the `DISPLAY` environment variable. Startup notification IDs are defined in the [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - + a startup notification ID for the application, or %NULL if not supported. @@ -4018,7 +4087,7 @@ the application startup notification started in g_app_launch_context_get_startup Gets the display string for the @context. This is used to ensure new applications are started on the same display as the launching application, by setting the `DISPLAY` environment variable. - + a display string for the display. @@ -4064,7 +4133,7 @@ the form `KEY=VALUE`. Startup notification IDs are defined in the [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - + a startup notification ID for the application, or %NULL if not supported. @@ -4188,7 +4257,7 @@ platform-specific data about this launch. On UNIX, at least the - + a display string for the display. @@ -4212,7 +4281,7 @@ platform-specific data about this launch. On UNIX, at least the - + a startup notification ID for the application, or %NULL if not supported. @@ -4448,7 +4517,7 @@ the default when it is created. You can exercise more control over this by using g_application_set_default(). If there is no default application then %NULL is returned. - + the default application for this process, or %NULL @@ -4950,7 +5019,7 @@ finalized. Gets the unique identifier for @application. - + the identifier for @application, owned by @application @@ -4975,7 +5044,7 @@ normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See g_application_get_is_registered(). - + a #GDBusConnection, or %NULL @@ -5001,7 +5070,7 @@ normally be in use but we were unable to connect to the bus. This function must not be called before the application has been registered. See g_application_get_is_registered(). - + the object path, or %NULL @@ -6267,12 +6336,12 @@ The complete example can be found here: The #GInputStream can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available -on UNIX when using a DBus daemon capable of passing file descriptors. +on UNIX when using a D-Bus daemon capable of passing file descriptors. If stdin is not available then %NULL will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. - + a #GInputStream for stdin @@ -6485,12 +6554,12 @@ For local invocation, it will be %NULL. The #GInputStream can be used to read data passed to the standard input of the invoking process. This doesn't work on all platforms. Presently, it is only available -on UNIX when using a DBus daemon capable of passing file descriptors. +on UNIX when using a D-Bus daemon capable of passing file descriptors. If stdin is not available then %NULL will be returned. In the future, support may be expanded to other platforms. You must only call this function once per commandline invocation. - + a #GInputStream for stdin @@ -6513,7 +6582,7 @@ to invocation messages from other applications). The return value should not be modified or freed and is valid for as long as @cmdline exists. - + the value of the variable, or %NULL if unset or unsent @@ -6671,7 +6740,7 @@ contains private data only. - + a #GInputStream for stdin @@ -8366,10 +8435,13 @@ png) to be used as icon. - Creates a new icon for a bytes. + Creates a new icon for a bytes. + +This cannot fail, but loading and interpreting the bytes may fail later on +(for example, if g_loadable_icon_load() is called) if the image is invalid. a #GIcon for the given - @bytes, or %NULL on error. + @bytes. @@ -8382,7 +8454,7 @@ png) to be used as icon. Gets the #GBytes associated with the given @icon. - a #GBytes, or %NULL. + a #GBytes. @@ -9648,10 +9720,10 @@ It is a programming error (which will cause a warning to be logged) to use this method if there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. - The pointer to native credentials or %NULL if the -operation there is no #GCredentials support for the OS or if -@native_type isn't supported by the OS. Do not free the returned -data, it is owned by @credentials. + The pointer to native credentials or + %NULL if there is no #GCredentials support for the OS or if @native_type + isn't supported by the OS. Do not free the returned data, it is owned + by @credentials. @@ -9674,7 +9746,7 @@ OS or if the native credentials type does not contain information about the UNIX process ID (for example this is the case for %G_CREDENTIALS_TYPE_APPLE_XUCRED). - The UNIX process ID, or -1 if @error is set. + The UNIX process ID, or `-1` if @error is set. @@ -9692,7 +9764,7 @@ This operation can fail if #GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. - The UNIX user identifier or -1 if @error is set. + The UNIX user identifier or `-1` if @error is set. @@ -10153,7 +10225,7 @@ the memory used is freed. Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. - + The value or %NULL if not found. Do not free, it is owned by @annotations. @@ -10257,7 +10329,9 @@ By default, a #GDBusServer or server-side #GDBusConnection will accept connections from any successfully authenticated user (but not from anonymous connections using the `ANONYMOUS` mechanism). If you only want to allow D-Bus connections from processes owned by the same uid -as the server, you would use a signal handler like the following: +as the server, since GLib 2.68, you should use the +%G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag. It’s equivalent +to the following signal handler: |[<!-- language="C" --> static gboolean @@ -10453,8 +10527,8 @@ Here is an example for exporting a #GObject: Finishes an operation started with g_dbus_connection_new_for_address(). - a #GDBusConnection or %NULL if @error is set. Free with - g_object_unref(). + a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref(). @@ -10474,8 +10548,9 @@ which must be in the This constructor can only be used to initiate client-side connections - use g_dbus_connection_new_sync() if you need to act as the server. In particular, @flags cannot contain the -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. This is a synchronous failable constructor. See g_dbus_connection_new_for_address() for the asynchronous version. @@ -10483,8 +10558,8 @@ g_dbus_connection_new_for_address() for the asynchronous version. If @observer is not %NULL it may be used to control the authentication process. - a #GDBusConnection or %NULL if @error is set. Free with - g_object_unref(). + a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref(). @@ -10523,7 +10598,8 @@ authentication process. This is a synchronous failable constructor. See g_dbus_connection_new() for the asynchronous version. - a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + a #GDBusConnection or %NULL if @error is set. + Free with g_object_unref(). @@ -10613,8 +10689,9 @@ which must be in the This constructor can only be used to initiate client-side connections - use g_dbus_connection_new() if you need to act as the server. In particular, @flags cannot contain the -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER or -%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS flags. +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER, +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS or +%G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flags. When the operation is finished, @callback will be invoked. You can then call g_dbus_connection_new_for_address_finish() to get the result of @@ -10818,8 +10895,8 @@ the %G_DBUS_MESSAGE_FLAGS_NO_REPLY_EXPECTED flag set. Finishes an operation started with g_dbus_connection_call(). - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). + %NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref(). @@ -10871,8 +10948,8 @@ The calling thread is blocked until a reply is received. See g_dbus_connection_call() for the asynchronous version of this method. - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). + %NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref(). @@ -10924,6 +11001,18 @@ this method. Like g_dbus_connection_call() but also takes a #GUnixFDList object. +The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE +values in the body of the message. For example, if a message contains +two file descriptors, @fd_list would have length 2, and +`g_variant_new_handle (0)` and `g_variant_new_handle (1)` would appear +somewhere in the body of the message (not necessarily in that order!) +to represent the file descriptors at indexes 0 and 1 respectively. + +When designing D-Bus APIs that are intended to be interoperable, +please note that non-GDBus implementations of D-Bus can usually only +access file descriptors if they are referenced in this way by a +value of type %G_VARIANT_TYPE_HANDLE in the body of the message. + This method is only available on UNIX. @@ -10989,10 +11078,21 @@ This method is only available on UNIX. - Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). + Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). + +The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE +values in the body of the message. For example, +if g_variant_get_handle() returns 5, that is intended to be a reference +to the file descriptor that can be accessed by +`g_unix_fd_list_get (*out_fd_list, 5, ...)`. + +When designing D-Bus APIs that are intended to be interoperable, +please note that non-GDBus implementations of D-Bus can usually only +access file descriptors if they are referenced in this way by a +value of type %G_VARIANT_TYPE_HANDLE in the body of the message. - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). + %NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref(). @@ -11013,11 +11113,13 @@ This method is only available on UNIX. Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects. +See g_dbus_connection_call_with_unix_fd_list() and +g_dbus_connection_call_with_unix_fd_list_finish() for more details. This method is only available on UNIX. - %NULL if @error is set. Otherwise a #GVariant tuple with - return values. Free with g_variant_unref(). + %NULL if @error is set. Otherwise a non-floating + #GVariant tuple with return values. Free with g_variant_unref(). @@ -11569,7 +11671,7 @@ See this [server][gdbus-server] for an example of how to use this method. Version of g_dbus_connection_register_object() using closures instead of a #GDBusInterfaceVTable for easier binding in other languages. - 0 if @error is set, otherwise a registration id (never 0) + 0 if @error is set, otherwise a registration ID (never 0) that can be used with g_dbus_connection_unregister_object() . @@ -11636,8 +11738,8 @@ registration. See this [server][gdbus-subtree-server] for an example of how to use this method. - 0 if @error is set, otherwise a subtree registration id (never 0) -that can be used with g_dbus_connection_unregister_subtree() . + 0 if @error is set, otherwise a subtree registration ID (never 0) +that can be used with g_dbus_connection_unregister_subtree() @@ -11699,7 +11801,9 @@ Unless @flags contain the will be assigned by @connection and set on @message via g_dbus_message_set_serial(). If @out_serial is not %NULL, then the serial number used will be written to this location prior to -submitting the message to the underlying transport. +submitting the message to the underlying transport. While it has a `volatile` +qualifier, this is a historical artifact and the argument passed to it should +not be `volatile`. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @message is not well-formed, @@ -11744,7 +11848,9 @@ Unless @flags contain the will be assigned by @connection and set on @message via g_dbus_message_set_serial(). If @out_serial is not %NULL, then the serial number used will be written to this location prior to -submitting the message to the underlying transport. +submitting the message to the underlying transport. While it has a `volatile` +qualifier, this is a historical artifact and the argument passed to it should +not be `volatile`. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will @@ -11843,7 +11949,9 @@ Unless @flags contain the will be assigned by @connection and set on @message via g_dbus_message_set_serial(). If @out_serial is not %NULL, then the serial number used will be written to this location prior to -submitting the message to the underlying transport. +submitting the message to the underlying transport. While it has a `volatile` +qualifier, this is a historical artifact and the argument passed to it should +not be `volatile`. If @connection is closed then the operation will fail with %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will @@ -12180,7 +12288,7 @@ authenticating. If you are constructing a #GDBusConnection and pass %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the -#GDBusConnection:flags property then you MUST also set this +#GDBusConnection:flags property then you **must** also set this property to a valid guid. If you are constructing a #GDBusConnection and pass @@ -12424,7 +12532,8 @@ on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). This function is typically only used in object mappings to put a #GError on the wire. Regular applications should not use it. - A D-Bus error name (never %NULL). Free with g_free(). + A D-Bus error name (never %NULL). + Free with g_free(). @@ -12441,9 +12550,9 @@ This function is guaranteed to return a D-Bus error name for all #GErrors returned from functions handling remote method calls (e.g. g_dbus_connection_call_finish()) unless g_dbus_error_strip_remote_error() has been used on @error. - - an allocated string or %NULL if the D-Bus error name - could not be found. Free with g_free(). + + an allocated string or %NULL if the + D-Bus error name could not be found. Free with g_free(). @@ -12542,7 +12651,10 @@ exists. - Helper function for associating a #GError error domain with D-Bus error names. + Helper function for associating a #GError error domain with D-Bus error names. + +While @quark_volatile has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. @@ -12682,7 +12794,7 @@ on the service side (see #GDBusInterfaceSkeleton) and client side (see #GDBusProxy). Gets the #GDBusObject that @interface_ belongs to, if any. - + A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). @@ -12714,7 +12826,7 @@ implemented by @interface_. It is not safe to use the returned object if @interface_ or the returned object is being used from other threads. See g_dbus_interface_dup_object() for a thread-safe alternative. - + A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. @@ -12746,7 +12858,7 @@ Note that @interface_ will hold a weak reference to @object. Gets the #GDBusObject that @interface_ belongs to, if any. - + A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). @@ -12778,7 +12890,7 @@ implemented by @interface_. It is not safe to use the returned object if @interface_ or the returned object is being used from other threads. See g_dbus_interface_dup_object() for a thread-safe alternative. - + A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. @@ -12870,7 +12982,7 @@ Note that @interface_ will hold a weak reference to @object. - + A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. @@ -12902,7 +13014,7 @@ Note that @interface_ will hold a weak reference to @object. - + A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). @@ -13015,7 +13127,7 @@ method. The cost of this function is O(n) in number of methods unless g_dbus_interface_info_cache_build() has been used on @info. - + A #GDBusMethodInfo or %NULL if not found. Do not free, it is owned by @info. @@ -13035,7 +13147,7 @@ g_dbus_interface_info_cache_build() has been used on @info. The cost of this function is O(n) in number of properties unless g_dbus_interface_info_cache_build() has been used on @info. - + A #GDBusPropertyInfo or %NULL if not found. Do not free, it is owned by @info. @@ -13055,7 +13167,7 @@ g_dbus_interface_info_cache_build() has been used on @info. The cost of this function is O(n) in number of signals unless g_dbus_interface_info_cache_build() has been used on @info. - + A #GDBusSignalInfo or %NULL if not found. Do not free, it is owned by @info. @@ -13308,7 +13420,7 @@ for collapsing multiple property changes into one. Gets the first connection that @interface_ is exported on, if any. - + A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. @@ -13368,7 +13480,7 @@ implemented by @interface_. Gets the object path that @interface_ is exported on, if any. - + A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. @@ -13858,7 +13970,7 @@ and the per-process or system-wide open files limit is reached. Convenience to get the first item in the body of @message. - + The string item or %NULL if the first item in the body of @message is not a string. @@ -13872,7 +13984,7 @@ and the per-process or system-wide open files limit is reached. Gets the body of a message. - + A #GVariant or %NULL if the body is empty. Do not free, it is owned by @message. @@ -13899,7 +14011,7 @@ empty. Do not free, it is owned by @message. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_DESTINATION header field. - + The value. @@ -13912,7 +14024,7 @@ empty. Do not free, it is owned by @message. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_ERROR_NAME header field. - + The value. @@ -13976,7 +14088,7 @@ is a #guchar. Free with g_free(). Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_INTERFACE header field. - + The value. @@ -14004,7 +14116,7 @@ on the #GDBusMessage:locked property. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_MEMBER header field. - + The value. @@ -14043,7 +14155,7 @@ on the #GDBusMessage:locked property. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_PATH header field. - + The value. @@ -14069,7 +14181,7 @@ on the #GDBusMessage:locked property. Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SENDER header field. - + The value. @@ -14109,8 +14221,14 @@ on the #GDBusMessage:locked property. Gets the UNIX file descriptors associated with @message, if any. -This method is only available on UNIX. - +This method is only available on UNIX. + +The file descriptors normally correspond to %G_VARIANT_TYPE_HANDLE +values in the body of the message. For example, +if g_variant_get_handle() returns 5, that is intended to be a reference +to the file descriptor that can be accessed by +`g_unix_fd_list_get (list, 5, ...)`. + A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. @@ -14316,7 +14434,7 @@ If @body is floating, @message assumes ownership of @body. A #GDBusMessage. - + The value to set. @@ -14328,7 +14446,7 @@ If @body is floating, @message assumes ownership of @body. - + A #GDBusMessage. @@ -14387,7 +14505,7 @@ If @value is floating, @message assumes ownership of @value. A #GDBusMessage. - + The value to set. @@ -14403,7 +14521,7 @@ If @value is floating, @message assumes ownership of @value. A #GDBusMessage. - + The value to set. @@ -14451,7 +14569,7 @@ If @value is floating, @message assumes ownership of @value. A #GDBusMessage. - + The value to set. @@ -14483,7 +14601,7 @@ If @value is floating, @message assumes ownership of @value. A #GDBusMessage. - + The value to set. @@ -14515,7 +14633,7 @@ If @value is floating, @message assumes ownership of @value. A #GDBusMessage. - + The value to set. @@ -14527,7 +14645,12 @@ side-effect the %G_DBUS_MESSAGE_HEADER_FIELD_NUM_UNIX_FDS header field is set to the number of fds in @fd_list (or cleared if @fd_list is %NULL). -This method is only available on UNIX. +This method is only available on UNIX. + +When designing D-Bus APIs that are intended to be interoperable, +please note that non-GDBus implementations of D-Bus can usually only +access file descriptors if they are referenced by a value of type +%G_VARIANT_TYPE_HANDLE in the body of the message. @@ -14878,7 +15001,7 @@ If this method invocation is a property Get, Set or GetAll call that has been redirected to the method call handler then %NULL will be returned. See g_dbus_method_invocation_get_property_info() and #GDBusInterfaceVTable for more information. - + A #GDBusMethodInfo or %NULL. Do not free, it is owned by @invocation. @@ -14941,7 +15064,7 @@ property_set() vtable pointers being unset. See #GDBusInterfaceVTable for more information. If the call was GetAll, %NULL will be returned. - + a #GDBusPropertyInfo or %NULL @@ -15302,7 +15425,7 @@ handling the `org.freedesktop.DBus.Introspectable.Introspect` method. Looks up information about an interface. The cost of this function is O(n) in number of interfaces. - + A #GDBusInterfaceInfo or %NULL if not found. Do not free, it is owned by @info. @@ -15354,7 +15477,7 @@ interfaces. Gets the D-Bus interface with name @interface_name associated with @object, if any. - + %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). @@ -15429,7 +15552,7 @@ interfaces. Gets the D-Bus interface with name @interface_name associated with @object, if any. - + %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). @@ -15540,7 +15663,7 @@ interfaces. - + %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). @@ -18245,13 +18368,15 @@ implement the org.freedesktop.DBus interface. 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(). -An example of peer-to-peer communication with G-DBus can be found +An example of peer-to-peer communication with GDBus can be found in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). Note that a minimal #GDBusServer will accept connections from any peer. In many use-cases it will be necessary to add a #GDBusAuthObserver that only accepts connections that have successfully authenticated -as the same user that is running the #GDBusServer. +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 @@ -20767,7 +20892,7 @@ The @key is looked up in the "Desktop Entry" group. Gets the categories from the desktop file. - + The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it. @@ -20783,7 +20908,7 @@ The @key is looked up in the "Desktop Entry" group. When @info was created from a known filename, return it. In some situations such as the #GDesktopAppInfo returned from g_desktop_app_info_new_from_keyfile(), this function will return %NULL. - + The full path to the file for @info, or %NULL if not known. @@ -20796,8 +20921,8 @@ g_desktop_app_info_new_from_keyfile(), this function will return %NULL. - Gets the generic name from the destkop file. - + Gets the generic name from the desktop file. + The value of the GenericName key @@ -20906,7 +21031,7 @@ otherwise. Retrieves the StartupWMClass field from @info. This represents the WM_CLASS property of the main window of the application, if launched through @info. - + the startup WM class, or %NULL if none is set in the desktop file. @@ -20922,7 +21047,7 @@ in the desktop file. Looks up a string value in the keyfile backing @info. The @key is looked up in the "Desktop Entry" group. - + a newly allocated string, or %NULL if the key is not found @@ -26594,12 +26719,29 @@ See g_file_find_enclosing_mount_async(). - - - + + Gets the base name (the last component of the path) for a given #GFile. + +If called for the top level of a system (such as the filesystem root +or a uri like sftp://host/) it will return a single directory separator +(and on Windows, possibly a drive letter). + +The base name is a byte string (not UTF-8). It has no defined encoding +or rules other than it may not contain zero bytes. 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 call does no blocking I/O. + + string containing the #GFile's + base name, or %NULL if given #GFile is invalid. The returned string + should be freed with g_free() when no longer needed. + + input #GFile @@ -26677,25 +26819,42 @@ This call does no blocking I/O. - - - + + Gets the local pathname for #GFile, if one exists. If non-%NULL, this is +guaranteed to be an absolute, canonical path. It might contain symlinks. + +This call does no blocking I/O. + + string containing the #GFile's path, + or %NULL if no such path exists. The returned string should be freed + with g_free() when no longer needed. + + input #GFile - - - + + Gets the path for @descendant relative to @parent. + +This call does no blocking I/O. + + string with the relative path from + @descendant to @parent, or %NULL if @descendant doesn't have @parent as + prefix. The returned string should be freed with g_free() when + no longer needed. + + input #GFile + input #GFile @@ -26705,7 +26864,8 @@ This call does no blocking I/O. This call does no blocking I/O. - a string containing the #GFile's URI. + a string containing the #GFile's URI. If the #GFile was constructed + with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. @@ -26725,11 +26885,14 @@ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include "file", "http", "ftp", etc. +The scheme can be different from the one used to construct the #GFile, +in that it might be replaced with one that is logically equivalent to the #GFile. + This call does no blocking I/O. - + a string containing the URI scheme for the given - #GFile. The returned string should be freed with g_free() - when no longer needed. + #GFile or %NULL if the #GFile was constructed with an invalid URI. The + returned string should be freed with g_free() when no longer needed. @@ -29815,7 +29978,8 @@ This call does no blocking I/O. This call does no blocking I/O. - a string containing the #GFile's URI. + a string containing the #GFile's URI. If the #GFile was constructed + with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. @@ -29835,11 +29999,14 @@ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| Common schemes include "file", "http", "ftp", etc. +The scheme can be different from the one used to construct the #GFile, +in that it might be replaced with one that is logically equivalent to the #GFile. + This call does no blocking I/O. - + a string containing the URI scheme for the given - #GFile. The returned string should be freed with g_free() - when no longer needed. + #GFile or %NULL if the #GFile was constructed with an invalid URI. The + returned string should be freed with g_free() when no longer needed. @@ -30094,7 +30261,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. or %NULL if the length is not needed - + a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -30168,7 +30335,7 @@ set to the new entity tag for the @file. or %NULL if the length is not needed - + a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -30247,7 +30414,7 @@ needed. or %NULL if the length is not needed - + a location to place the current entity tag for the file, or %NULL if the entity tag is not needed @@ -31670,7 +31837,7 @@ changed the next time it is saved over. a set of #GFileCreateFlags - + a location to a new [entity tag][gfile-etag] for the document. This should be freed with g_free() when no longer needed, or %NULL @@ -31810,7 +31977,7 @@ tag for the document, if present. a #GAsyncResult - + a location of a new [entity tag][gfile-etag] for the document. This should be freed with g_free() when it is no longer needed, or %NULL @@ -33030,17 +33197,17 @@ attribute when the @matcher matches the whole namespace - or remove a namespace or attribute when the matcher matches everything. This is a limitation of the current implementation, but may be fixed in the future. - + A file attribute matcher matching all attributes of @matcher that are not matched by @subtract - + Matcher to subtract from - + The matcher to subtract @@ -33994,7 +34161,7 @@ on the output stream. Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. @@ -34146,7 +34313,7 @@ by g_file_io_stream_query_info_async(). Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. @@ -34410,7 +34577,7 @@ by g_file_io_stream_query_info_async(). - + the entity tag for the stream. @@ -34481,7 +34648,7 @@ to be used as icon. Gets the #GFile associated with the given @icon. - a #GFile, or %NULL. + a #GFile. @@ -34589,10 +34756,10 @@ to be used as icon. - + a string containing the URI scheme for the given - #GFile. The returned string should be freed with g_free() - when no longer needed. + #GFile or %NULL if the #GFile was constructed with an invalid URI. The + returned string should be freed with g_free() when no longer needed. @@ -34605,11 +34772,15 @@ to be used as icon. - - + + string containing the #GFile's + base name, or %NULL if given #GFile is invalid. The returned string + should be freed with g_free() when no longer needed. + + input #GFile @@ -34617,11 +34788,15 @@ to be used as icon. - - + + string containing the #GFile's path, + or %NULL if no such path exists. The returned string should be freed + with g_free() when no longer needed. + + input #GFile @@ -34630,7 +34805,8 @@ to be used as icon. - a string containing the #GFile's URI. + a string containing the #GFile's URI. If the #GFile was constructed + with an invalid URI, an invalid URI is returned. The returned string should be freed with g_free() when no longer needed. @@ -34696,14 +34872,20 @@ to be used as icon. - - + + string with the relative path from + @descendant to @parent, or %NULL if @descendant doesn't have @parent as + prefix. The returned string should be freed with g_free() when + no longer needed. + + input #GFile + input #GFile @@ -37341,7 +37523,7 @@ G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. Gets the [entity tag][gfile-etag] for a given #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. - + a string containing the value of the "etag:value" attribute. @@ -37368,7 +37550,7 @@ This is different from the file's content type, see g_file_info_get_content_type Gets the icon for a file. - + #GIcon for the given @info. @@ -37469,9 +37651,11 @@ in @result. - Gets the file's size. + Gets the file's size (in bytes). The size is retrieved through the value of +the %G_FILE_ATTRIBUTE_STANDARD_SIZE attribute and is converted +from #guint64 to #goffset before returning the result. - a #goffset containing the file's size. + a #goffset containing the file's size (in bytes). @@ -37497,7 +37681,7 @@ See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. Gets the symbolic icon for a file. - + #GIcon for the given @info. @@ -37510,7 +37694,7 @@ See %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER. Gets the symlink target for a given #GFileInfo. - + a string containing the symlink target. @@ -38940,7 +39124,7 @@ stream, use g_seekable_truncate(). Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. @@ -39092,7 +39276,7 @@ by g_file_output_stream_query_info_async(). Gets the entity tag for the file when it has been written. This must be called after the stream has been written and closed, as the etag can change while writing. - + the entity tag for the stream. @@ -39356,7 +39540,7 @@ by g_file_output_stream_query_info_async(). - + the entity tag for the stream. @@ -39518,10 +39702,10 @@ completion strings for widget implementations. Obtains a completion for @initial_text from @completer. - - a completed string, or %NULL if no completion exists. - This string is not owned by GIO, so remember to g_free() it - when finished. + + a completed string, or %NULL if no + completion exists. This string is not owned by GIO, so remember to g_free() + it when finished. @@ -42566,7 +42750,7 @@ understood by g_icon_deserialize(), yielding one of the built-in icon types. Deserializes a #GIcon previously serialized using g_icon_serialize(). - + a #GIcon, or %NULL when deserialization fails. @@ -42647,7 +42831,7 @@ back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace. - + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. @@ -42718,7 +42902,7 @@ back by calling g_icon_deserialize() on the returned value. As serialization will avoid using raw icon data when possible, it only makes sense to transfer the #GVariant between processes on the same machine, (as opposed to over the network), and within the same file system namespace. - + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. @@ -42843,7 +43027,7 @@ use in a #GHashTable or similar data structure. - + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. @@ -47285,7 +47469,7 @@ returned. If @expected_type is specified and the attribute does not have this type, %NULL is returned. %NULL is also returned if the attribute simply does not exist. - + the attribute value, or %NULL @@ -47306,7 +47490,7 @@ simply does not exist. Queries the named @link on @menu_item. - + the link, or %NULL @@ -47924,7 +48108,7 @@ expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then %NULL is returned. - + the value of the attribute @@ -47977,7 +48161,7 @@ specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. - + the linked #GMenuModel, or %NULL @@ -48146,7 +48330,7 @@ expected type is unspecified) then the value is returned. If the attribute does not exist, or does not match the expected type then %NULL is returned. - + the value of the attribute @@ -48176,7 +48360,7 @@ specified by @link. If the link exists, the linked #GMenuModel is returned. If the link does not exist, %NULL is returned. - + the linked #GMenuModel, or %NULL @@ -48426,7 +48610,7 @@ reported. The signal is emitted after the modification. - + the value of the attribute @@ -48495,7 +48679,7 @@ reported. The signal is emitted after the modification. - + the linked #GMenuModel, or %NULL @@ -50448,7 +50632,7 @@ the choice's list, or `0`. Gets the domain of the mount operation. - + a string set to the domain. @@ -50489,7 +50673,7 @@ for a TCRYPT system volume. Gets a password from the mount operation. - + a string containing the password within @op. @@ -50528,7 +50712,7 @@ for a TCRYPT system volume. Get the user name from the mount operation. - + a string containing the user name. @@ -50597,7 +50781,7 @@ for a TCRYPT system volume. a #GMountOperation. - + the domain to set. @@ -50645,7 +50829,7 @@ for a TCRYPT system volume. a #GMountOperation. - + password to set. @@ -50693,7 +50877,7 @@ for a TCRYPT system volume. a #GMountOperation. - + input username. @@ -51422,7 +51606,7 @@ depending on what @addr was created with. Gets @addr's scheme - + @addr's scheme (%NULL if not built from URI) @@ -51487,7 +51671,8 @@ There is also an implementation for use inside Flatpak sandboxes. Gets the default #GNetworkMonitor for the system. - a #GNetworkMonitor + a #GNetworkMonitor, which will be + a dummy object if no network monitor is available @@ -56083,7 +56268,7 @@ g_io_extension_point_get_extension_by_name(). Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. - + return a #GProxy or NULL if protocol is not supported. @@ -56385,7 +56570,7 @@ server; eg, "http" or "ftp". Gets @proxy's password. - + the @proxy's password @@ -56411,7 +56596,7 @@ server; eg, "http" or "ftp". Gets the proxy URI that @proxy was constructed from. - + the @proxy's URI, or %NULL if unknown @@ -56424,7 +56609,7 @@ server; eg, "http" or "ftp". Gets @proxy's username. - + the @proxy's username @@ -56673,7 +56858,8 @@ Flatpak portals. Gets the default #GProxyResolver for the system. - the default #GProxyResolver. + the default #GProxyResolver, which + will be a dummy object if no proxy resolver is available @@ -58812,12 +58998,16 @@ 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` 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` (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 @@ -58895,7 +59085,7 @@ When debugging a program or testing a change to an installed version, it is ofte 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. +during resource lookups. It is ignored when running in a setuid process. A substitution has the form @@ -61722,7 +61912,9 @@ to the name of a settings backend. The user gets a reference to the backend. - the default #GSettingsBackend + the default #GSettingsBackend, + which will be a dummy (memory) settings backend if no other settings + backend is available. @@ -62562,7 +62754,7 @@ database: those located at the path returned by this function. Relocatable schemas can be referenced by other schemas and can therefore describe multiple sets of keys at different locations. For relocatable schemas, this function will return %NULL. - + the path of the schema, or %NULL @@ -62689,7 +62881,7 @@ This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. - + the description for @key, or %NULL @@ -62775,7 +62967,7 @@ This function is slow. The summary and description information for the schemas is not stored in the compiled schema database so this function has to parse all of the source XML files in the schema directory. - + the summary for @key, or %NULL @@ -65622,6 +65814,11 @@ will be returned. To be notified when space is available, wait for the notified of a %G_IO_OUT condition. (On Windows in particular, this is very common due to the way the underlying APIs work.) +The sum of the sizes of each #GOutputVector in vectors must not be +greater than %G_MAXSSIZE. If the message can be larger than this, +then it is mandatory to use the g_socket_send_message_with_timeout() +function. + On error -1 is returned and @error is set accordingly. Number of bytes written (which may be less than @size), or -1 @@ -66848,6 +67045,15 @@ socket will be bound to this address before connecting. This is the asynchronous version of g_socket_client_connect(). +You may wish to prefer the asynchronous version even in synchronous +command line programs because, since 2.60, it implements +[RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs" +recommendations to work around long connection timeouts in networks +where IPv6 is broken by performing an IPv4 connection simultaneously +without waiting for IPv6 to time out, which is not supported by the +synchronous call. (This is not an API guarantee, and may change in +the future.) + When the operation is finished @callback will be called. You can then call g_socket_client_connect_finish() to get the result of the operation. @@ -67219,7 +67425,7 @@ See g_socket_client_set_family() for details. Gets the local address of the socket client. See g_socket_client_set_local_address() for details. - + a #GSocketAddress or %NULL. Do not free. @@ -67600,7 +67806,7 @@ Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted multiple times (or not at all) for a given connectable (in particular, if @client ends up attempting to connect to more than one address). However, if @client emits the #GSocketClient::event -signal at all for a given connectable, that it will always emit +signal at all for a given connectable, then it will always emit it with %G_SOCKET_CLIENT_COMPLETE when it is done. Note that there may be additional #GSocketClientEvent values in @@ -69976,9 +70182,9 @@ returned. Gets the #GInputStream from which to read the stderr output of @subprocess. -The process must have been created with -%G_SUBPROCESS_FLAGS_STDERR_PIPE. - +The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE, +otherwise %NULL will be returned. + the stderr pipe @@ -69993,9 +70199,9 @@ The process must have been created with Gets the #GOutputStream that you can write to in order to give data to the stdin of @subprocess. -The process must have been created with -%G_SUBPROCESS_FLAGS_STDIN_PIPE. - +The process must have been created with %G_SUBPROCESS_FLAGS_STDIN_PIPE and +not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned. + the stdout pipe @@ -70010,9 +70216,9 @@ The process must have been created with Gets the #GInputStream from which to read the stdout output of @subprocess. -The process must have been created with -%G_SUBPROCESS_FLAGS_STDOUT_PIPE. - +The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE, +otherwise %NULL will be returned. + the stdout pipe @@ -70307,7 +70513,7 @@ environment of processes launched from this launcher. On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8. - + the value of the environment variable, %NULL if unset @@ -70598,16 +70804,16 @@ On Windows, they should be in UTF-8. Transfer an arbitrary file descriptor from parent process to the -child. This function takes "ownership" of the fd; it will be closed +child. This function takes ownership of the @source_fd; it will be closed in the parent when @self is freed. By default, all file descriptors from the parent will be closed. -This function allows you to create (for example) a custom pipe() or -socketpair() before launching the process, and choose the target +This function allows you to create (for example) a custom `pipe()` or +`socketpair()` before launching the process, and choose the target descriptor in the child. An example use case is GNUPG, which has a command line argument ---passphrase-fd providing a file descriptor number where it expects +`--passphrase-fd` providing a file descriptor number where it expects the passphrase to be written. @@ -72989,7 +73195,8 @@ not return until the connection is closed. Gets the default #GTlsBackend for the system. - a #GTlsBackend + a #GTlsBackend, which will be a + dummy object if no TLS backend is available @@ -73431,7 +73638,7 @@ as appropriate.) Gets the #GTlsCertificate representing @cert's issuer, if known - + The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. @@ -73830,7 +74037,7 @@ the free the list with g_list_free(). Gets @conn's expected server identity - + a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. @@ -78582,7 +78789,7 @@ or less than @mount2, respectively. Gets the options for the mount point. - + a string containing the options. @@ -79173,7 +79380,8 @@ See [Extending GIO][extending-gio]. Gets the default #GVfs for the system. - a #GVfs. + a #GVfs, which will be the local + file system #GVfs if no other implementation is available. @@ -81224,7 +81432,7 @@ its elements have been unreffed with g_object_unref(). Finds a #GMount object by its UUID (see g_mount_get_uuid()) - + a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). @@ -81260,7 +81468,7 @@ its elements have been unreffed with g_object_unref(). Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - + a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). @@ -81405,7 +81613,7 @@ its elements have been unreffed with g_object_unref(). Finds a #GMount object by its UUID (see g_mount_get_uuid()) - + a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). @@ -81441,7 +81649,7 @@ its elements have been unreffed with g_object_unref(). Finds a #GVolume object by its UUID (see g_volume_get_uuid()) - + a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). @@ -81840,7 +82048,7 @@ GIO was used to unmount. - + a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). @@ -81859,7 +82067,7 @@ GIO was used to unmount. - + a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). @@ -82022,7 +82230,7 @@ GIO was used to unmount. Returns the #GZlibCompressor:file-info property. - + a #GFileInfo, or %NULL @@ -82109,7 +82317,7 @@ of compressed data processed by @compressor, or %NULL if @decompressor's #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, or the header data was not fully processed yet, or it not present in the data stream at all. - + a #GFileInfo, or %NULL @@ -83366,7 +83574,10 @@ g_dbus_address_get_stream_sync() for the synchronous version. - Finishes an operation started with g_dbus_address_get_stream(). + Finishes an operation started with g_dbus_address_get_stream(). + +A server is not required to set a GUID, so @out_guid may be set to %NULL +even on success. A #GIOStream or %NULL if @error is set. @@ -83376,7 +83587,7 @@ g_dbus_address_get_stream_sync() for the synchronous version. A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). - + %NULL or return location to store the GUID extracted from @address, if any. @@ -83388,6 +83599,9 @@ sets up the connection so it is in a state to run the client-side of the D-Bus authentication conversation. @address must be in the [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). +A server is not required to set a GUID, so @out_guid may be set to %NULL +even on success. + This is a synchronous failable function. See g_dbus_address_get_stream() for the asynchronous version. @@ -83399,7 +83613,7 @@ g_dbus_address_get_stream() for the asynchronous version. A valid D-Bus address. - + %NULL or return location to store the GUID extracted from @address, if any. @@ -83413,7 +83627,7 @@ g_dbus_address_get_stream() for the asynchronous version. Looks up the value of an annotation. The cost of this function is O(n) in number of annotations. - + The value or %NULL if not found. Do not free, it is owned by @annotations. @@ -83443,7 +83657,8 @@ on the wire back to a #GError using g_dbus_error_new_for_dbus_error(). This function is typically only used in object mappings to put a #GError on the wire. Regular applications should not use it. - A D-Bus error name (never %NULL). Free with g_free(). + A D-Bus error name (never %NULL). + Free with g_free(). @@ -83460,9 +83675,9 @@ This function is guaranteed to return a D-Bus error name for all #GErrors returned from functions handling remote method calls (e.g. g_dbus_connection_call_finish()) unless g_dbus_error_strip_remote_error() has been used on @error. - - an allocated string or %NULL if the D-Bus error name - could not be found. Free with g_free(). + + an allocated string or %NULL if the + D-Bus error name could not be found. Free with g_free(). @@ -83561,7 +83776,10 @@ exists. - Helper function for associating a #GError error domain with D-Bus error names. + Helper function for associating a #GError error domain with D-Bus error names. + +While @quark_volatile has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. @@ -83666,9 +83884,9 @@ returned (e.g. 0 for scalar types, the empty string for string types, See the g_dbus_gvariant_to_gvalue() function for how to convert a #GVariant to a #GValue. - A #GVariant (never floating) of #GVariantType @type holding - the data from @gvalue or %NULL in case of failure. Free with - g_variant_unref(). + A #GVariant (never floating) of + #GVariantType @type holding the data from @gvalue or an empty #GVariant + in case of failure. Free with g_variant_unref(). @@ -84109,12 +84327,12 @@ G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); GQuark foo_bar_error_quark (void) { - static volatile gsize quark_volatile = 0; + static gsize quark = 0; g_dbus_error_register_error_domain ("foo-bar-error-quark", - &quark_volatile, + &quark, foo_bar_error_entries, G_N_ELEMENTS (foo_bar_error_entries)); - return (GQuark) quark_volatile; + return (GQuark) quark; } ]| With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and @@ -84393,7 +84611,7 @@ decompresses data compressed with zlib. Deserializes a #GIcon previously serialized using g_icon_serialize(). - + a #GIcon, or %NULL when deserialization fails. @@ -84796,7 +85014,8 @@ the memory backend will start out with the default values again. Gets the default #GNetworkMonitor for the system. - a #GNetworkMonitor + a #GNetworkMonitor, which will be + a dummy object if no network monitor is available @@ -84999,7 +85218,7 @@ need to be a #GPollableOutputStream. Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. - + return a #GProxy or NULL if protocol is not supported. @@ -85014,7 +85233,8 @@ the specified protocol. Gets the default #GProxyResolver for the system. - the default #GProxyResolver. + the default #GProxyResolver, which + will be a dummy object if no proxy resolver is available @@ -85319,7 +85539,8 @@ ownership of @error, so the caller does not have to free it any more. Gets the default #GTlsBackend for the system. - a #GTlsBackend + a #GTlsBackend, which will be a + dummy object if no TLS backend is available