From 9023ce0a94fb33a2c9718dbe8780b2c52703a904 Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Tue, 5 Jan 2021 02:56:48 +0100 Subject: [PATCH] gir-files: Import from gir-files at 824aa87 --- gir-files/GLib-2.0.gir | 6039 +++++++++++++++++++++++++++++++++++-- gir-files/GModule-2.0.gir | 74 + gir-files/GObject-2.0.gir | 478 ++- gir-files/Gio-2.0.gir | 1021 ++++++- 4 files changed, 7260 insertions(+), 352 deletions(-) diff --git a/gir-files/GLib-2.0.gir b/gir-files/GLib-2.0.gir index a5a98f4cc..08934e1bf 100644 --- a/gir-files/GLib-2.0.gir +++ b/gir-files/GLib-2.0.gir @@ -345,6 +345,10 @@ The elements between the old end of the array and the newly inserted elements will be initialised to zero if the array was configured to clear elements; otherwise their values will be undefined. +If @index_ is less than the array’s current length, new entries will be +inserted into the array, and the existing entries above @index_ will be moved +upwards. + @data may be %NULL if (and only if) @len is zero. If @len is zero, this function is a no-op. @@ -1449,11 +1453,13 @@ If no bookmark for @uri is found then it is created. - + Gets the time the bookmark for @uri was added to @bookmark In the event the URI cannot be found, -1 is returned and @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + Use g_bookmark_file_get_added_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem. a timestamp @@ -1470,9 +1476,30 @@ In the event the URI cannot be found, -1 is returned and - + + Gets the time the bookmark for @uri was added to @bookmark + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + + a #GDateTime + + + + + a #GBookmarkFile + + + + a valid URI + + + + + Gets the registration information of @app_name for the bookmark for -@uri. See g_bookmark_file_set_app_info() for more information about +@uri. See g_bookmark_file_set_application_info() for more information about the returned data. The string returned in @app_exec must be freed. @@ -1484,6 +1511,8 @@ for @uri, %FALSE is returned and error is set to #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting the command line fails, an error of the #G_SHELL_ERROR domain is set and %FALSE is returned. + Use g_bookmark_file_get_application_info() instead, as + `time_t` is deprecated due to the year 2038 problem. %TRUE on success. @@ -1516,6 +1545,52 @@ set and %FALSE is returned. + + Gets the registration information of @app_name for the bookmark for +@uri. See g_bookmark_file_set_application_info() for more information about +the returned data. + +The string returned in @app_exec must be freed. + +In the event the URI cannot be found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. In the +event that no application with name @app_name has registered a bookmark +for @uri, %FALSE is returned and error is set to +#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. In the event that unquoting +the command line fails, an error of the #G_SHELL_ERROR domain is +set and %FALSE is returned. + + + %TRUE on success. + + + + + a #GBookmarkFile + + + + a valid URI + + + + an application's name + + + + return location for the command line of the application, or %NULL + + + + return location for the registration count, or %NULL + + + + return location for the last registration time, or %NULL + + + + Retrieves the names of the applications that have registered the bookmark for @uri. @@ -1675,11 +1750,13 @@ event that the MIME type cannot be found, %NULL is returned and - + Gets the time when the bookmark for @uri was last modified. In the event the URI cannot be found, -1 is returned and @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + Use g_bookmark_file_get_modified_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem. a timestamp @@ -1696,6 +1773,27 @@ In the event the URI cannot be found, -1 is returned and + + Gets the time when the bookmark for @uri was last modified. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + + a #GDateTime + + + + + a #GBookmarkFile + + + + a valid URI + + + + Gets the number of bookmarks inside @bookmark. @@ -1757,11 +1855,13 @@ optionally be %NULL. - + Gets the time the bookmark for @uri was last visited. In the event the URI cannot be found, -1 is returned and @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + Use g_bookmark_file_get_visited_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem. a timestamp. @@ -1778,6 +1878,27 @@ In the event the URI cannot be found, -1 is returned and + + Gets the time the bookmark for @uri was last visited. + +In the event the URI cannot be found, %NULL is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. + + + a #GDateTime + + + + + a #GBookmarkFile + + + + a valid URI + + + + Checks whether the bookmark for @uri inside @bookmark has been registered by application @name. @@ -2025,10 +2146,12 @@ In the event no group was defined, %FALSE is returned and - + Sets the time the bookmark for @uri was added into @bookmark. If no bookmark for @uri is found then it is created. + Use g_bookmark_file_set_added_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem. @@ -2048,7 +2171,30 @@ If no bookmark for @uri is found then it is created. - + + Sets the time the bookmark for @uri was added into @bookmark. + +If no bookmark for @uri is found then it is created. + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a #GDateTime + + + + + Sets the meta-data of application @name inside the list of applications that have registered a bookmark for @uri inside @bookmark. @@ -2062,7 +2208,7 @@ application. be expanded as the local file name retrieved from the bookmark's URI; "\%u", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored -command line using the g_bookmark_file_get_app_info() function. +command line using the g_bookmark_file_get_application_info() function. @count is the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application with @name will be removed from @@ -2077,6 +2223,8 @@ in the event that no application @name has registered a bookmark for @uri, %FALSE is returned and error is set to #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark for @uri is found, one is created. + Use g_bookmark_file_set_application_info() instead, as + `time_t` is deprecated due to the year 2038 problem. %TRUE if the application's meta-data was successfully @@ -2110,6 +2258,68 @@ for @uri is found, one is created. + + Sets the meta-data of application @name inside the list of +applications that have registered a bookmark for @uri inside +@bookmark. + +You should rarely use this function; use g_bookmark_file_add_application() +and g_bookmark_file_remove_application() instead. + +@name can be any UTF-8 encoded string used to identify an +application. +@exec can have one of these two modifiers: "\%f", which will +be expanded as the local file name retrieved from the bookmark's +URI; "\%u", which will be expanded as the bookmark's URI. +The expansion is done automatically when retrieving the stored +command line using the g_bookmark_file_get_application_info() function. +@count is the number of times the application has registered the +bookmark; if is < 0, the current registration count will be increased +by one, if is 0, the application with @name will be removed from +the list of registered applications. +@stamp is the Unix time of the last registration. + +If you try to remove an application by setting its registration count to +zero, and no bookmark for @uri is found, %FALSE is returned and +@error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND; similarly, +in the event that no application @name has registered a bookmark +for @uri, %FALSE is returned and error is set to +#G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark +for @uri is found, one is created. + + + %TRUE if the application's meta-data was successfully + changed. + + + + + a #GBookmarkFile + + + + a valid URI + + + + an application's name + + + + an application's command line + + + + the number of registrations done for this application + + + + the time of the last registration for this application, + which may be %NULL if @count is 0 + + + + Sets @description as the description of the bookmark for @uri. @@ -2241,7 +2451,7 @@ If a bookmark for @uri cannot be found then it is created. - + Sets the last time the bookmark for @uri was last modified. If no bookmark for @uri is found then it is created. @@ -2249,7 +2459,9 @@ If no bookmark for @uri is found then it is created. The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of #GBookmarkFile that modifies a bookmark also changes the modification time, except for -g_bookmark_file_set_visited(). +g_bookmark_file_set_visited_date_time(). + Use g_bookmark_file_set_modified_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem. @@ -2269,6 +2481,34 @@ g_bookmark_file_set_visited(). + + Sets the last time the bookmark for @uri was last modified. + +If no bookmark for @uri is found then it is created. + +The "modified" time should only be set when the bookmark's meta-data +was actually changed. Every function of #GBookmarkFile that +modifies a bookmark also changes the modification time, except for +g_bookmark_file_set_visited_date_time(). + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a #GDateTime + + + + Sets @title as the title of the bookmark for @uri inside the bookmark file @bookmark. @@ -2295,16 +2535,18 @@ If a bookmark for @uri cannot be found then it is created. - + Sets the time the bookmark for @uri was last visited. If no bookmark for @uri is found then it is created. The "visited" time should only be set if the bookmark was launched, -either using the command line retrieved by g_bookmark_file_get_app_info() +either using the command line retrieved by g_bookmark_file_get_application_info() or by the default application for the bookmark's MIME type, retrieved using g_bookmark_file_get_mime_type(). Changing the "visited" time does not affect the "modified" time. + Use g_bookmark_file_set_visited_date_time() instead, as + `time_t` is deprecated due to the year 2038 problem. @@ -2324,6 +2566,35 @@ does not affect the "modified" time. + + Sets the time the bookmark for @uri was last visited. + +If no bookmark for @uri is found then it is created. + +The "visited" time should only be set if the bookmark was launched, +either using the command line retrieved by g_bookmark_file_get_application_info() +or by the default application for the bookmark's MIME type, retrieved +using g_bookmark_file_get_mime_type(). Changing the "visited" time +does not affect the "modified" time. + + + + + + + a #GBookmarkFile + + + + a valid URI + + + + a #GDateTime + + + + This function outputs @bookmark as a string. @@ -4037,6 +4308,13 @@ in the macro, so you shouldn't use double quotes. + + + + + + + This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it @@ -4194,6 +4472,13 @@ int my_mistake (void); + + + + + + + @@ -4341,6 +4626,13 @@ int my_mistake (void); + + + + + + + @@ -4488,6 +4780,13 @@ int my_mistake (void); + + + + + + + The directory separator character. This is '/' on UNIX machines and '\' under Windows. @@ -4538,7 +4837,7 @@ to mutate but invalid and thus not safe for calendrical computations. If it's declared on the stack, it will contain garbage so must be initialized with g_date_clear(). g_date_clear() makes the date invalid -but sane. An invalid date doesn't represent a day, it's "empty." A date +but safe. An invalid date doesn't represent a day, it's "empty." A date becomes valid after you set it to a Julian day or you set a day, month, and year. @@ -4570,7 +4869,7 @@ and year. Allocates a #GDate and initializes -it to a sane state. The new date will +it to a safe state. The new date will be cleared (as if you'd called g_date_clear()) but invalid (it won't represent an existing day). Free the return value with g_date_free(). @@ -4705,7 +5004,7 @@ All non-%NULL dates must be valid. - Initializes one or more #GDate structs to a sane but invalid + Initializes one or more #GDate structs to a safe but invalid state. The cleared dates will not represent an existing date, but will not contain garbage. Useful to init a date declared on the stack. Validity can be tested with g_date_valid(). @@ -5233,7 +5532,7 @@ must be valid. Fills in the date-related bits of a struct tm using the @date value. -Initializes the non-date parts with something sane but meaningless. +Initializes the non-date parts with something safe but meaningless. @@ -5573,7 +5872,7 @@ return %NULL. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL @@ -5685,7 +5984,7 @@ when you are done with it. #GTimeVal is not year-2038-safe. Use g_date_time_new_from_unix_local() instead. - + a new #GDateTime, or %NULL @@ -5710,7 +6009,7 @@ when you are done with it. #GTimeVal is not year-2038-safe. Use g_date_time_new_from_unix_utc() instead. - + a new #GDateTime, or %NULL @@ -5734,7 +6033,7 @@ of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL @@ -5757,7 +6056,7 @@ of the supported range of #GDateTime. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL @@ -5775,7 +6074,7 @@ the local time zone. This call is equivalent to calling g_date_time_new() with the time zone returned by g_time_zone_new_local(). - + a #GDateTime, or %NULL @@ -5811,14 +6110,13 @@ zone returned by g_time_zone_new_local(). time zone @tz. The time is as accurate as the system allows, to a maximum accuracy of 1 microsecond. -This function will always succeed unless the system clock is set to -truly insane values (or unless GLib is still being used after the -year 9999). +This function will always succeed unless GLib is still being used after the +year 9999. You should release the return value by calling g_date_time_unref() when you are done with it. - + a new #GDateTime, or %NULL @@ -5836,7 +6134,7 @@ time zone. This is equivalent to calling g_date_time_new_now() with the time zone returned by g_time_zone_new_local(). - + a new #GDateTime, or %NULL @@ -5847,7 +6145,7 @@ zone returned by g_time_zone_new_local(). This is equivalent to calling g_date_time_new_now() with the time zone returned by g_time_zone_new_utc(). - + a new #GDateTime, or %NULL @@ -5859,7 +6157,7 @@ UTC. This call is equivalent to calling g_date_time_new() with the time zone returned by g_time_zone_new_utc(). - + a #GDateTime, or %NULL @@ -5893,9 +6191,9 @@ zone returned by g_time_zone_new_utc(). Creates a copy of @datetime and adds the specified timespan to the copy. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -5913,9 +6211,9 @@ zone returned by g_time_zone_new_utc(). Creates a copy of @datetime and adds the specified number of days to the copy. Add negative values to subtract days. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -5933,9 +6231,9 @@ copy. Add negative values to subtract days. Creates a new #GDateTime adding the specified values to the current date and time in @datetime. Add negative values to subtract. - - the newly created #GDateTime that should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -5973,9 +6271,9 @@ time in @datetime. Add negative values to subtract. Creates a copy of @datetime and adds the specified number of hours. Add negative values to subtract hours. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -5993,9 +6291,9 @@ Add negative values to subtract hours. Creates a copy of @datetime adding the specified number of minutes. Add negative values to subtract minutes. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6018,9 +6316,9 @@ of days in the updated calendar month. For example, if adding 1 month to 31st January 2018, the result would be 28th February 2018. In 2020 (a leap year), the result would be 29th February. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6038,9 +6336,9 @@ year), the result would be 29th February. Creates a copy of @datetime and adds the specified number of seconds. Add negative values to subtract seconds. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6058,9 +6356,9 @@ Add negative values to subtract seconds. Creates a copy of @datetime and adds the specified number of weeks to the copy. Add negative values to subtract weeks. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6081,9 +6379,9 @@ copy. Add negative values to subtract years. As with g_date_time_add_months(), if the resulting date would be 29th February on a non-leap year, the day will be clamped to 28th February. - - the newly created #GDateTime which should be freed with - g_date_time_unref(). + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6125,7 +6423,7 @@ The format strings understood by this function are a subset of the strftime() format language as specified by C99. The \%D, \%U and \%W conversions are not supported, nor is the 'E' modifier. The GNU extensions \%k, \%l, \%s and \%P are supported, however, as are the -'0', '_' and '-' modifiers. +'0', '_' and '-' modifiers. The Python extension \%f is also supported. In contrast to strftime(), this function always produces a UTF-8 string, regardless of the current locale. Note that the rendering of @@ -6157,12 +6455,17 @@ The following format specifiers are supported: single digits are preceded by a blank - \%m: the month as a decimal number (range 01 to 12) - \%M: the minute as a decimal number (range 00 to 59) +- \%f: the microsecond as a decimal number (range 000000 to 999999) - \%p: either "AM" or "PM" according to the given time value, or the corresponding strings for the current locale. Noon is treated as - "PM" and midnight as "AM". + "PM" and midnight as "AM". Use of this format specifier is discouraged, as + many locales have no concept of AM/PM formatting. Use \%c or \%X instead. - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for - the current locale -- \%r: the time in a.m. or p.m. notation + the current locale. Use of this format specifier is discouraged, as + many locales have no concept of AM/PM formatting. Use \%c or \%X instead. +- \%r: the time in a.m. or p.m. notation. Use of this format specifier is + discouraged, as many locales have no concept of AM/PM formatting. Use \%c + or \%X instead. - \%R: the time in 24-hour notation (\%H:\%M) - \%s: the number of seconds since the Epoch, that is, since 1970-01-01 00:00:00 UTC @@ -6214,11 +6517,11 @@ rules. For other languages there is no difference. \%OB is a GNU and BSD strftime() extension expected to be added to the future POSIX specification, \%Ob and \%Oh are GNU strftime() extensions. Since: 2.56 - - a newly allocated string formatted to the requested format - or %NULL in the case that there was an error (such as a format specifier - not being supported in the current locale). The string - should be freed with g_free(). + + a newly allocated string formatted to + the requested format or %NULL in the case that there was an error (such + as a format specifier not being supported in the current locale). The + string should be freed with g_free(). @@ -6236,12 +6539,14 @@ strftime() extension expected to be added to the future POSIX specification, Format @datetime in [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601), including the date, time and time zone, and return that as a UTF-8 encoded -string. +string. + +Since GLib 2.66, this will output to sub-second precision if needed. - - a newly allocated string formatted in ISO 8601 format - or %NULL in the case that there was an error. The string - should be freed with g_free(). + + a newly allocated string formatted in + ISO 8601 format or %NULL in the case that there was an error. The string + should be freed with g_free(). @@ -6586,8 +6891,9 @@ the time zone of @datetime. This call is equivalent to calling g_date_time_to_timezone() with the time zone returned by g_time_zone_new_local(). - - the newly created #GDateTime + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6635,13 +6941,11 @@ On systems where 'long' is 64bit, this function never fails. This call can fail in the case that the time goes out of bounds. For example, converting 0001-01-01 00:00:00 UTC to a time zone west of -Greenwich will fail (due to the year 0 being out of range). - -You should release the return value by calling g_date_time_unref() -when you are done with it. +Greenwich will fail (due to the year 0 being out of range). - - a new #GDateTime, or %NULL + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -6680,8 +6984,9 @@ Unix time is the number of seconds that have elapsed since 1970-01-01 This call is equivalent to calling g_date_time_to_timezone() with the time zone returned by g_time_zone_new_utc(). - - the newly created #GDateTime + + the newly created #GDateTime which + should be freed with g_date_time_unref(), or %NULL @@ -7327,6 +7632,35 @@ differences in when a system will report a given error, etc. code applies. + + Flags to pass to g_file_set_contents_full() to affect its safety and +performance. + + + No guarantees about file consistency or durability. + The most dangerous setting, which is slightly faster than other settings. + + + Guarantee file consistency: after a crash, + either the old version of the file or the new version of the file will be + available, but not a mixture. On Unix systems this equates to an `fsync()` + on the file and use of an atomic `rename()` of the new version of the file + over the old. + + + Guarantee file durability: after a crash, the + new version of the file will be available. On Unix systems this equates to + an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or + the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the + directory containing the file after calling `rename()`. + + + Only apply consistency and durability + guarantees if the file already exists. This may speed up file operations + if the file doesn’t currently exist, but may result in a corrupted version + of the new file if the system crashes while writing it. + + A test to perform on a file using g_file_test(). @@ -7966,7 +8300,7 @@ cause hash collisions. Therefore, you should consider choosing a more secure hash function when using a GHashTable with keys that originate in untrusted data (such as HTTP requests). Using g_str_hash() in that situation might make your application -vulerable to +vulnerable to [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/). The key to choosing a good hash is unpredictability. Even @@ -10174,7 +10508,7 @@ programmer (unless you are creating a new type of #GIOChannel). the size of the buffer. Note that the buffer may not be - complelely filled even if there is data in the buffer if the + completely filled even if there is data in the buffer if the remaining data is not a complete character. @@ -10963,7 +11297,7 @@ in a generic way. - Stati returned by most of the #GIOFuncs functions. + Statuses returned by most of the #GIOFuncs functions. An error occurred. @@ -11856,7 +12190,7 @@ loads the file into @key_file and returns the file's full path in set to either a #GFileError or #GKeyFileError. - %TRUE if a key file could be loaded, %FALSE othewise + %TRUE if a key file could be loaded, %FALSE otherwise @@ -12031,7 +12365,9 @@ from the key file. Writes the contents of @key_file to @filename using -g_file_set_contents(). +g_file_set_contents(). If you need stricter guarantees about durability of +the written file than are provided by g_file_set_contents(), use +g_file_set_contents_full() with the return value of g_key_file_to_data(). This function can fail for any of the reasons that g_file_set_contents() may fail. @@ -13827,7 +14163,7 @@ linked against at application run time. - + The micro version number of the GLib library. Like #gtk_micro_version, but from the headers used at @@ -13856,7 +14192,7 @@ linked against at application run time. - + The minor version number of the GLib library. Like #gtk_minor_version, but from the headers used at @@ -17465,7 +17801,7 @@ or g_option_group_add_entries(). - + Error codes returned by option parsing. @@ -20411,7 +20747,7 @@ library written by Philip Hazel. the initial setup of the #GRegex structure. - a #GRegex structure or %NULL if an error occured. Call + a #GRegex structure or %NULL if an error occurred. Call g_regex_unref() when you are done with it @@ -20858,7 +21194,7 @@ There are also escapes that changes the case of the following text: If you do not need to use backreferences use g_regex_replace_literal(). The @replacement string must be UTF-8 encoded even if #G_REGEX_RAW was -passed to g_regex_new(). If you want to use not UTF-8 encoded stings +passed to g_regex_new(). If you want to use not UTF-8 encoded strings you can use g_regex_replace_literal(). Setting @start_position differs from just passing over a shortened @@ -25612,7 +25948,7 @@ list to the `g_spawn...` function. as the file to execute, and passes all of `argv` to the child. - if `argv[0]` is not an abolute path, + if `argv[0]` is not an absolute path, it will be looked for in the `PATH` from the passed child environment. Since: 2.34 @@ -25758,7 +26094,7 @@ to the string. - Appends @unescaped to @string, escaped any characters that + Appends @unescaped to @string, escaping any characters that are reserved in URIs using URI-style escape sequences. @@ -26885,7 +27221,7 @@ explicitly. The structure is opaque -- none of its fields may be directly accessed. - + This function creates a new thread. The new thread starts by invoking @func with the argument data. The thread will run until @func returns or until g_thread_exit() is called from the new thread. The return value @@ -26923,7 +27259,7 @@ POSIX and all threads inherit their parent thread's priority. an (optional) name for the new thread - + a function to execute in the new thread @@ -26933,7 +27269,7 @@ POSIX and all threads inherit their parent thread's priority. - + This function is the same as g_thread_new() except that it allows for the possibility of failure. @@ -26949,7 +27285,7 @@ If a thread can not be created (due to resource limits), an (optional) name for the new thread - + a function to execute in the new thread @@ -26977,12 +27313,12 @@ This will usually cause the #GThread struct and associated resources to be freed. Use g_thread_ref() to obtain an extra reference if you want to keep the GThread alive beyond the g_thread_join() call. - + the return value of the thread - + a #GThread @@ -27014,7 +27350,7 @@ if you don't need it anymore. - + a #GThread @@ -27061,7 +27397,7 @@ APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as g_thread_join()) on these threads. - + the #GThread representing the current thread @@ -27126,10 +27462,10 @@ Note however, that no thread of this pool is interrupted while processing a task. Instead at least all still running threads can finish their tasks before the @pool is freed. -If @wait_ is %TRUE, the functions does not return before all +If @wait_ is %TRUE, this function does not return before all tasks to be processed (dependent on @immediate, whether all or only the currently running) are ready. -Otherwise the function returns immediately. +Otherwise this function returns immediately. After calling this function @pool must not be used anymore. @@ -27357,6 +27693,10 @@ newly created or reused thread now executes the function @func with the two arguments. The first one is the parameter to g_thread_pool_push() and the second one is @user_data. +Pass g_get_num_processors() to @max_threads to create as many threads as +there are logical processors on the system. This will not pin each thread to +a specific processor. + The parameter @exclusive determines whether the thread pool owns all threads exclusive or shares them with other thread pools. If @exclusive is %TRUE, @max_threads threads are started @@ -28321,7 +28661,7 @@ parameter passed to g_tree_traverse(). If the function returns - Specifies the type of traveral performed by g_tree_traverse(), + Specifies the type of traversal performed by g_tree_traverse(), g_node_traverse() and g_node_find(). The different orders are illustrated here: - In order: A, B, C, D, E, F, G, H, I @@ -28434,7 +28774,10 @@ 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. +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)). @@ -28540,7 +28883,11 @@ It is safe to call this function from any thread. If the #GTree was created using g_tree_new_full(), the key and value are freed using the supplied destroy functions, otherwise you have to make sure that any dynamically allocated values are freed yourself. -If the key does not exist in the #GTree, the function does nothing. +If the key does not exist in the #GTree, the function does nothing. + +The cost of maintaining a balanced tree while removing a key/value +result in a O(n log(n)) operation where most of the other operations +are O(log(n)). %TRUE if the key was found (prior to 2.8, this function @@ -28791,6 +29138,15 @@ that has been annotated with this macros will produce a compiler warning. + + + + + + + + + @@ -28833,13 +29189,15 @@ if (G_UNLIKELY (random () == 1)) - - Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". + + Generic delimiters characters as defined in +[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`. - - Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". + + Subcomponent delimiter characters as defined in +[RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`. @@ -29460,6 +29818,18 @@ See [Unicode Standard Annex #24: Script names](http://www.unicode.org/reports/tr Wcho. Since: 2.62 + + Chorasmian. Since: 2.66 + + + Dives Akuru. Since: 2.66 + + + Khitan small script. Since: 2.66 + + + Yezidi. Since: 2.66 + These are the possible character classifications from the @@ -29580,6 +29950,1419 @@ triggers. + + The #GUri type and related functions can be used to parse URIs into +their components, and build valid URIs from individual components. + +Note that #GUri scope is to help manipulate URIs in various applications, +following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular, +it doesn't intend to cover web browser needs, and doesn't implement the +[WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to +help prevent +[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so +#GUri is not suitable for formatting URIs for display to the user for making +security-sensitive decisions. + +## Relative and absolute URIs # {#relative-absolute-uris} + +As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the +hierarchical nature of URIs means that they can either be ‘relative +references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for +clarity, ‘URIs’ are referred to in this documentation as +‘absolute URIs’ — although +[in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3), +fragment identifiers are always allowed). + +Relative references have one or more components of the URI missing. In +particular, they have no scheme. Any other component, such as hostname, +query, etc. may be missing, apart from a path, which has to be specified (but +may be empty). The path may be relative, starting with `./` rather than `/`. + +For example, a valid relative reference is `./path?query`, +`/?query#fragment` or `//example.com`. + +Absolute URIs have a scheme specified. Any other components of the URI which +are missing are specified as explicitly unset in the URI, rather than being +resolved relative to a base URI using g_uri_parse_relative(). + +For example, a valid absolute URI is `file:///home/bob` or +`https://search.com?query=string`. + +A #GUri instance is always an absolute URI. A string may be an absolute URI +or a relative reference; see the documentation for individual functions as to +what forms they accept. + +## Parsing URIs + +The most minimalist APIs for parsing URIs are g_uri_split() and +g_uri_split_with_user(). These split a URI into its component +parts, and return the parts; the difference between the two is that +g_uri_split() treats the ‘userinfo’ component of the URI as a +single element, while g_uri_split_with_user() can (depending on the +#GUriFlags you pass) treat it as containing a username, password, +and authentication parameters. Alternatively, g_uri_split_network() +can be used when you are only interested in the components that are +needed to initiate a network connection to the service (scheme, +host, and port). + +g_uri_parse() is similar to g_uri_split(), but instead of returning +individual strings, it returns a #GUri structure (and it requires +that the URI be an absolute URI). + +g_uri_resolve_relative() and g_uri_parse_relative() allow you to +resolve a relative URI relative to a base URI. +g_uri_resolve_relative() takes two strings and returns a string, +and g_uri_parse_relative() takes a #GUri and a string and returns a +#GUri. + +All of the parsing functions take a #GUriFlags argument describing +exactly how to parse the URI; see the documentation for that type +for more details on the specific flags that you can pass. If you +need to choose different flags based on the type of URI, you can +use g_uri_peek_scheme() on the URI string to check the scheme +first, and use that to decide what flags to parse it with. + +For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the +params for a web URI, so compare the result of g_uri_peek_scheme() against +`http` and `https`. + +## Building URIs + +g_uri_join() and g_uri_join_with_user() can be used to construct +valid URI strings from a set of component strings. They are the +inverse of g_uri_split() and g_uri_split_with_user(). + +Similarly, g_uri_build() and g_uri_build_with_user() can be used to +construct a #GUri from a set of component strings. + +As with the parsing functions, the building functions take a +#GUriFlags argument. In particular, it is important to keep in mind +whether the URI components you are using are already `%`-encoded. If so, +you must pass the %G_URI_FLAGS_ENCODED flag. + +## `file://` URIs + +Note that Windows and Unix both define special rules for parsing +`file://` URIs (involving non-UTF-8 character sets on Unix, and the +interpretation of path separators on Windows). #GUri does not +implement these rules. Use g_filename_from_uri() and +g_filename_to_uri() if you want to properly convert between +`file://` URIs and local filenames. + +## URI Equality + +Note that there is no `g_uri_equal ()` function, because comparing +URIs usefully requires scheme-specific knowledge that #GUri does +not have. 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. + + + Gets @uri's authentication parameters, which may contain +`%`-encoding, depending on the flags with which @uri was created. +(If @uri was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will +be %NULL.) + +Depending on the URI scheme, g_uri_parse_params() may be useful for +further parsing this information. + + + @uri's authentication parameters. + + + + + a #GUri + + + + + + Gets @uri's flags set upon construction. + + + @uri's flags. + + + + + a #GUri + + + + + + Gets @uri's fragment, which may contain `%`-encoding, depending on +the flags with which @uri was created. + + + @uri's fragment. + + + + + a #GUri + + + + + + Gets @uri's host. This will never have `%`-encoded characters, +unless it is non-UTF-8 (which can only be the case if @uri was +created with %G_URI_FLAGS_NON_DNS). + +If @uri contained an IPv6 address literal, this value will be just +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. + + + + + a #GUri + + + + + + Gets @uri's password, which may contain `%`-encoding, depending on +the flags with which @uri was created. (If @uri was not created +with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.) + + + @uri's password. + + + + + a #GUri + + + + + + Gets @uri's path, which may contain `%`-encoding, depending on the +flags with which @uri was created. + + + @uri's path. + + + + + a #GUri + + + + + + Gets @uri's port. + + + @uri's port, or `-1` if no port was specified. + + + + + a #GUri + + + + + + Gets @uri's query, which may contain `%`-encoding, depending on the +flags with which @uri was created. + +For queries consisting of a series of `name=value` parameters, +#GUriParamsIter or g_uri_parse_params() may be useful. + + + @uri's query. + + + + + a #GUri + + + + + + Gets @uri's scheme. Note that this will always be all-lowercase, +regardless of the string or strings that @uri was created from. + + + @uri's scheme. + + + + + a #GUri + + + + + + Gets the ‘username’ component of @uri's userinfo, which may contain +`%`-encoding, depending on the flags with which @uri was created. +If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or +%G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo(). + + + @uri's user. + + + + + a #GUri + + + + + + Gets @uri's userinfo, which may contain `%`-encoding, depending on +the flags with which @uri was created. + + + @uri's userinfo. + + + + + a #GUri + + + + + + Parses @uri_ref according to @flags and, if it is a +[relative URI][relative-absolute-uris], resolves it relative to @base_uri. +If the result is not a valid absolute URI, it will be discarded, and an error +returned. + + + a new #GUri. + + + + + a base absolute URI + + + + a string representing a relative or absolute URI + + + + flags describing how to parse @uri_ref + + + + + + Increments the reference count of @uri by one. + + + @uri + + + + + a #GUri + + + + + + Returns a string representing @uri. + +This is not guaranteed to return a string which is identical to the +string that @uri was parsed from. However, if the source URI was +syntactically correct (according to RFC 3986), and it was parsed +with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return +a string which is at least semantically equivalent to the source +URI (according to RFC 3986). + +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 #GUri + + + + + + 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 #GUri + + + + flags describing what parts of @uri to hide + + + + + + Atomically decrements the reference count of @uri by one. + +When the reference count reaches zero, the resources allocated by +@uri are freed + + + + + + + a #GUri + + + + + + Creates a new #GUri from the given components according to @flags. + +See also g_uri_build_with_user(), which allows specifying the +components of the "userinfo" separately. + + + a new #GUri + + + + + flags describing how to build the #GUri + + + + the URI scheme + + + + the userinfo component, or %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + Creates a new #GUri from the given components according to @flags +(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be +coherent with the passed values, in particular use `%`-encoded values with +%G_URI_FLAGS_ENCODED. + +In contrast to g_uri_build(), this allows specifying the components +of the ‘userinfo’ field separately. Note that @user must be non-%NULL +if either @password or @auth_params is non-%NULL. + + + a new #GUri + + + + + flags describing how to build the #GUri + + + + the URI scheme + + + + the user component of the userinfo, or %NULL + + + + the password component of the userinfo, or %NULL + + + + the auth params of the userinfo, or %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + + + + + + Escapes arbitrary data for use in a URI. + +Normally all characters that are not ‘unreserved’ (i.e. ASCII +alphanumerical characters plus dash, dot, underscore and tilde) are +escaped. But if you specify characters in @reserved_chars_allowed +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. + +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. + + + + + the unescaped input data. + + + + + + the length of @unescaped + + + + a string of reserved + characters that are allowed to be used, or %NULL. + + + + + + Escapes a string for use in a URI. + +Normally all characters that are not "unreserved" (i.e. ASCII +alphanumerical characters plus dash, dot, underscore and tilde) are +escaped. But if you specify characters in @reserved_chars_allowed +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. + + + + + the unescaped input string. + + + + a string of reserved + characters that are allowed to be used, or %NULL. + + + + %TRUE if the result can include UTF-8 characters. + + + + + + Parses @uri_string according to @flags, to determine whether it is a valid +[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved +relative to another URI using g_uri_parse_relative(). + +If it’s not a valid URI, an error is returned explaining how it’s invalid. + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags. + + + %TRUE if @uri_string is a valid absolute URI, %FALSE on error. + + + + + a string containing an absolute URI + + + + flags for parsing @uri_string + + + + + + Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +When @host is present, @path must either be empty or begin with a slash (`/`) +character. When @host is not present, @path cannot begin with two slash + characters (`//`). See +[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). + +See also g_uri_join_with_user(), which allows specifying the +components of the ‘userinfo’ separately. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags. + + + an absolute URI string + + + + + flags describing how to build the URI string + + + + the URI scheme, or %NULL + + + + the userinfo component, or %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +In contrast to g_uri_join(), this allows specifying the components +of the ‘userinfo’ separately. It otherwise behaves the same. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags. + + + an absolute URI string + + + + + flags describing how to build the URI string + + + + the URI scheme, or %NULL + + + + the user component of the userinfo, or %NULL + + + + the password component of the userinfo, or + %NULL + + + + the auth params of the userinfo, or + %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + Splits an URI list conforming to the text/uri-list +mime type defined in RFC 2483 into individual URIs, +discarding any comments. The URIs are not validated. + + + a newly allocated %NULL-terminated list + of strings holding the individual URIs. The array should be freed + with g_strfreev(). + + + + + + + an URI list + + + + + + Parses @uri_string according to @flags. If the result is not a +valid [absolute URI][relative-absolute-uris], it will be discarded, and an +error returned. + + + a new #GUri. + + + + + a string representing an absolute URI + + + + flags describing how to parse @uri_string + + + + + + Many URI schemes include one or more attribute/value pairs as part of the URI +value. This method can be used to parse them into a hash table. When an +attribute has multiple occurrences, the last value is the final returned +value. If you need to handle repeated attributes differently, use +#GUriParamsIter. + +The @params string is assumed to still be `%`-encoded, but the returned +values will be fully decoded. (Thus it is possible that the returned values +may contain `=` or @separators, if the value was encoded in the input.) +Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED +rules for g_uri_parse(). (However, if @params is the path or query string +from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and +%G_URI_FLAGS_ENCODED, then you already know that it does not contain any +invalid encoding.) + +%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). + +If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be +compared case-insensitively, so a params string `attr=123&Attr=456` will only +return a single attribute–value pair, `Attr=456`. Case will be preserved in +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 `%`-encoded string containing `attribute=value` + parameters + + + + the length of @params, or `-1` if it is nul-terminated + + + + the separator byte character set between parameters. (usually + `&`, but sometimes `;` or both `&;`). Note that this function works on + bytes not characters, so it can't be used to delimit UTF-8 strings for + anything but ASCII characters. You may pass an empty set, in which case + no splitting will occur. + + + + flags to modify the way the parameters are handled. + + + + + + Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc. + + + The ‘scheme’ component of the URI, or + %NULL on error. The returned string should be freed when no longer needed. + + + + + a valid URI. + + + + + + Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc. + +Unlike g_uri_parse_scheme(), the returned scheme is normalized to +all-lowercase and does not need to be freed. + + + The ‘scheme’ component of the URI, or + %NULL on error. The returned string is normalized to all-lowercase, and + interned via g_intern_string(), so it does not need to be freed. + + + + + a valid URI. + + + + + + Parses @uri_ref according to @flags and, if it is a +[relative URI][relative-absolute-uris], resolves it relative to +@base_uri_string. If the result is not a valid absolute URI, it will be +discarded, and an error returned. + +(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. + + + + + a string representing a base URI + + + + a string representing a relative or absolute URI + + + + flags describing how to parse @uri_ref + + + + + + Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in +@uri_ref will remain encoded in the output strings. (If not, +then all such characters will be decoded.) Note that decoding will +only work if the URI components are ASCII or UTF-8, so you will +need to use %G_URI_FLAGS_ENCODED if they are not. + +Note that the %G_URI_FLAGS_HAS_PASSWORD and +%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), +since it always returns only the full userinfo; use +g_uri_split_with_user() if you want it split up. + + + %TRUE if @uri_ref parsed successfully, %FALSE + on error. + + + + + a string containing a relative or absolute URI + + + + flags for parsing @uri_ref + + + + on return, contains + the scheme (converted to lowercase), or %NULL + + + + on return, contains + the userinfo, or %NULL + + + + on return, contains the + host, or %NULL + + + + on return, contains the + port, or `-1` + + + + on return, contains the + path + + + + on return, contains the + query, or %NULL + + + + on return, contains + the fragment, or %NULL + + + + + + Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) +according to @flags, and returns the pieces relevant to connecting to a host. +See the documentation for g_uri_split() for more details; this is +mostly a wrapper around that function with simpler arguments. +However, it will return an error if @uri_string is a relative URI, +or does not contain a hostname component. + + + %TRUE if @uri_string parsed successfully, + %FALSE on error. + + + + + a string containing an absolute URI + + + + flags for parsing @uri_string + + + + on return, contains + the scheme (converted to lowercase), or %NULL + + + + on return, contains the + host, or %NULL + + + + on return, contains the + port, or `-1` + + + + + + Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags. Note that @password will only +be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and +@auth_params will only be parsed out if @flags contains +%G_URI_FLAGS_HAS_AUTH_PARAMS. + + + %TRUE if @uri_ref parsed successfully, %FALSE + on error. + + + + + a string containing a relative or absolute URI + + + + flags for parsing @uri_ref + + + + on return, contains + the scheme (converted to lowercase), or %NULL + + + + on return, contains + the user, or %NULL + + + + on return, contains + the password, or %NULL + + + + on return, contains + the auth_params, or %NULL + + + + on return, contains the + host, or %NULL + + + + on return, contains the + port, or `-1` + + + + on return, contains the + path + + + + on return, contains the + query, or %NULL + + + + on return, contains + the fragment, or %NULL + + + + + + Unescapes a segment of an escaped string as binary data. + +Note that in contrast to g_uri_unescape_string(), this does allow +nul bytes to appear in the output. + +If any of the characters in @illegal_characters 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 or %NULL on + error (if decoding failed, using %G_URI_ERROR_FAILED error code). The + returned #GBytes should be unreffed when no longer needed. + + + + + A URI-escaped string + + + + the length (in bytes) of @escaped_string to escape, or `-1` if it + is nul-terminated. + + + + a string of illegal characters + not to be allowed, or %NULL. + + + + + + Unescapes a segment of an escaped string. + +If any of the characters in @illegal_characters or the NUL +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. + +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. + + + + + A string, may be %NULL + + + + Pointer to end of @escaped_string, + may be %NULL + + + + An optional string of illegal + characters not to be allowed, may be %NULL + + + + + + Unescapes a whole escaped string. + +If any of the characters in @illegal_characters or the NUL +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 escaped string to be unescaped. + + + + a string of illegal characters + not to be allowed, or %NULL. + + + + + + + Error codes returned by #GUri methods. + + + Generic error if no more specific error is available. + See the error message for details. + + + The scheme of a URI could not be parsed. + + + The user/userinfo of a URI could not be parsed. + + + The password of a URI could not be parsed. + + + The authentication parameters of a URI could not be parsed. + + + The host of a URI could not be parsed. + + + The port of a URI could not be parsed. + + + The path of a URI could not be parsed. + + + The query of a URI could not be parsed. + + + The fragment of a URI could not be parsed. + + + + Flags that describe a URI. + +When parsing a URI, if you need to choose different flags based on +the type of URI, you can use g_uri_peek_scheme() on the URI string +to check the scheme first, and use that to decide what flags to +parse it with. + + + No flags set. + + + Parse the URI more relaxedly than the + [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies, + fixing up or ignoring common mistakes in URIs coming from external + sources. This is also needed for some obscure URI schemes where `;` + separates the host from the path. Don’t use this flag unless you need to. + + + The userinfo field may contain a password, + which will be separated from the username by `:`. + + + The userinfo may contain additional + authentication-related parameters, which will be separated from + the username and/or password by `;`. + + + When parsing a URI, this indicates that `%`-encoded + characters in the userinfo, path, query, and fragment fields + should not be decoded. (And likewise the host field if + %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates + that you have already `%`-encoded the components, and so #GUri + should not do any encoding itself. + + + The host component should not be assumed to be a + DNS hostname or IP address (for example, for `smb` URIs with NetBIOS + hostnames). + + + Same as %G_URI_FLAGS_ENCODED, for the query + field only. + + + Same as %G_URI_FLAGS_ENCODED, for the path only. + + + Same as %G_URI_FLAGS_ENCODED, for the + fragment only. + + + + Flags describing what parts of the URI to hide in +g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and +%G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with +the corresponding flags. + + + No flags set. + + + Hide the userinfo. + + + Hide the password. + + + Hide the auth_params. + + + Hide the query. + + + Hide the fragment. + + + + Flags modifying the way parameters are handled by g_uri_parse_params() and +#GUriParamsIter. + + + No flags set. + + + Parameter names are case insensitive. + + + Replace `+` with space character. Only useful for + URLs on the web, using the `https` or `http` schemas. + + + See %G_URI_FLAGS_PARSE_RELAXED. + + + + Many URI schemes include one or more attribute/value pairs as part of the URI +value. For example `scheme://server/path?query=string&is=there` has two +attributes – `query=string` and `is=there` – in its query part. + +A #GUriParamsIter structure represents an iterator that can be used to +iterate over the attribute/value pairs of a URI query string. #GUriParamsIter +structures are typically allocated on the stack and then initialized with +g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init() +for a usage example. + + + + + + + + + + + + + + + + + Initializes an attribute/value pair iterator. + +The iterator keeps pointers to the @params and @separators arguments, those +variables must thus outlive the iterator and not be modified during the +iteration. + +If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param +string will be replaced with spaces in the output. For example, `foo=bar+baz` +will give attribute `foo` with value `bar baz`. This is commonly used on the +web (the `https` and `http` schemes only), but is deprecated in favour of +the equivalent of encoding spaces as `%20`. + +Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no +effect if passed to @flags for g_uri_params_iter_init(). The caller is +responsible for doing their own case-insensitive comparisons. + +|[<!-- language="C" --> +GUriParamsIter iter; +GError *error = NULL; +gchar *unowned_attr, *unowned_value; + +g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE); +while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error)) + { + g_autofree gchar *attr = g_steal_pointer (&unowned_attr); + g_autofree gchar *value = g_steal_pointer (&unowned_value); + // do something with attr and value; this code will be called 4 times + // for the params string in this example: once with attr=foo and value=bar, + // then with baz/bar, then Foo/frob, then baz/bar2. + } +if (error) + // handle parsing error +]| + + + + + + + an uninitialized #GUriParamsIter + + + + a `%`-encoded string containing `attribute=value` + parameters + + + + the length of @params, or `-1` if it is nul-terminated + + + + the separator byte character set between parameters. (usually + `&`, but sometimes `;` or both `&;`). Note that this function works on + bytes not characters, so it can't be used to delimit UTF-8 strings for + anything but ASCII characters. You may pass an empty set, in which case + no splitting will occur. + + + + flags to modify the way the parameters are handled. + + + + + + Advances @iter and retrieves the next attribute/value. %FALSE is returned if +an error has occurred (in which case @error is set), or if the end of the +iteration is reached (in which case @attribute and @value are set to %NULL +and the iterator becomes invalid). If %TRUE is returned, +g_uri_params_iter_next() may be called again to receive another +attribute/value pair. + +Note that the same @attribute may be returned multiple times, since URIs +allow repeated attributes. + + + %FALSE if the end of the parameters has been reached or an error was + encountered. %TRUE otherwise. + + + + + an initialized #GUriParamsIter + + + + on return, contains + the attribute, or %NULL. + + + + on return, contains + the value, or %NULL. + + + + + These are logical ids for special directories which are defined depending on the platform used. You should use g_get_user_special_dir() @@ -31201,6 +32984,12 @@ in the container. See g_variant_n_children(). The returned value is never floating. You should free it with g_variant_unref() when you're done with it. +Note that values borrowed from the returned child are not guaranteed to +still be valid after the child is freed even if you still hold a reference +to @value, if @value has not been serialised at the time this function is +called. To avoid this, you can serialize @value by calling +g_variant_get_data() and optionally ignoring the return value. + There may be implementation specific restrictions on deeply nested values, which would result in the unit tuple being returned as the child value, instead of further nested children. #GVariant is guaranteed to handle @@ -31526,11 +33315,15 @@ involved. type. This includes the types %G_VARIANT_TYPE_STRING, %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE. -The string will always be UTF-8 encoded, and will never be %NULL. +The string will always be UTF-8 encoded, will never be %NULL, and will never +contain nul bytes. If @length is non-%NULL then the length of the string (in bytes) is returned there. For trusted values, this information is already -known. For untrusted values, a strlen() will be performed. +known. Untrusted values will be validated and, if valid, a strlen() will be +performed. If invalid, a default value will be returned — for +%G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the +empty string. It is an error to call this function with a @value of any type other than those three. @@ -32106,7 +33899,7 @@ reference. Using this function on the return value of the user's callback allows the user to do whichever is more convenient for them. The caller -will alway receives exactly one full reference to the value: either +will always receives exactly one full reference to the value: either the one that was returned in the first place, or a floating reference that has been converted to a full reference. @@ -33171,7 +34964,7 @@ Use g_variant_iter_free() to free the return value when you no longer need it. A reference is taken to the container that @iter is iterating over -and will be releated only when g_variant_iter_free() is called. +and will be related only when g_variant_iter_free() is called. a new heap-allocated #GVariantIter @@ -34387,6 +36180,124 @@ Thus it provides the same advantages and pitfalls as alloca(): + + An "atomically reference counted box", or "ArcBox", is an opaque wrapper +data type that is guaranteed to be as big as the size of a given data type, +and which augments the given data type with thread safe reference counting +semantics for its memory management. + +ArcBox is useful if you have a plain old data type, like a structure +typically placed on the stack, and you wish to provide additional API +to use it on the heap; or if you want to implement a new type to be +passed around by reference without necessarily implementing copy/free +semantics or your own reference counting. + +The typical use is: + +|[<!-- language="C" --> +typedef struct { + char *name; + char *address; + char *city; + char *state; + int age; +} Person; + +Person * +person_new (void) +{ + return g_atomic_rc_box_new0 (Person); +} +]| + +Every time you wish to acquire a reference on the memory, you should +call g_atomic_rc_box_acquire(); similarly, when you wish to release a reference +you should call g_atomic_rc_box_release(): + +|[<!-- language="C" --> +// Add a Person to the Database; the Database acquires ownership +// of the Person instance +void +add_person_to_database (Database *db, Person *p) +{ + db->persons = g_list_prepend (db->persons, g_atomic_rc_box_acquire (p)); +} + +// Removes a Person from the Database; the reference acquired by +// add_person_to_database() is released here +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_atomic_rc_box_release (p); +} +]| + +If you have additional memory allocated inside the structure, you can +use g_atomic_rc_box_release_full(), which takes a function pointer, which +will be called if the reference released was the last: + +|[<!-- language="C" --> +void +person_clear (Person *p) +{ + g_free (p->name); + g_free (p->address); + g_free (p->city); + g_free (p->state); +} + +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_atomic_rc_box_release_full (p, (GDestroyNotify) person_clear); +} +]| + +If you wish to transfer the ownership of a reference counted data +type without increasing the reference count, you can use g_steal_pointer(): + +|[<!-- language="C" --> + Person *p = g_atomic_rc_box_new (Person); + + fill_person_details (p); + + add_person_to_database (db, g_steal_pointer (&p)); +]| + +## Thread safety + +The reference counting operations on data allocated using g_atomic_rc_box_alloc(), +g_atomic_rc_box_new(), and g_atomic_rc_box_dup() are guaranteed to be atomic, and thus +can be safely be performed by different threads. It is important to note that +only the reference acquisition and release are atomic; changes to the content +of the data are your responsibility. + +## Automatic pointer clean up + +If you want to add g_autoptr() support to your plain old data type through +reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and +g_atomic_rc_box_release(): + +|[<!-- language="C" --> +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_atomic_rc_box_release) +]| + +If you need to clear the contents of the data, you will need to use an +ancillary function that calls g_rc_box_release_full(): + +|[<!-- language="C" --> +static void +my_data_struct_release (MyDataStruct *data) +{ + // my_data_struct_clear() is defined elsewhere + g_atomic_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); +} + +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) +]| + Adds the value on to the end of the array. The array will grow in size automatically if necessary. @@ -34406,14 +36317,29 @@ such as "27". You must use variables. Returns the element of a #GArray at the given index. The return -value is cast to the given type. +value is cast to the given type. This is the main way to read or write an +element in a #GArray. -This example gets a pointer to an element in a #GArray: +Writing an element is typically done by reference, as in the following +example. This example gets a pointer to an element in a #GArray, and then +writes to a field in it: |[<!-- language="C" --> EDayViewEvent *event; // This gets a pointer to the 4th element in the array of // EDayViewEvent structs. event = &g_array_index (events, EDayViewEvent, 3); + event->start_time = g_get_current_time (); +]| + +This example reads from and writes to an array of integers: +|[<!-- language="C" --> + g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint)); + for (guint i = 0; i < 10; i++) + g_array_append_val (int_array, i); + + guint *my_int = &g_array_index (int_array, guint, 1); + g_print ("Int at index 1 is %u; decrementing it\n", *my_int); + *my_int = *my_int - 1; ]| @@ -34468,6 +36394,123 @@ such as "27". You must use variables. + + Arrays are similar to standard C arrays, except that they grow +automatically as elements are added. + +Array elements can be of any size (though all elements of one array +are the same size), and the array can be automatically cleared to +'0's and zero-terminated. + +To create a new array use g_array_new(). + +To add elements to an array with a cost of O(n) at worst, use +g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), +g_array_prepend_vals(), g_array_insert_val() and g_array_insert_vals(). + +To access an element of an array in O(1) (to read it or to write it), +use g_array_index(). + +To set the size of an array, use g_array_set_size(). + +To free an array, use g_array_unref() or g_array_free(). + +All the sort functions are internally calling a quick-sort (or similar) +function with an average cost of O(n log(n)) and a worst case +cost of O(n^2). + +Here is an example that stores integers in a #GArray: +|[<!-- language="C" --> + GArray *garray; + gint i; + // We create a new array to store gint values. + // We don't want it zero-terminated or cleared to 0's. + garray = g_array_new (FALSE, FALSE, sizeof (gint)); + for (i = 0; i < 10000; i++) + g_array_append_val (garray, i); + for (i = 0; i < 10000; i++) + if (g_array_index (garray, gint, i) != i) + g_print ("ERROR: got %d instead of %d\n", + g_array_index (garray, gint, i), i); + g_array_free (garray, TRUE); +]| + + + #GByteArray is a mutable array of bytes based on #GArray, to provide arrays +of bytes which grow automatically as elements are added. + +To create a new #GByteArray use g_byte_array_new(). To add elements to a +#GByteArray, use g_byte_array_append(), and g_byte_array_prepend(). + +To set the size of a #GByteArray, use g_byte_array_set_size(). + +To free a #GByteArray, use g_byte_array_free(). + +An example for using a #GByteArray: +|[<!-- language="C" --> + GByteArray *gbarray; + gint i; + + gbarray = g_byte_array_new (); + for (i = 0; i < 10000; i++) + g_byte_array_append (gbarray, (guint8*) "abcd", 4); + + for (i = 0; i < 10000; i++) + { + g_assert (gbarray->data[4*i] == 'a'); + g_assert (gbarray->data[4*i+1] == 'b'); + g_assert (gbarray->data[4*i+2] == 'c'); + g_assert (gbarray->data[4*i+3] == 'd'); + } + + g_byte_array_free (gbarray, TRUE); +]| + +See #GBytes if you are interested in an immutable object representing a +sequence of bytes. + + + Pointer Arrays are similar to Arrays but are used only for storing +pointers. + +If you remove elements from the array, elements at the end of the +array are moved into the space previously occupied by the removed +element. This means that you should not rely on the index of particular +elements remaining the same. You should also be careful when deleting +elements while iterating over the array. + +To create a pointer array, use g_ptr_array_new(). + +To add elements to a pointer array, use g_ptr_array_add(). + +To remove elements from a pointer array, use g_ptr_array_remove(), +g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). + +To access an element of a pointer array, use g_ptr_array_index(). + +To set the size of a pointer array, use g_ptr_array_set_size(). + +To free a pointer array, use g_ptr_array_free(). + +An example using a #GPtrArray: +|[<!-- language="C" --> + GPtrArray *array; + gchar *string1 = "one"; + gchar *string2 = "two"; + gchar *string3 = "three"; + + array = g_ptr_array_new (); + g_ptr_array_add (array, (gpointer) string1); + g_ptr_array_add (array, (gpointer) string2); + g_ptr_array_add (array, (gpointer) string3); + + if (g_ptr_array_index (array, 0) != (gpointer) string1) + g_print ("ERROR: got %p instead of %p\n", + g_ptr_array_index (array, 0), string1); + + g_ptr_array_free (array, TRUE); +]| + Determines the numeric value of a character as a decimal digit. Differs from g_unichar_digit_value() because it takes a char, so @@ -35099,7 +37142,7 @@ before passing a possibly non-ASCII character in. - Determines the numeric value of a character as a hexidecimal + Determines the numeric value of a character as a hexadecimal digit. Differs from g_unichar_xdigit_value() because it takes a char, so there's no worry about sign extension if characters are signed. @@ -35360,6 +37403,24 @@ See g_test_set_nonfatal_assertions(). + + Debugging macro to check that an expression has a non-negative return value, +as used by traditional POSIX functions (such as `rmdir()`) to indicate +success. + +If the assertion fails (i.e. the @expr returns a negative value), an error +message is logged and the testcase is marked as failed. The error message +will contain the value of `errno` and its human-readable message from +g_strerror(). + +This macro will clear the value of `errno` before executing @expr. + + + + the expression to check + + + Debugging macro to check that a #GError is not set. @@ -35606,6 +37667,49 @@ g_assert_not_reached() macros. + + Often you need to communicate between different threads. In general +it's safer not to do this by shared memory, but by explicit message +passing. These messages only make sense asynchronously for +multi-threaded applications though, as a synchronous operation could +as well be done in the same thread. + +Asynchronous queues are an exception from most other GLib data +structures, as they can be used simultaneously from multiple threads +without explicit locking and they bring their own builtin reference +counting. This is because the nature of an asynchronous queue is that +it will always be used by at least 2 concurrent threads. + +For using an asynchronous queue you first have to create one with +g_async_queue_new(). #GAsyncQueue structs are reference counted, +use g_async_queue_ref() and g_async_queue_unref() to manage your +references. + +A thread which wants to send a message to that queue simply calls +g_async_queue_push() to push the message to the queue. + +A thread which is expecting messages from an asynchronous queue +simply calls g_async_queue_pop() for that queue. If no message is +available in the queue at that point, the thread is now put to sleep +until a message arrives. The message will be removed from the queue +and returned. The functions g_async_queue_try_pop() and +g_async_queue_timeout_pop() can be used to only check for the presence +of messages or to only wait a certain time for messages respectively. + +For almost every function there exist two variants, one that locks +the queue and one that doesn't. That way you can hold the queue lock +(acquire it with g_async_queue_lock() and release it with +g_async_queue_unlock()) over multiple queue accessing instructions. +This can be necessary to ensure the integrity of the queue, but should +only be used when really necessary, as it can make your life harder +if used unwisely. Normally you should only use the locking function +variants (those without the _unlocked suffix). + +In many cases, it may be more convenient to use #GThreadPool when +you need to distribute work to a set of worker threads instead of +using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue +internally. + Specifies a function to be called at normal program termination. @@ -35871,6 +37975,43 @@ This call acts as a full compiler and hardware memory barrier. + + The following is a collection of compiler macros to provide atomic +access to integer and pointer-sized values. + +The macros that have 'int' in the name will operate on pointers to +#gint and #guint. The macros with 'pointer' in the name will operate +on pointers to any pointer-sized value, including #gsize. There is +no support for 64bit operations on platforms with 32bit pointers +because it is not generally possible to perform these operations +atomically. + +The get, set and exchange operations for integers and pointers +nominally operate on #gint and #gpointer, respectively. Of the +arithmetic operations, the 'add' operation operates on (and returns) +signed integer values (#gint and #gssize) and the 'and', 'or', and +'xor' operations operate on (and return) unsigned integer values +(#guint and #gsize). + +All of the operations act as a full compiler and (where appropriate) +hardware memory barrier. Acquire and release or producer and +consumer barrier semantics are not available through this API. + +It is very important that all accesses to a particular integer or +pointer be performed using only this API and that different sizes of +operation are not mixed or used on overlapping memory regions. Never +read or assign directly from or to a value -- always use this API. + +For simple reference counting purposes you should use +g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that +fall outside of simple reference counting patterns are prone to +subtle bugs and occasionally undefined behaviour. It is also worth +noting that since all of these operations require global +synchronisation of the entire machine, they can be quite slow. In +the case of performing multiple atomic operations it can often be +faster to simply acquire a mutex lock around the critical area, +perform the operations normally and then release the lock. + Atomically adds @val to the value of @atomic. @@ -36071,7 +38212,7 @@ built-in type. Allocates @block_size bytes of memory, and adds atomic -referenc counting semantics to it. +reference counting semantics to it. The contents of the returned data is set to zero. @@ -36252,6 +38393,24 @@ resources allocated for @mem_block. + + Base64 is an encoding that allows a sequence of arbitrary bytes to be +encoded as a sequence of printable ASCII characters. For the definition +of Base64, see +[RFC 1421](http://www.ietf.org/rfc/rfc1421.txt) +or +[RFC 2045](http://www.ietf.org/rfc/rfc2045.txt). +Base64 is most commonly used as a MIME transfer encoding +for email. + +GLib supports incremental encoding using g_base64_encode_step() and +g_base64_encode_close(). Incremental decoding can be done with +g_base64_decode_step(). To encode or decode data in one go, use +g_base64_encode() or g_base64_decode(). To avoid memory allocation when +decoding, you can use g_base64_decode_inplace(). + +Support for Base64 encoding has been added in GLib 2.12. + Decode a sequence of Base-64 encoded text into binary data. Note that the returned binary data is not necessarily zero-terminated, @@ -36621,6 +38780,46 @@ reliably. + + GBookmarkFile lets you parse, edit or create files containing bookmarks +to URI, along with some meta-data about the resource pointed by the URI +like its MIME type, the application that is registering the bookmark and +the icon that should be used to represent the bookmark. The data is stored +using the +[Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec). + +The syntax of the bookmark files is described in detail inside the +Desktop Bookmark Specification, here is a quick summary: bookmark +files use a sub-class of the XML Bookmark Exchange Language +specification, consisting of valid UTF-8 encoded XML, under the +<xbel> root element; each bookmark is stored inside a +<bookmark> element, using its URI: no relative paths can +be used inside a bookmark file. The bookmark may have a user defined +title and description, to be used instead of the URI. Under the +<metadata> element, with its owner attribute set to +`http://freedesktop.org`, is stored the meta-data about a resource +pointed by its URI. The meta-data consists of the resource's MIME +type; the applications that have registered a bookmark; the groups +to which a bookmark belongs to; a visibility flag, used to set the +bookmark as "private" to the applications and groups that has it +registered; the URI and MIME type of an icon, to be used when +displaying the bookmark inside a GUI. + +Here is an example of a bookmark file: +[bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel) + +A bookmark file might contain more than one bookmark; each bookmark +is accessed through its URI. + +The important caveat of bookmark files is that when you add a new +bookmark you must also add the application that is registering it, using +g_bookmark_file_add_application() or g_bookmark_file_set_application_info(). +If a bookmark has no applications then it won't be dumped when creating +the on disk representation, using g_bookmark_file_to_data() or +g_bookmark_file_to_file(). + +The #GBookmarkFile parser was added in GLib 2.12. + Creates a filename from a series of elements using the correct separator for filenames. @@ -36889,6 +39088,36 @@ thread. + + These macros provide a portable way to determine the host byte order +and to convert values between different byte orders. + +The byte order is the order in which bytes are stored to create larger +data types such as the #gint and #glong values. +The host byte order is the byte order used on the current machine. + +Some processors store the most significant bytes (i.e. the bytes that +hold the largest part of the value) first. These are known as big-endian +processors. Other processors (notably the x86 family) store the most +significant byte last. These are known as little-endian processors. + +Finally, to complicate matters, some other processors store the bytes in +a rather curious order known as PDP-endian. For a 4-byte word, the 3rd +most significant byte is stored first, then the 4th, then the 1st and +finally the 2nd. + +Obviously there is a problem when these different processors communicate +with each other, for example over networks or by using binary file formats. +This is where these macros come in. They are typically used to convert +values into a byte order which has been agreed on for use when +communicating between different processors. The Internet uses what is +known as 'network byte order' as the standard byte order (which is in +fact the big-endian byte order). + +Note that the byte order conversion macros may evaluate their arguments +multiple times, thus you should not use them with arguments which have +side-effects. + Gets the canonical file name from @filename. All triple slashes are turned into single slashes, and all `..` and `.`s resolved against @relative_to. @@ -36978,6 +39207,38 @@ version @required_major.required_minor.@required_micro + + GLib offers a set of macros for doing additions and multiplications +of unsigned integers, with checks for overflows. + +The helpers all have three arguments. A pointer to the destination +is always the first argument and the operands to the operation are +the other two. + +Following standard GLib convention, the helpers return %TRUE in case +of success (ie: no overflow). + +The helpers may be macros, normal functions or inlines. They may be +implemented with inline assembly or compiler intrinsics where +available. + + + GLib provides a generic API for computing checksums (or "digests") +for a sequence of arbitrary bytes, using various hashing algorithms +like MD5, SHA-1 and SHA-256. Checksums are commonly used in various +environments and specifications. + +GLib supports incremental checksums using the GChecksum data +structure, by calling g_checksum_update() as long as there's data +available and then using g_checksum_get_string() or +g_checksum_get_digest() to compute the checksum and return it either +as a string in hexadecimal form, or as a raw sequence of bytes. To +compute the checksum for binary blobs and NUL-terminated strings in +one go, use the convenience functions g_compute_checksum_for_data() +and g_compute_checksum_for_string(), respectively. + +Support for checksums has been added in GLib 2.16 + Gets the length in bytes of digests of type @checksum_type @@ -37443,6 +39704,100 @@ The hexadecimal string returned will be in lower case. + + The g_convert() family of function wraps the functionality of iconv(). +In addition to pure character set conversions, GLib has functions to +deal with the extra complications of encodings for file names. + +## File Name Encodings + +Historically, UNIX has not had a defined encoding for file names: +a file name is valid as long as it does not have path separators +in it ("/"). However, displaying file names may require conversion: +from the character set in which they were created, to the character +set in which the application operates. Consider the Spanish file name +"Presentación.sxi". If the application which created it uses +ISO-8859-1 for its encoding, +|[ +Character: P r e s e n t a c i ó n . s x i +Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69 +]| +However, if the application use UTF-8, the actual file name on +disk would look like this: +|[ +Character: P r e s e n t a c i ó n . s x i +Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69 +]| +Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use +GLib do the same thing. If you get a file name from the file system, +for example, from readdir() or from g_dir_read_name(), and you wish +to display the file name to the user, you will need to convert it +into UTF-8. The opposite case is when the user types the name of a +file they wish to save: the toolkit will give you that string in +UTF-8 encoding, and you will need to convert it to the character +set used for file names before you can create the file with open() +or fopen(). + +By default, GLib assumes that file names on disk are in UTF-8 +encoding. This is a valid assumption for file systems which +were created relatively recently: most applications use UTF-8 +encoding for their strings, and that is also what they use for +the file names they create. However, older file systems may +still contain file names created in "older" encodings, such as +ISO-8859-1. In this case, for compatibility reasons, you may want +to instruct GLib to use that particular encoding for file names +rather than UTF-8. You can do this by specifying the encoding for +file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING] +environment variable. For example, if your installation uses +ISO-8859-1 for file names, you can put this in your `~/.profile`: +|[ +export G_FILENAME_ENCODING=ISO-8859-1 +]| +GLib provides the functions g_filename_to_utf8() and +g_filename_from_utf8() to perform the necessary conversions. +These functions convert file names from the encoding specified +in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This +[diagram][file-name-encodings-diagram] illustrates how +these functions are used to convert between UTF-8 and the +encoding for file names in the file system. + +## Conversion between file name encodings # {#file-name-encodings-diagram) + +![](file-name-encodings.png) + +## Checklist for Application Writers + +This section is a practical summary of the detailed +things to do to make sure your applications process file +name encodings correctly. + +1. If you get a file name from the file system from a function + such as readdir() or gtk_file_chooser_get_filename(), you do + not need to do any conversion to pass that file name to + functions like open(), rename(), or fopen() -- those are "raw" + file names which the file system understands. + +2. If you need to display a file name, convert it to UTF-8 first + by using g_filename_to_utf8(). If conversion fails, display a + string like "Unknown file name". Do not convert this string back + into the encoding used for file names if you wish to pass it to + the file system; use the original file name instead. + + For example, the document window of a word processor could display + "Unknown file name" in its title bar but still let the user save + the file, as it would keep the raw file name internally. This + can happen if the user has not set the `G_FILENAME_ENCODING` + environment variable even though he has files whose names are + not encoded in UTF-8. + +3. If your user interface lets the user type a file name for saving + or renaming, convert it to the encoding used for file names in + the file system by using g_filename_from_utf8(). Pass the converted + file name to functions like fopen(). If conversion fails, ask the + user to enter a different file name. This can happen if the user + types Japanese characters when `G_FILENAME_ENCODING` is set to + `ISO-8859-1`, for example. + Converts a string from one character set to another. @@ -37655,6 +40010,34 @@ unrepresentable characters, use g_convert_with_fallback(). + + Keyed data lists provide lists of arbitrary data elements which can +be accessed either with a string or with a #GQuark corresponding to +the string. + +The #GQuark methods are quicker, since the strings have to be +converted to #GQuarks anyway. + +Data lists are used for associating arbitrary data with #GObjects, +using g_object_set_data() and related functions. + +To create a datalist, use g_datalist_init(). + +To add data elements to a datalist use g_datalist_id_set_data(), +g_datalist_id_set_data_full(), g_datalist_set_data() and +g_datalist_set_data_full(). + +To get data elements from a datalist use g_datalist_id_get_data() +and g_datalist_get_data(). + +To iterate over all data elements in a datalist use +g_datalist_foreach() (not thread-safe). + +To remove data elements from a datalist use +g_datalist_id_remove_data() and g_datalist_remove_data(). + +To remove all data elements from a datalist, use g_datalist_clear(). + Frees all the data elements of the datalist. The data elements' destroy functions are called @@ -38264,6 +40647,80 @@ function to call when the data element is destroyed. + + Datasets associate groups of data elements with particular memory +locations. These are useful if you need to associate data with a +structure returned from an external library. Since you cannot modify +the structure, you use its location in memory as the key into a +dataset, where you can associate any number of data elements with it. + +There are two forms of most of the dataset functions. The first form +uses strings to identify the data elements associated with a +location. The second form uses #GQuark identifiers, which are +created with a call to g_quark_from_string() or +g_quark_from_static_string(). The second form is quicker, since it +does not require looking up the string in the hash table of #GQuark +identifiers. + +There is no function to create a dataset. It is automatically +created as soon as you add elements to it. + +To add data elements to a dataset use g_dataset_id_set_data(), +g_dataset_id_set_data_full(), g_dataset_set_data() and +g_dataset_set_data_full(). + +To get data elements from a dataset use g_dataset_id_get_data() and +g_dataset_get_data(). + +To iterate over all data elements in a dataset use +g_dataset_foreach() (not thread-safe). + +To remove data elements from a dataset use +g_dataset_id_remove_data() and g_dataset_remove_data(). + +To destroy a dataset, use g_dataset_destroy(). + + + The #GDate data structure represents a day between January 1, Year 1, +and sometime a few thousand years in the future (right now it will go +to the year 65535 or so, but g_date_set_parse() only parses up to the +year 8000 or so - just count on "a few thousand"). #GDate is meant to +represent everyday dates, not astronomical dates or historical dates +or ISO timestamps or the like. It extrapolates the current Gregorian +calendar forward and backward in time; there is no attempt to change +the calendar to match time periods or locations. #GDate does not store +time information; it represents a day. + +The #GDate implementation has several nice features; it is only a +64-bit struct, so storing large numbers of dates is very efficient. It +can keep both a Julian and day-month-year representation of the date, +since some calculations are much easier with one representation or the +other. A Julian representation is simply a count of days since some +fixed day in the past; for #GDate the fixed day is January 1, 1 AD. +("Julian" dates in the #GDate API aren't really Julian dates in the +technical sense; technically, Julian dates count from the start of the +Julian period, Jan 1, 4713 BC). + +#GDate is simple to use. First you need a "blank" date; you can get a +dynamically allocated date from g_date_new(), or you can declare an +automatic variable or array and initialize it by +calling g_date_clear(). A cleared date is safe; it's safe to call +g_date_set_dmy() and the other mutator functions to initialize the +value of a cleared date. However, a cleared date is initially +invalid, meaning that it doesn't represent a day that exists. +It is undefined to call any of the date calculation routines on an +invalid date. If you obtain a date from a user or other +unpredictable source, you should check its validity with the +g_date_valid() predicate. g_date_valid() is also used to check for +errors with g_date_set_parse() and other functions that can +fail. Dates can be invalidated by calling g_date_clear() again. + +It is very important to use the API to access the #GDate +struct. Often only the day-month-year or only the Julian +representation is valid. Sometimes neither is valid. Use the API. + +GLib also features #GDateTime which represents a precise time. + Returns the number of days in a month, taking leap years into account. @@ -38534,6 +40991,33 @@ though there is a 16-bit limit to what #GDate will understand. + + #GDateTime is a structure that combines a Gregorian date and time +into a single structure. It provides many conversion and methods to +manipulate dates and times. Time precision is provided down to +microseconds and the time can range (proleptically) from 0001-01-01 +00:00:00 to 9999-12-31 23:59:59.999999. #GDateTime follows POSIX +time in the sense that it is oblivious to leap seconds. + +#GDateTime is an immutable object; once it has been created it cannot +be modified further. All modifiers will create a new #GDateTime. +Nearly all such functions can fail due to the date or time going out +of range, in which case %NULL will be returned. + +#GDateTime is reference counted: the reference count is increased by calling +g_date_time_ref() and decreased by calling g_date_time_unref(). When the +reference count drops to 0, the resources allocated by the #GDateTime +structure are released. + +Many parts of the API may produce non-obvious results. As an +example, adding two months to January 31st will yield March 31st +whereas adding one month and then one month again will yield either +March 28th or March 29th. Also note that adding 24 hours is not +always the same as adding one day (since days containing daylight +savings time transitions are either 23 or 25 hours in length). + +#GDateTime is available since GLib 2.26. + This is a variant of g_dgettext() that allows specifying a locale category instead of always using `LC_MESSAGES`. See g_dgettext() for @@ -38910,6 +41394,353 @@ environment @envp. + + GLib provides a standard method of reporting errors from a called +function to the calling code. (This is the same problem solved by +exceptions in other languages.) It's important to understand that +this method is both a data type (the #GError struct) and a [set of +rules][gerror-rules]. If you use #GError incorrectly, then your code will not +properly interoperate with other code that uses #GError, and users +of your API will probably get confused. In most cases, [using #GError is +preferred over numeric error codes][gerror-comparison], but there are +situations where numeric error codes are useful for performance. + +First and foremost: #GError should only be used to report recoverable +runtime errors, never to report programming errors. If the programmer +has screwed up, then you should use g_warning(), g_return_if_fail(), +g_assert(), g_error(), or some similar facility. (Incidentally, +remember that the g_error() function should only be used for +programming errors, it should not be used to print any error +reportable via #GError.) + +Examples of recoverable runtime errors are "file not found" or +"failed to parse input." Examples of programming errors are "NULL +passed to strcmp()" or "attempted to free the same pointer twice." +These two kinds of errors are fundamentally different: runtime errors +should be handled or reported to the user, programming errors should +be eliminated by fixing the bug in the program. This is why most +functions in GLib and GTK+ do not use the #GError facility. + +Functions that can fail take a return location for a #GError as their +last argument. On error, a new #GError instance will be allocated and +returned to the caller via this argument. For example: +|[<!-- language="C" --> +gboolean g_file_get_contents (const gchar *filename, + gchar **contents, + gsize *length, + GError **error); +]| +If you pass a non-%NULL value for the `error` argument, it should +point to a location where an error can be placed. For example: +|[<!-- language="C" --> +gchar *contents; +GError *err = NULL; + +g_file_get_contents ("foo.txt", &contents, NULL, &err); +g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); +if (err != NULL) + { + // Report error to user, and free error + g_assert (contents == NULL); + fprintf (stderr, "Unable to read file: %s\n", err->message); + g_error_free (err); + } +else + { + // Use file contents + g_assert (contents != NULL); + } +]| +Note that `err != NULL` in this example is a reliable indicator +of whether g_file_get_contents() failed. Additionally, +g_file_get_contents() returns a boolean which +indicates whether it was successful. + +Because g_file_get_contents() returns %FALSE on failure, if you +are only interested in whether it failed and don't need to display +an error message, you can pass %NULL for the @error argument: +|[<!-- language="C" --> +if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors + // no error occurred + ; +else + // error + ; +]| + +The #GError object contains three fields: @domain indicates the module +the error-reporting function is located in, @code indicates the specific +error that occurred, and @message is a user-readable error message with +as many details as possible. Several functions are provided to deal +with an error received from a called function: g_error_matches() +returns %TRUE if the error matches a given domain and code, +g_propagate_error() copies an error into an error location (so the +calling function will receive it), and g_clear_error() clears an +error location by freeing the error and resetting the location to +%NULL. To display an error to the user, simply display the @message, +perhaps along with additional context known only to the calling +function (the file being opened, or whatever - though in the +g_file_get_contents() case, the @message already contains a filename). + +Note, however, that many error messages are too technical to display to the +user in an application, so prefer to use g_error_matches() to categorize errors +from called functions, and build an appropriate error message for the context +within your application. Error messages from a #GError are more appropriate +to be printed in system logs or on the command line. They are typically +translated. + +When implementing a function that can report errors, the basic +tool is g_set_error(). Typically, if a fatal error occurs you +want to g_set_error(), then return immediately. g_set_error() +does nothing if the error location passed to it is %NULL. +Here's an example: +|[<!-- language="C" --> +gint +foo_open_file (GError **error) +{ + gint fd; + int saved_errno; + + g_return_val_if_fail (error == NULL || *error == NULL, -1); + + fd = open ("file.txt", O_RDONLY); + saved_errno = errno; + + if (fd < 0) + { + g_set_error (error, + FOO_ERROR, // error domain + FOO_ERROR_BLAH, // error code + "Failed to open file: %s", // error message format string + g_strerror (saved_errno)); + return -1; + } + else + return fd; +} +]| + +Things are somewhat more complicated if you yourself call another +function that can report a #GError. If the sub-function indicates +fatal errors in some way other than reporting a #GError, such as +by returning %TRUE on success, you can simply do the following: +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + if (!sub_function_that_can_fail (err)) + { + // assert that error was set by the sub-function + g_assert (err == NULL || *err != NULL); + return FALSE; + } + + // otherwise continue, no error occurred + g_assert (err == NULL || *err == NULL); +} +]| + +If the sub-function does not indicate errors other than by +reporting a #GError (or if its return value does not reliably indicate +errors) you need to create a temporary #GError +since the passed-in one may be %NULL. g_propagate_error() is +intended for use in this case. +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + GError *tmp_error; + + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + tmp_error = NULL; + sub_function_that_can_fail (&tmp_error); + + if (tmp_error != NULL) + { + // store tmp_error in err, if err != NULL, + // otherwise call g_error_free() on tmp_error + g_propagate_error (err, tmp_error); + return FALSE; + } + + // otherwise continue, no error occurred +} +]| + +Error pileups are always a bug. For example, this code is incorrect: +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + GError *tmp_error; + + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + tmp_error = NULL; + sub_function_that_can_fail (&tmp_error); + other_function_that_can_fail (&tmp_error); + + if (tmp_error != NULL) + { + g_propagate_error (err, tmp_error); + return FALSE; + } +} +]| +@tmp_error should be checked immediately after sub_function_that_can_fail(), +and either cleared or propagated upward. The rule is: after each error, +you must either handle the error, or return it to the calling function. + +Note that passing %NULL for the error location is the equivalent +of handling an error by always doing nothing about it. So the +following code is fine, assuming errors in sub_function_that_can_fail() +are not fatal to my_function_that_can_fail(): +|[<!-- language="C" --> +gboolean +my_function_that_can_fail (GError **err) +{ + GError *tmp_error; + + g_return_val_if_fail (err == NULL || *err == NULL, FALSE); + + sub_function_that_can_fail (NULL); // ignore errors + + tmp_error = NULL; + other_function_that_can_fail (&tmp_error); + + if (tmp_error != NULL) + { + g_propagate_error (err, tmp_error); + return FALSE; + } +} +]| + +Note that passing %NULL for the error location ignores errors; +it's equivalent to +`try { sub_function_that_can_fail (); } catch (...) {}` +in C++. It does not mean to leave errors unhandled; it means +to handle them by doing nothing. + +Error domains and codes are conventionally named as follows: + +- The error domain is called <NAMESPACE>_<MODULE>_ERROR, + for example %G_SPAWN_ERROR or %G_THREAD_ERROR: + |[<!-- language="C" --> + #define G_SPAWN_ERROR g_spawn_error_quark () + + G_DEFINE_QUARK (g-spawn-error-quark, g_spawn_error) + ]| + +- The quark function for the error domain is called + <namespace>_<module>_error_quark, + for example g_spawn_error_quark() or g_thread_error_quark(). + +- The error codes are in an enumeration called + <Namespace><Module>Error; + for example, #GThreadError or #GSpawnError. + +- Members of the error code enumeration are called + <NAMESPACE>_<MODULE>_ERROR_<CODE>, + for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. + +- If there's a "generic" or "unknown" error code for unrecoverable + errors it doesn't make sense to distinguish with specific codes, + it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, + for example %G_SPAWN_ERROR_FAILED. In the case of error code + enumerations that may be extended in future releases, you should + generally not handle this error code explicitly, but should + instead treat any unrecognized error code as equivalent to + FAILED. + +## Comparison of #GError and traditional error handling # {#gerror-comparison} + +#GError has several advantages over traditional numeric error codes: +importantly, tools like +[gobject-introspection](https://developer.gnome.org/gi/stable/) understand +#GErrors and convert them to exceptions in bindings; the message includes +more information than just a code; and use of a domain helps prevent +misinterpretation of error codes. + +#GError has disadvantages though: it requires a memory allocation, and +formatting the error message string has a performance overhead. This makes it +unsuitable for use in retry loops where errors are a common case, rather than +being unusual. For example, using %G_IO_ERROR_WOULD_BLOCK means hitting these +overheads in the normal control flow. String formatting overhead can be +eliminated by using g_set_error_literal() in some cases. + +These performance issues can be compounded if a function wraps the #GErrors +returned by the functions it calls: this multiplies the number of allocations +and string formatting operations. This can be partially mitigated by using +g_prefix_error(). + +## Rules for use of #GError # {#gerror-rules} + +Summary of rules for use of #GError: + +- Do not report programming errors via #GError. + +- The last argument of a function that returns an error should + be a location where a #GError can be placed (i.e. "#GError** error"). + If #GError is used with varargs, the #GError** should be the last + argument before the "...". + +- The caller may pass %NULL for the #GError** if they are not interested + in details of the exact error that occurred. + +- If %NULL is passed for the #GError** argument, then errors should + not be returned to the caller, but your function should still + abort and return if an error occurs. That is, control flow should + not be affected by whether the caller wants to get a #GError. + +- If a #GError is reported, then your function by definition had a + fatal failure and did not complete whatever it was supposed to do. + If the failure was not fatal, then you handled it and you should not + report it. If it was fatal, then you must report it and discontinue + whatever you were doing immediately. + +- If a #GError is reported, out parameters are not guaranteed to + be set to any defined value. + +- A #GError* must be initialized to %NULL before passing its address + to a function that can report errors. + +- "Piling up" errors is always a bug. That is, if you assign a + new #GError to a #GError* that is non-%NULL, thus overwriting + the previous error, it indicates that you should have aborted + the operation instead of continuing. If you were able to continue, + you should have cleared the previous error with g_clear_error(). + g_set_error() will complain if you pile up errors. + +- By convention, if you return a boolean value indicating success + then %TRUE means success and %FALSE means failure. Avoid creating + functions which have a boolean return value and a GError parameter, + but where the boolean does something other than signal whether the + GError is set. Among other problems, it requires C callers to allocate + a temporary error. Instead, provide a "gboolean *" out parameter. + There are functions in GLib itself such as g_key_file_has_key() that + are deprecated because of this. If %FALSE is returned, the error must + be set to a non-%NULL value. One exception to this is that in situations + that are already considered to be undefined behaviour (such as when a + g_return_val_if_fail() check fails), the error need not be set. + Instead of checking separately whether the error is set, callers + should ensure that they do not provoke undefined behaviour, then + assume that the error will be set on failure. + +- A %NULL return value is also frequently used to mean that an error + occurred. You should make clear in your documentation whether %NULL + is a valid return value in non-error cases; if %NULL is a valid value, + then users must check whether an error was returned to see if the + function succeeded. + +- When implementing a function that can report errors, you may want + to add a check at the top of your function that the error return + location is either %NULL or contains a %NULL error (e.g. + `g_return_if_fail (error == NULL || *error == NULL);`). + Gets a #GFileError constant based on the passed-in @err_no. For example, if you pass in `EEXIST` this function returns @@ -39026,42 +41857,10 @@ for filenames. Use g_filename_to_utf8() to convert it to UTF-8. - Writes all of @contents to a file named @filename, with good error checking. -If a file called @filename already exists it will be overwritten. - -This write is atomic in the sense that it is first written to a temporary -file which is then renamed to the final name. Notes: - -- On UNIX, if @filename already exists hard links to @filename will break. - Also since the file is recreated, existing permissions, access control - lists, metadata etc. may be lost. If @filename is a symbolic link, - the link itself will be replaced, not the linked file. - -- On UNIX, if @filename already exists and is non-empty, and if the system - supports it (via a journalling filesystem or equivalent), the fsync() - call (or equivalent) will be used to ensure atomic replacement: @filename - will contain either its old contents or @contents, even in the face of - system power loss, the disk being unsafely removed, etc. - -- On UNIX, if @filename does not already exist or is empty, there is a - possibility that system power loss etc. after calling this function will - leave @filename empty or full of NUL bytes, depending on the underlying - filesystem. - -- On Windows renaming a file will not remove an existing file with the - new name, so on Windows there is a race condition between the existing - file being removed and the temporary file being renamed. - -- On Windows there is no way to remove a file that is open to some - process, or mapped into memory. Thus, this function will fail if - @filename already exists and is open. - -If the call was successful, it returns %TRUE. If the call was not successful, -it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. -Possible error codes are those in the #GFileError enumeration. - -Note that the name for the temporary file is constructed by appending up -to 7 characters to @filename. + Writes all of @contents to a file named @filename. This is a convenience +wrapper around calling g_file_set_contents() with `flags` set to +`G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and +`mode` set to `0666`. %TRUE on success, %FALSE if an error occurred @@ -39085,6 +41884,92 @@ to 7 characters to @filename. + + Writes all of @contents to a file named @filename, with good error checking. +If a file called @filename already exists it will be overwritten. + +@flags control the properties of the write operation: whether it’s atomic, +and what the tradeoff is between returning quickly or being resilient to +system crashes. + +As this function performs file I/O, it is recommended to not call it anywhere +where blocking would cause problems, such as in the main loop of a graphical +application. In particular, if @flags has any value other than +%G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`. + +If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation is atomic +in the sense that it is first written to a temporary file which is then +renamed to the final name. + +Notes: + +- On UNIX, if @filename already exists hard links to @filename will break. + Also since the file is recreated, existing permissions, access control + lists, metadata etc. may be lost. If @filename is a symbolic link, + the link itself will be replaced, not the linked file. + +- On UNIX, if @filename already exists and is non-empty, and if the system + supports it (via a journalling filesystem or equivalent), and if + %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the `fsync()` call (or + equivalent) will be used to ensure atomic replacement: @filename + will contain either its old contents or @contents, even in the face of + system power loss, the disk being unsafely removed, etc. + +- On UNIX, if @filename does not already exist or is empty, there is a + possibility that system power loss etc. after calling this function will + leave @filename empty or full of NUL bytes, depending on the underlying + filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and + %G_FILE_SET_CONTENTS_CONSISTENT are set in @flags. + +- On Windows renaming a file will not remove an existing file with the + new name, so on Windows there is a race condition between the existing + file being removed and the temporary file being renamed. + +- On Windows there is no way to remove a file that is open to some + process, or mapped into memory. Thus, this function will fail if + @filename already exists and is open. + +If the call was successful, it returns %TRUE. If the call was not successful, +it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR. +Possible error codes are those in the #GFileError enumeration. + +Note that the name for the temporary file is constructed by appending up +to 7 characters to @filename. + +If the file didn’t exist before and is created, it will be given the +permissions from @mode. Otherwise, the permissions of the existing file may +be changed to @mode depending on @flags, or they may remain unchanged. + + + %TRUE on success, %FALSE if an error occurred + + + + + name of a file to write @contents to, in the GLib file name + encoding + + + + string to write to the file + + + + + + length of @contents, or -1 if @contents is a nul-terminated string + + + + flags controlling the safety vs speed of the operation + + + + file mode, as passed to `open()`; typically this will be `0666` + + + + Returns %TRUE if any of the tests in the bitfield @test are %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)` @@ -39342,6 +42227,38 @@ may contain embedded nul characters. + + Do not use these APIs unless you are porting a POSIX application to Windows. +A more high-level file access API is provided as GIO — see the documentation +for #GFile. + +There is a group of functions which wrap the common POSIX functions +dealing with filenames (g_open(), g_rename(), g_mkdir(), g_stat(), +g_unlink(), g_remove(), g_fopen(), g_freopen()). The point of these +wrappers is to make it possible to handle file names with any Unicode +characters in them on Windows without having to use ifdefs and the +wide character API in the application code. + +On some Unix systems, these APIs may be defined as identical to their POSIX +counterparts. For this reason, you must check for and include the necessary +header files (such as `fcntl.h`) before using functions like g_creat(). You +must also define the relevant feature test macros. + +The pathname argument should be in the GLib file name encoding. +On POSIX this is the actual on-disk encoding which might correspond +to the locale settings of the process (or the `G_FILENAME_ENCODING` +environment variable), or not. + +On Windows the GLib file name encoding is UTF-8. Note that the +Microsoft C library does not use UTF-8, but has separate APIs for +current system code page and wide characters (UTF-16). The GLib +wrappers call the wide character API if present (on modern Windows +systems), otherwise convert to/from the system code page. + +Another group of functions allows to open and read directories +in the GLib file name encoding. These are g_dir_open(), +g_dir_read_name(), g_dir_rewind(), g_dir_close(). + Locates the first executable named @program in the user's path, in the same way that execvp() would locate it. Returns an allocated string @@ -40128,6 +43045,29 @@ references to other environment variables, they are expanded. + + Functions for manipulating internet hostnames; in particular, for +converting between Unicode and ASCII-encoded forms of +Internationalized Domain Names (IDNs). + +The +[Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt) +standards allow for the use +of Unicode domain names in applications, while providing +backward-compatibility with the old ASCII-only DNS, by defining an +ASCII-Compatible Encoding of any given Unicode name, which can be +used with non-IDN-aware applications and protocols. (For example, +"Παν語.org" maps to "xn--4wa8awb4637h.org".) + + + Most of GLib is intended to be portable; in contrast, this set of +functions is designed for programs which explicitly target UNIX, +or are using it to build higher level abstractions which would be +conditionally compiled if the platform matches G_OS_UNIX. + +To use these functions, you must explicitly include the +"glib-unix.h" header. + This is a convenience function for using a #GHashTable as a set. It is equivalent to calling g_hash_table_replace() with @key as both the @@ -40519,6 +43459,73 @@ This function is MT-safe and may be called from any thread. + + A #GHashTable provides associations between keys and values which is +optimized so that given a key, the associated value can be found, +inserted or removed in amortized O(1). All operations going through +each element take O(n) time (list all keys/values, table resize, etc.). + +Note that neither keys nor values are copied when inserted into the +#GHashTable, so they must exist for the lifetime of the #GHashTable. +This means that the use of static strings is OK, but temporary +strings (i.e. those created in buffers and those returned by GTK +widgets) should be copied with g_strdup() before being inserted. + +If keys or values are dynamically allocated, you must be careful to +ensure that they are freed when they are removed from the +#GHashTable, and also when they are overwritten by new insertions +into the #GHashTable. It is also not advisable to mix static strings +and dynamically-allocated strings in a #GHashTable, because it then +becomes difficult to determine whether the string should be freed. + +To create a #GHashTable, use g_hash_table_new(). + +To insert a key and value into a #GHashTable, use +g_hash_table_insert(). + +To look up a value corresponding to a given key, use +g_hash_table_lookup() and g_hash_table_lookup_extended(). + +g_hash_table_lookup_extended() can also be used to simply +check if a key is present in the hash table. + +To remove a key and value, use g_hash_table_remove(). + +To call a function for each key and value pair use +g_hash_table_foreach() or use an iterator to iterate over the +key/value pairs in the hash table, see #GHashTableIter. The iteration order +of a hash table is not defined, and you must not rely on iterating over +keys/values in the same order as they were inserted. + +To destroy a #GHashTable use g_hash_table_destroy(). + +A common use-case for hash tables is to store information about a +set of keys, without associating any particular value with each +key. GHashTable optimizes one way of doing so: If you store only +key-value pairs where key == value, then GHashTable does not +allocate memory to store the values, which can be a considerable +space saving, if your set is large. The functions +g_hash_table_add() and g_hash_table_contains() are designed to be +used when using #GHashTable this way. + +#GHashTable is not designed to be statically initialised with keys and +values known at compile time. To build a static hash table, use a tool such +as [gperf](https://www.gnu.org/software/gperf/). + + + HMACs should be used when producing a cookie or hash based on data +and a key. Simple mechanisms for using SHA1 and other algorithms to +digest a key and data together are vulnerable to various security +issues. +[HMAC](http://en.wikipedia.org/wiki/HMAC) +uses algorithms like SHA1 in a secure way to produce a digest of a +key and data. + +Both the key and data are arbitrary byte arrays of bytes or characters. + +Support for HMAC Digests has been added in GLib 2.30, and support for SHA-512 +in GLib 2.42. Support for SHA-384 was added in GLib 2.52. + Appends a #GHook onto the end of a #GHookList. @@ -40642,6 +43649,11 @@ from the #GHookList and g_hook_free() is called to free it. + + The #GHookList, #GHook and their related functions provide support for +lists of hook functions. Functions can be added and removed from the lists, +and the list of hook functions can be invoked. + Tests if @hostname contains segments with an ASCII-compatible encoding of an Internationalized Domain Name. If this returns @@ -40666,7 +43678,9 @@ segments. Tests if @hostname is the string form of an IPv4 or IPv6 address. -(Eg, "192.168.0.1".) +(Eg, "192.168.0.1".) + +Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874). %TRUE if @hostname is an IP address @@ -40755,6 +43769,50 @@ the canonical presentation form will be entirely ASCII. + + GLib doesn't force any particular localization method upon its users. +But since GLib itself is localized using the gettext() mechanism, it seems +natural to offer the de-facto standard gettext() support macros in an +easy-to-use form. + +In order to use these macros in an application, you must include +`<glib/gi18n.h>`. For use in a library, you must include +`<glib/gi18n-lib.h>` +after defining the %GETTEXT_PACKAGE macro suitably for your library: +|[<!-- language="C" --> +#define GETTEXT_PACKAGE "gtk20" +#include <glib/gi18n-lib.h> +]| +For an application, note that you also have to call bindtextdomain(), +bind_textdomain_codeset(), textdomain() and setlocale() early on in your +main() to make gettext() work. For example: +|[<!-- language="C" --> +#include <glib/gi18n.h> +#include <locale.h> + +int +main (int argc, char **argv) +{ + setlocale (LC_ALL, ""); + bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale"); + bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8"); + textdomain (GETTEXT_PACKAGE); + + // Rest of your application. +} +]| +where `DATADIR` is as typically provided by automake or Meson. + +For a library, you only have to call bindtextdomain() and +bind_textdomain_codeset() in your initialization function. If your library +doesn't have an initialization function, you can call the functions before +the first translated message. + +The +[gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers) +covers details of how to integrate gettext into a project’s build system and +workflow. + Same as the standard UNIX routine iconv(), but may be implemented via libiconv on UNIX flavors that lack @@ -41162,11 +44220,307 @@ implementation and unavoidable. + + The #GIOChannel data type aims to provide a portable method for +using file descriptors, pipes, and sockets, and integrating them +into the [main event loop][glib-The-Main-Event-Loop]. Currently, +full support is available on UNIX platforms, support for Windows +is only partially complete. + +To create a new #GIOChannel on UNIX systems use +g_io_channel_unix_new(). This works for plain file descriptors, +pipes and sockets. Alternatively, a channel can be created for a +file in a system independent manner using g_io_channel_new_file(). + +Once a #GIOChannel has been created, it can be used in a generic +manner with the functions g_io_channel_read_chars(), +g_io_channel_write_chars(), g_io_channel_seek_position(), and +g_io_channel_shutdown(). + +To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], +use g_io_add_watch() or g_io_add_watch_full(). Here you specify which +events you are interested in on the #GIOChannel, and provide a +function to be called whenever these events occur. + +#GIOChannel instances are created with an initial reference count of 1. +g_io_channel_ref() and g_io_channel_unref() can be used to +increment or decrement the reference count respectively. When the +reference count falls to 0, the #GIOChannel is freed. (Though it +isn't closed automatically, unless it was created using +g_io_channel_new_file().) Using g_io_add_watch() or +g_io_add_watch_full() increments a channel's reference count. + +The new functions g_io_channel_read_chars(), +g_io_channel_read_line(), g_io_channel_read_line_string(), +g_io_channel_read_to_end(), g_io_channel_write_chars(), +g_io_channel_seek_position(), and g_io_channel_flush() should not be +mixed with the deprecated functions g_io_channel_read(), +g_io_channel_write(), and g_io_channel_seek() on the same channel. + + + #GKeyFile lets you parse, edit or create files containing groups of +key-value pairs, which we call "key files" for lack of a better name. +Several freedesktop.org specifications use key files now, e.g the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) +and the +[Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec). + +The syntax of key files is described in detail in the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), +here is a quick summary: Key files +consists of groups of key-value pairs, interspersed with comments. + +|[ +# this is just an example +# there can be comments before the first group + +[First Group] + +Name=Key File Example\tthis value shows\nescaping + +# localized strings are stored in multiple key-value pairs +Welcome=Hello +Welcome[de]=Hallo +Welcome[fr_FR]=Bonjour +Welcome[it]=Ciao +Welcome[be@latin]=Hello + +[Another Group] + +Numbers=2;20;-200;0 + +Booleans=true;false;true;true +]| + +Lines beginning with a '#' and blank lines are considered comments. + +Groups are started by a header line containing the group name enclosed +in '[' and ']', and ended implicitly by the start of the next group or +the end of the file. Each key-value pair must be contained in a group. + +Key-value pairs generally have the form `key=value`, with the +exception of localized strings, which have the form +`key[locale]=value`, with a locale identifier of the +form `lang_COUNTRY@MODIFIER` where `COUNTRY` and `MODIFIER` +are optional. +Space before and after the '=' character are ignored. Newline, tab, +carriage return and backslash characters in value are escaped as \n, +\t, \r, and \\\\, respectively. To preserve leading spaces in values, +these can also be escaped as \s. + +Key files can store strings (possibly with localized variants), integers, +booleans and lists of these. Lists are separated by a separator character, +typically ';' or ','. To use the list separator character in a value in +a list, it has to be escaped by prefixing it with a backslash. + +This syntax is obviously inspired by the .ini files commonly met +on Windows, but there are some important differences: + +- .ini files use the ';' character to begin comments, + key files use the '#' character. + +- Key files do not allow for ungrouped keys meaning only + comments can precede the first group. + +- Key files are always encoded in UTF-8. + +- Key and Group names are case-sensitive. For example, a group called + [GROUP] is a different from [group]. + +- .ini files don't have a strongly typed boolean entry type, + they only have GetProfileInt(). In key files, only + true and false (in lower case) are allowed. + +Note that in contrast to the +[Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec), +groups in key files may contain the same +key multiple times; the last entry wins. Key files may also contain +multiple groups with the same name; they are merged together. +Another difference is that keys and group names in key files are not +restricted to ASCII characters. + +Here is an example of loading a key file and reading a value: +|[<!-- language="C" --> +g_autoptr(GError) error = NULL; +g_autoptr(GKeyFile) key_file = g_key_file_new (); + +if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) + { + if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) + g_warning ("Error loading key file: %s", error->message); + return; + } + +g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); +if (val == NULL && + !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) + { + g_warning ("Error finding key in key file: %s", error->message); + return; + } +else if (val == NULL) + { + // Fall back to a default value. + val = g_strdup ("default-value"); + } +]| + +Here is an example of creating and saving a key file: +|[<!-- language="C" --> +g_autoptr(GKeyFile) key_file = g_key_file_new (); +const gchar *val = …; +g_autoptr(GError) error = NULL; + +g_key_file_set_string (key_file, "Group Name", "SomeKey", val); + +// Save as a file. +if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) + { + g_warning ("Error saving key file: %s", error->message); + return; + } + +// Or store to a GBytes for use elsewhere. +gsize data_len; +g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); +if (data == NULL) + { + g_warning ("Error saving key file: %s", error->message); + return; + } +g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); +]| + + + The #GList structure and its associated functions provide a standard +doubly-linked list data structure. The benefit of this data-structure +is to provide insertion/deletion operations in O(1) complexity where +access/search operations are in O(n). The benefit of #GList over +#GSList (singly linked list) is that the worst case on access/search +operations is divided by two which comes at a cost in space as we need +to retain two pointers in place of one. + +Each element in the list contains a piece of data, together with +pointers which link to the previous and next elements in the list. +Using these pointers it is possible to move through the list in both +directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], +which only allows movement through the list in the forward direction). + +The double linked list does not keep track of the number of items +and does not keep track of both the start and end of the list. If +you want fast access to both the start and the end of the list, +and/or the number of items in the list, use a +[GQueue][glib-Double-ended-Queues] instead. + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], +or simply pointers to any type of data. + +List elements are allocated from the [slice allocator][glib-Memory-Slices], +which is more efficient than allocating elements individually. + +Note that most of the #GList functions expect to be passed a pointer +to the first element in the list. The functions which insert +elements return the new start of the list, which may have changed. + +There is no function to create a #GList. %NULL is considered to be +a valid, empty list so you simply set a #GList* to %NULL to initialize +it. + +To add elements, use g_list_append(), g_list_prepend(), +g_list_insert() and g_list_insert_sorted(). + +To visit all elements in the list, use a loop over the list: +|[<!-- language="C" --> +GList *l; +for (l = list; l != NULL; l = l->next) + { + // do something with l->data + } +]| + +To call a function for each element in the list, use g_list_foreach(). + +To loop over the list and modify it (e.g. remove a certain element) +a while loop is more appropriate, for example: +|[<!-- language="C" --> +GList *l = list; +while (l != NULL) + { + GList *next = l->next; + if (should_be_removed (l)) + { + // possibly free l->data + list = g_list_delete_link (list, l); + } + l = next; + } +]| + +To remove elements, use g_list_remove(). + +To navigate in a list, use g_list_first(), g_list_last(), +g_list_next(), g_list_previous(). + +To find elements in the list use g_list_nth(), g_list_nth_data(), +g_list_find() and g_list_find_custom(). + +To find the index of an element use g_list_position() and +g_list_index(). + +To free the entire list, use g_list_free() or g_list_free_full(). + + + The #GSList structure and its associated functions provide a +standard singly-linked list data structure. The benefit of this +data-structure is to provide insertion/deletion operations in O(1) +complexity where access/search operations are in O(n). The benefit +of #GSList over #GList (doubly linked list) is that they are lighter +in space as they only need to retain one pointer but it double the +cost of the worst case access/search operations. + +Each element in the list contains a piece of data, together with a +pointer which links to the next element in the list. Using this +pointer it is possible to move through the list in one direction +only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], +which allow movement in both directions). + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], +or simply pointers to any type of data. + +List elements are allocated from the [slice allocator][glib-Memory-Slices], +which is more efficient than allocating elements individually. + +Note that most of the #GSList functions expect to be passed a +pointer to the first element in the list. The functions which insert +elements return the new start of the list, which may have changed. + +There is no function to create a #GSList. %NULL is considered to be +the empty list so you simply set a #GSList* to %NULL. + +To add elements, use g_slist_append(), g_slist_prepend(), +g_slist_insert() and g_slist_insert_sorted(). + +To remove elements, use g_slist_remove(). + +To find elements in the list use g_slist_last(), g_slist_next(), +g_slist_nth(), g_slist_nth_data(), g_slist_find() and +g_slist_find_custom(). + +To find the index of an element use g_slist_position() and +g_slist_index(). + +To call a function for each element in the list use +g_slist_foreach(). + +To free the entire list, use g_slist_free(). + A convenience macro to get the next element in a #GList. Note that it is considered perfectly acceptable to access @@ -41358,7 +44712,7 @@ environment variables: - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which messages should be prefixed by the program name and PID of the - aplication. + application. - `G_MESSAGES_DEBUG`: A space-separated list of log domains for which debug and informational messages are printed. By default @@ -42083,6 +45437,123 @@ application domain + + These macros provide a few commonly-used features. + + + These macros provide more specialized features which are not +needed so often by application programmers. + + + The main event loop manages all the available sources of events for +GLib and GTK+ applications. These events can come from any number of +different types of sources such as file descriptors (plain files, +pipes or sockets) and timeouts. New types of event sources can also +be added using g_source_attach(). + +To allow multiple independent sets of sources to be handled in +different threads, each source is associated with a #GMainContext. +A #GMainContext can only be running in a single thread, but +sources can be added to it and removed from it from other threads. All +functions which operate on a #GMainContext or a built-in #GSource are +thread-safe. + +Each event source is assigned a priority. The default priority, +#G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. +Values greater than 0 denote lower priorities. Events from high priority +sources are always processed before events from lower priority sources. + +Idle functions can also be added, and assigned a priority. These will +be run whenever no events with a higher priority are ready to be processed. + +The #GMainLoop data type represents a main event loop. A GMainLoop is +created with g_main_loop_new(). After adding the initial event sources, +g_main_loop_run() is called. This continuously checks for new events from +each of the event sources and dispatches them. Finally, the processing of +an event from one of the sources leads to a call to g_main_loop_quit() to +exit the main loop, and g_main_loop_run() returns. + +It is possible to create new instances of #GMainLoop recursively. +This is often used in GTK+ applications when showing modal dialog +boxes. Note that event sources are associated with a particular +#GMainContext, and will be checked and dispatched for all main +loops associated with that GMainContext. + +GTK+ contains wrappers of some of these functions, e.g. gtk_main(), +gtk_main_quit() and gtk_events_pending(). + +## Creating new source types + +One of the unusual features of the #GMainLoop functionality +is that new types of event source can be created and used in +addition to the builtin type of event source. A new event source +type is used for handling GDK events. A new source type is created +by "deriving" from the #GSource structure. The derived type of +source is represented by a structure that has the #GSource structure +as a first element, and other elements specific to the new source +type. To create an instance of the new source type, call +g_source_new() passing in the size of the derived structure and +a table of functions. These #GSourceFuncs determine the behavior of +the new source type. + +New source types basically interact with the main context +in two ways. Their prepare function in #GSourceFuncs can set a timeout +to determine the maximum amount of time that the main loop will sleep +before checking the source again. In addition, or as well, the source +can add file descriptors to the set that the main context checks using +g_source_add_poll(). + +## Customizing the main loop iteration + +Single iterations of a #GMainContext can be run with +g_main_context_iteration(). In some cases, more detailed control +of exactly how the details of the main loop work is desired, for +instance, when integrating the #GMainLoop with an external main loop. +In such cases, you can call the component functions of +g_main_context_iteration() directly. These functions are +g_main_context_prepare(), g_main_context_query(), +g_main_context_check() and g_main_context_dispatch(). + +## State of a Main Context # {#mainloop-states} + +The operation of these functions can best be seen in terms +of a state diagram, as shown in this image. + +![](mainloop-states.gif) + +On UNIX, the GLib mainloop is incompatible with fork(). Any program +using the mainloop must either exec() or exit() from the child +without returning to the mainloop. + +## Memory management of sources # {#mainloop-memory-management} + +There are two options for memory management of the user data passed to a +#GSource to be passed to its callback on invocation. This data is provided +in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and +more generally, using g_source_set_callback(). This data is typically an +object which ‘owns’ the timeout or idle callback, such as a widget or a +network protocol implementation. In many cases, it is an error for the +callback to be invoked after this owning object has been destroyed, as that +results in use of freed memory. + +The first, and preferred, option is to store the source ID returned by +functions such as g_timeout_add() or g_source_attach(), and explicitly +remove that source from the main context using g_source_remove() when the +owning object is finalized. This ensures that the callback can only be +invoked while the object is still alive. + +The second option is to hold a strong reference to the object in the +callback, and to release it in the callback’s #GDestroyNotify. This ensures +that the object is kept alive until after the source is finalized, which is +guaranteed to be after it is invoked for the final time. The #GDestroyNotify +is another callback passed to the ‘full’ variants of #GSource functions (for +example, g_timeout_add_full()). It is called when the source is finalized, +and is designed for releasing references like this. + +One important caveat of this second approach is that it will keep the object +alive indefinitely if the main loop is stopped before the #GSource is +invoked, which may be undesirable. + Returns the global default main context. This is the main context used for main loop functions when a main loop is not explicitly @@ -42311,6 +45782,49 @@ but care is taken to detect possible overflow during multiplication. + + The "GMarkup" parser is intended to parse a simple markup format +that's a subset of XML. This is a small, efficient, easy-to-use +parser. It should not be used if you expect to interoperate with +other applications generating full-scale XML, and must not be used if you +expect to parse untrusted input. However, it's very +useful for application data files, config files, etc. where you +know your application will be the only one writing the file. +Full-scale XML parsers should be able to parse the subset used by +GMarkup, so you can easily migrate to full-scale XML at a later +time if the need arises. + +GMarkup is not guaranteed to signal an error on all invalid XML; +the parser may accept documents that an XML parser would not. +However, XML documents which are not well-formed (which is a +weaker condition than being valid. See the +[XML specification](http://www.w3.org/TR/REC-xml/) +for definitions of these terms.) are not considered valid GMarkup +documents. + +Simplifications to XML include: + +- Only UTF-8 encoding is allowed + +- No user-defined entities + +- Processing instructions, comments and the doctype declaration + are "passed through" but are not interpreted in any way + +- No DTD or validation + +The markup format does support: + +- Elements + +- Attributes + +- 5 standard entities: &amp; &lt; &gt; &quot; &apos; + +- Character references + +- Sections marked as CDATA + Collects the attributes of the element from the data passed to the #GMarkupParser start_element function, dealing with common error @@ -42554,6 +46068,241 @@ The source and destination areas may overlap. + + These functions provide support for allocating and freeing memory. + +If any call to allocate memory using functions g_new(), g_new0(), g_renew(), +g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n() +fails, the application is terminated. This also means that there is no +need to check if the call succeeded. On the other hand, the `g_try_...()` family +of functions returns %NULL on failure that can be used as a check +for unsuccessful memory allocation. The application is not terminated +in this case. + +As all GLib functions and data structures use `g_malloc()` internally, unless +otherwise specified, any allocation failure will result in the application +being terminated. + +It's important to match g_malloc() (and wrappers such as g_new()) with +g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with +g_slice_free(), plain malloc() with free(), and (if you're using C++) +new with delete and new[] with delete[]. Otherwise bad things can happen, +since these allocators may use different memory pools (and new/delete call +constructors and destructors). + +Since GLib 2.46 g_malloc() is hardcoded to always use the system malloc +implementation. + + + Memory slices provide a space-efficient and multi-processing scalable +way to allocate equal-sized pieces of memory, just like the original +#GMemChunks (from GLib 2.8), while avoiding their excessive +memory-waste, scalability and performance problems. + +To achieve these goals, the slice allocator uses a sophisticated, +layered design that has been inspired by Bonwick's slab allocator +([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html) +Jeff Bonwick, The slab allocator: An object-caching kernel +memory allocator. USENIX 1994, and +[Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html) +Bonwick and Jonathan Adams, Magazines and vmem: Extending the +slab allocator to many cpu's and arbitrary resources. USENIX 2001) + +It uses posix_memalign() to optimize allocations of many equally-sized +chunks, and has per-thread free lists (the so-called magazine layer) +to quickly satisfy allocation requests of already known structure sizes. +This is accompanied by extra caching logic to keep freed memory around +for some time before returning it to the system. Memory that is unused +due to alignment constraints is used for cache colorization (random +distribution of chunk addresses) to improve CPU cache utilization. The +caching layer of the slice allocator adapts itself to high lock contention +to improve scalability. + +The slice allocator can allocate blocks as small as two pointers, and +unlike malloc(), it does not reserve extra space per block. For large block +sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the +system malloc() implementation. For newly written code it is recommended +to use the new `g_slice` API instead of g_malloc() and +friends, as long as objects are not resized during their lifetime and the +object size used at allocation time is still available when freeing. + +Here is an example for using the slice allocator: +|[<!-- language="C" --> +gchar *mem[10000]; +gint i; + +// Allocate 10000 blocks. +for (i = 0; i < 10000; i++) + { + mem[i] = g_slice_alloc (50); + + // Fill in the memory with some junk. + for (j = 0; j < 50; j++) + mem[i][j] = i * j; + } + +// Now free all of the blocks. +for (i = 0; i < 10000; i++) + g_slice_free1 (50, mem[i]); +]| + +And here is an example for using the using the slice allocator +with data structures: +|[<!-- language="C" --> +GRealArray *array; + +// Allocate one block, using the g_slice_new() macro. +array = g_slice_new (GRealArray); + +// We can now use array just like a normal pointer to a structure. +array->data = NULL; +array->len = 0; +array->alloc = 0; +array->zero_terminated = (zero_terminated ? 1 : 0); +array->clear = (clear ? 1 : 0); +array->elt_size = elt_size; + +// We can free the block, so it can be reused. +g_slice_free (GRealArray, array); +]| + + + These functions provide support for outputting messages. + +The g_return family of macros (g_return_if_fail(), +g_return_val_if_fail(), g_return_if_reached(), +g_return_val_if_reached()) should only be used for programming +errors, a typical use case is checking for invalid parameters at +the beginning of a public function. They should not be used if +you just mean "if (error) return", they should only be used if +you mean "if (bug in program) return". The program behavior is +generally considered undefined after one of these checks fails. +They are not intended for normal control flow, only to give a +perhaps-helpful warning before giving up. + +Structured logging output is supported using g_log_structured(). This differs +from the traditional g_log() API in that log messages are handled as a +collection of key–value pairs representing individual pieces of information, +rather than as a single string containing all the information in an arbitrary +format. + +The convenience macros g_info(), g_message(), g_debug(), g_warning() and g_error() +will use the traditional g_log() API unless you define the symbol +%G_LOG_USE_STRUCTURED before including `glib.h`. But note that even messages +logged through the traditional g_log() API are ultimatively passed to +g_log_structured(), so that all log messages end up in same destination. +If %G_LOG_USE_STRUCTURED is defined, g_test_expect_message() will become +ineffective for the wrapper macros g_warning() and friends (see +[Testing for Messages][testing-for-messages]). + +The support for structured logging was motivated by the following needs (some +of which were supported previously; others weren’t): + * Support for multiple logging levels. + * Structured log support with the ability to add `MESSAGE_ID`s (see + g_log_structured()). + * Moving the responsibility for filtering log messages from the program to + the log viewer — instead of libraries and programs installing log handlers + (with g_log_set_handler()) which filter messages before output, all log + messages are outputted, and the log viewer program (such as `journalctl`) + must filter them. This is based on the idea that bugs are sometimes hard + to reproduce, so it is better to log everything possible and then use + tools to analyse the logs than it is to not be able to reproduce a bug to + get additional log data. Code which uses logging in performance-critical + sections should compile out the g_log_structured() calls in + release builds, and compile them in in debugging builds. + * A single writer function which handles all log messages in a process, from + all libraries and program code; rather than multiple log handlers with + poorly defined interactions between them. This allows a program to easily + change its logging policy by changing the writer function, for example to + log to an additional location or to change what logging output fallbacks + are used. The log writer functions provided by GLib are exposed publicly + so they can be used from programs’ log writers. This allows log writer + policy and implementation to be kept separate. + * If a library wants to add standard information to all of its log messages + (such as library state) or to redact private data (such as passwords or + network credentials), it should use a wrapper function around its + g_log_structured() calls or implement that in the single log writer + function. + * If a program wants to pass context data from a g_log_structured() call to + its log writer function so that, for example, it can use the correct + server connection to submit logs to, that user data can be passed as a + zero-length #GLogField to g_log_structured_array(). + * Color output needed to be supported on the terminal, to make reading + through logs easier. + +## Using Structured Logging ## {#using-structured-logging} + +To use structured logging (rather than the old-style logging), either use +the g_log_structured() and g_log_structured_array() functions; or define +`G_LOG_USE_STRUCTURED` before including any GLib header, and use the +g_message(), g_debug(), g_error() (etc.) macros. + +You do not need to define `G_LOG_USE_STRUCTURED` to use g_log_structured(), +but it is a good idea to avoid confusion. + +## Log Domains ## {#log-domains} + +Log domains may be used to broadly split up the origins of log messages. +Typically, there are one or a few log domains per application or library. +%G_LOG_DOMAIN should be used to define the default log domain for the current +compilation unit — it is typically defined at the top of a source file, or in +the preprocessor flags for a group of source files. + +Log domains must be unique, and it is recommended that they are the +application or library name, optionally followed by a hyphen and a sub-domain +name. For example, `bloatpad` or `bloatpad-io`. + +## Debug Message Output ## {#debug-message-output} + +The default log functions (g_log_default_handler() for the old-style API and +g_log_writer_default() for the structured API) both drop debug and +informational messages by default, unless the log domains of those messages +are listed in the `G_MESSAGES_DEBUG` environment variable (or it is set to +`all`). + +It is recommended that custom log writer functions re-use the +`G_MESSAGES_DEBUG` environment variable, rather than inventing a custom one, +so that developers can re-use the same debugging techniques and tools across +projects. + +## Testing for Messages ## {#testing-for-messages} + +With the old g_log() API, g_test_expect_message() and +g_test_assert_expected_messages() could be used in simple cases to check +whether some code under test had emitted a given log message. These +functions have been deprecated with the structured logging API, for several +reasons: + * They relied on an internal queue which was too inflexible for many use + cases, where messages might be emitted in several orders, some + messages might not be emitted deterministically, or messages might be + emitted by unrelated log domains. + * They do not support structured log fields. + * Examining the log output of code is a bad approach to testing it, and + while it might be necessary for legacy code which uses g_log(), it should + be avoided for new code using g_log_structured(). + +They will continue to work as before if g_log() is in use (and +%G_LOG_USE_STRUCTURED is not defined). They will do nothing if used with the +structured logging API. + +Examining the log output of code is discouraged: libraries should not emit to +`stderr` during defined behaviour, and hence this should not be tested. If +the log emissions of a library during undefined behaviour need to be tested, +they should be limited to asserting that the library aborts and prints a +suitable error message before aborting. This should be done with +g_test_trap_assert_stderr(). + +If it is really necessary to test the structured log messages emitted by a +particular piece of code – and the code cannot be restructured to be more +suitable to more conventional unit testing – you should write a custom log +writer function (see g_log_set_writer_func()) which appends all log messages +to a queue. When you want to check the log messages, examine and clear the +queue, ignoring irrelevant log messages (for example, from log domains other +than the one under test). + + + These are portable utility functions. + Create a directory if it doesn't already exist. Create intermediate parent directories as needed, too. @@ -42896,6 +46645,18 @@ so might hide memory allocation errors. + + GLib offers mathematical constants such as #G_PI for the value of pi; +many platforms have these in the C library, but some don't, the GLib +versions always exist. + +The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the +sign, mantissa and exponent of IEEE floats and doubles. These unions are +defined as appropriate for a given platform. IEEE floats and doubles are +supported (used for storage) by at least Intel, PPC and Sparc. See +[IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float) +for more information about IEEE number formats. + Prompts the user with `[E]xit, [H]alt, show [S]tack trace or [P]roceed`. @@ -43082,6 +46843,161 @@ initialization variable. + + The GOption commandline parser is intended to be a simpler replacement +for the popt library. It supports short and long commandline options, +as shown in the following example: + +`testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2` + +The example demonstrates a number of features of the GOption +commandline parser: + +- Options can be single letters, prefixed by a single dash. + +- Multiple short options can be grouped behind a single dash. + +- Long options are prefixed by two consecutive dashes. + +- Options can have an extra argument, which can be a number, a string or + a filename. For long options, the extra argument can be appended with + an equals sign after the option name, which is useful if the extra + argument starts with a dash, which would otherwise cause it to be + interpreted as another option. + +- Non-option arguments are returned to the application as rest arguments. + +- An argument consisting solely of two dashes turns off further parsing, + any remaining arguments (even those starting with a dash) are returned + to the application as rest arguments. + +Another important feature of GOption is that it can automatically +generate nicely formatted help output. Unless it is explicitly turned +off with g_option_context_set_help_enabled(), GOption will recognize +the `--help`, `-?`, `--help-all` and `--help-groupname` options +(where `groupname` is the name of a #GOptionGroup) and write a text +similar to the one shown in the following example to stdout. + +|[ +Usage: + testtreemodel [OPTION...] - test tree model performance + +Help Options: + -h, --help Show help options + --help-all Show all help options + --help-gtk Show GTK+ Options + +Application Options: + -r, --repeats=N Average over N repetitions + -m, --max-size=M Test up to 2^M items + --display=DISPLAY X display to use + -v, --verbose Be verbose + -b, --beep Beep when done + --rand Randomize the data +]| + +GOption groups options in #GOptionGroups, which makes it easy to +incorporate options from multiple sources. The intended use for this is +to let applications collect option groups from the libraries it uses, +add them to their #GOptionContext, and parse all options by a single call +to g_option_context_parse(). See gtk_get_option_group() for an example. + +If an option is declared to be of type string or filename, GOption takes +care of converting it to the right encoding; strings are returned in +UTF-8, filenames are returned in the GLib filename encoding. Note that +this only works if setlocale() has been called before +g_option_context_parse(). + +Here is a complete example of setting up GOption to parse the example +commandline above and produce the example help output. +|[<!-- language="C" --> +static gint repeats = 2; +static gint max_size = 8; +static gboolean verbose = FALSE; +static gboolean beep = FALSE; +static gboolean randomize = FALSE; + +static GOptionEntry entries[] = +{ + { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" }, + { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" }, + { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, + { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, + { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, + { NULL } +}; + +int +main (int argc, char *argv[]) +{ + GError *error = NULL; + GOptionContext *context; + + context = g_option_context_new ("- test tree model performance"); + g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); + g_option_context_add_group (context, gtk_get_option_group (TRUE)); + if (!g_option_context_parse (context, &argc, &argv, &error)) + { + g_print ("option parsing failed: %s\n", error->message); + exit (1); + } + + ... + +} +]| + +On UNIX systems, the argv that is passed to main() has no particular +encoding, even to the extent that different parts of it may have +different encodings. In general, normal arguments and flags will be +in the current locale and filenames should be considered to be opaque +byte strings. Proper use of %G_OPTION_ARG_FILENAME vs +%G_OPTION_ARG_STRING is therefore important. + +Note that on Windows, filenames do have an encoding, but using +#GOptionContext with the argv as passed to main() will result in a +program that can only accept commandline arguments with characters +from the system codepage. This can cause problems when attempting to +deal with filenames containing Unicode characters that fall outside +of the codepage. + +A solution to this is to use g_win32_get_command_line() and +g_option_context_parse_strv() which will properly handle full Unicode +filenames. If you are using #GApplication, this is done +automatically for you. + +The following example shows how you can use #GOptionContext directly +in order to correctly deal with Unicode filenames on Windows: + +|[<!-- language="C" --> +int +main (int argc, char **argv) +{ + GError *error = NULL; + GOptionContext *context; + gchar **args; + +#ifdef G_OS_WIN32 + args = g_win32_get_command_line (); +#else + args = g_strdupv (argv); +#endif + + // set up context + + if (!g_option_context_parse_strv (context, &args, &error)) + { + // error happened + } + + ... + + g_strfreev (args); + + ... +} +]| + @@ -43301,6 +47217,22 @@ g_pattern_match() instead while supplying the reversed string. + + The g_pattern_match* functions match a string +against a pattern containing '*' and '?' wildcards with similar +semantics as the standard glob() function: '*' matches an arbitrary, +possibly empty, string, '?' matches an arbitrary character. + +Note that in contrast to glob(), the '/' character can be matched by +the wildcards, there are no '[...]' character ranges and '*' and '?' +can not be escaped to include them literally in a pattern. + +When multiple strings must be matched against the same pattern, it +is better to compile the pattern to a #GPatternSpec using +g_pattern_spec_new() and use g_pattern_match_string() instead of +g_pattern_match_simple(). This avoids the overhead of repeated +pattern compilation. + This is equivalent to g_bit_lock, but working on pointers (or other pointer-sized values). @@ -43779,6 +47711,55 @@ running. + + Quarks are associations between strings and integer identifiers. +Given either the string or the #GQuark identifier it is possible to +retrieve the other. + +Quarks are used for both [datasets][glib-Datasets] and +[keyed data lists][glib-Keyed-Data-Lists]. + +To create a new quark from a string, use g_quark_from_string() or +g_quark_from_static_string(). + +To find the string corresponding to a given #GQuark, use +g_quark_to_string(). + +To find the #GQuark corresponding to a given string, use +g_quark_try_string(). + +Another use for the string pool maintained for the quark functions +is string interning, using g_intern_string() or +g_intern_static_string(). An interned string is a canonical +representation for a string. One important advantage of interned +strings is that they can be compared for equality by a simple +pointer comparison, rather than using strcmp(). + + + The #GQueue structure and its associated functions provide a standard +queue data structure. Internally, GQueue uses the same data structure +as #GList to store elements with the same complexity over +insertion/deletion (O(1)) and access/search (O(n)) operations. + +The data contained in each element can be either integer values, by +using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], +or simply pointers to any type of data. + +As with all other GLib data structures, #GQueue is not thread-safe. +For a thread-safe queue, use #GAsyncQueue. + +To create a new GQueue, use g_queue_new(). + +To initialize a statically-allocated GQueue, use #G_QUEUE_INIT or +g_queue_init(). + +To add elements, use g_queue_push_head(), g_queue_push_head_link(), +g_queue_push_tail() and g_queue_push_tail_link(). + +To remove elements, use g_queue_pop_head() and g_queue_pop_tail(). + +To free the entire queue, use g_queue_free(). + Returns a random #gboolean from @rand_. This corresponds to an unbiased coin toss. @@ -43844,6 +47825,52 @@ This corresponds to an unbiased coin toss. + + The following functions allow you to use a portable, fast and good +pseudo-random number generator (PRNG). + +Do not use this API for cryptographic purposes such as key +generation, nonces, salts or one-time pads. + +This PRNG is suitable for non-cryptographic use such as in games +(shuffling a card deck, generating levels), generating data for +a test suite, etc. If you need random data for cryptographic +purposes, it is recommended to use platform-specific APIs such +as `/dev/random` on UNIX, or CryptGenRandom() on Windows. + +GRand uses the Mersenne Twister PRNG, which was originally +developed by Makoto Matsumoto and Takuji Nishimura. Further +information can be found at +[this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html). + +If you just need a random number, you simply call the g_random_* +functions, which will create a globally used #GRand and use the +according g_rand_* functions internally. Whenever you need a +stream of reproducible random numbers, you better create a +#GRand yourself and use the g_rand_* functions directly, which +will also be slightly faster. Initializing a #GRand with a +certain seed will produce exactly the same series of random +numbers on all platforms. This can thus be used as a seed for +e.g. games. + +The g_rand*_range functions will return high quality equally +distributed random numbers, whereas for example the +`(g_random_int()%max)` approach often +doesn't yield equally distributed numbers. + +GLib changed the seeding algorithm for the pseudo-random number +generator Mersenne Twister, as used by #GRand. This was necessary, +because some seeds would yield very bad pseudo-random streams. +Also the pseudo-random integers generated by g_rand*_int_range() +will have a slightly better equal distribution with the new +version of GLib. + +The original seeding and generation algorithms, as found in +GLib 2.0.x, can be used instead of the new ones by setting the +environment variable `G_RANDOM_VERSION` to the value of '2.0'. +Use the GLib-2.0 algorithms only if you have sequences of numbers +generated with Glib-2.0 that you need to reproduce exactly. + Sets the seed for the global random number generator, which is used by the g_random_* functions, to @seed. @@ -44017,6 +48044,129 @@ resources allocated for @mem_block. + + A "reference counted box", or "RcBox", is an opaque wrapper data type +that is guaranteed to be as big as the size of a given data type, and +which augments the given data type with reference counting semantics +for its memory management. + +RcBox is useful if you have a plain old data type, like a structure +typically placed on the stack, and you wish to provide additional API +to use it on the heap; or if you want to implement a new type to be +passed around by reference without necessarily implementing copy/free +semantics or your own reference counting. + +The typical use is: + +|[<!-- language="C" --> +typedef struct { + char *name; + char *address; + char *city; + char *state; + int age; +} Person; + +Person * +person_new (void) +{ + return g_rc_box_new0 (Person); +} +]| + +Every time you wish to acquire a reference on the memory, you should +call g_rc_box_acquire(); similarly, when you wish to release a reference +you should call g_rc_box_release(): + +|[<!-- language="C" --> +// Add a Person to the Database; the Database acquires ownership +// of the Person instance +void +add_person_to_database (Database *db, Person *p) +{ + db->persons = g_list_prepend (db->persons, g_rc_box_acquire (p)); +} + +// Removes a Person from the Database; the reference acquired by +// add_person_to_database() is released here +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_rc_box_release (p); +} +]| + +If you have additional memory allocated inside the structure, you can +use g_rc_box_release_full(), which takes a function pointer, which +will be called if the reference released was the last: + +|[<!-- language="C" --> +void +person_clear (Person *p) +{ + g_free (p->name); + g_free (p->address); + g_free (p->city); + g_free (p->state); +} + +void +remove_person_from_database (Database *db, Person *p) +{ + db->persons = g_list_remove (db->persons, p); + g_rc_box_release_full (p, (GDestroyNotify) person_clear); +} +]| + +If you wish to transfer the ownership of a reference counted data +type without increasing the reference count, you can use g_steal_pointer(): + +|[<!-- language="C" --> + Person *p = g_rc_box_new (Person); + + // fill_person_details() is defined elsewhere + fill_person_details (p); + + // add_person_to_database_no_ref() is defined elsewhere; it adds + // a Person to the Database without taking a reference + add_person_to_database_no_ref (db, g_steal_pointer (&p)); +]| + +## Thread safety + +The reference counting operations on data allocated using g_rc_box_alloc(), +g_rc_box_new(), and g_rc_box_dup() are not thread safe; it is your code's +responsibility to ensure that references are acquired are released on the +same thread. + +If you need thread safe reference counting, see the [atomic reference counted +data][arcbox] API. + +## Automatic pointer clean up + +If you want to add g_autoptr() support to your plain old data type through +reference counting, you can use the G_DEFINE_AUTOPTR_CLEANUP_FUNC() and +g_rc_box_release(): + +|[<!-- language="C" --> +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, g_rc_box_release) +]| + +If you need to clear the contents of the data, you will need to use an +ancillary function that calls g_rc_box_release_full(): + +|[<!-- language="C" --> +static void +my_data_struct_release (MyDataStruct *data) +{ + // my_data_struct_clear() is defined elsewhere + g_rc_box_release_full (data, (GDestroyNotify) my_data_struct_clear); +} + +G_DEFINE_AUTOPTR_CLEANUP_FUNC (MyDataStruct, my_data_struct_release) +]| + Reallocates the memory pointed to by @mem, so that it now has space for @n_bytes bytes of memory. It returns the new address of the memory, which may @@ -44220,6 +48370,83 @@ resources allocated by the string are freed as well. + + Reference counting is a garbage collection mechanism that is based on +assigning a counter to a data type, or any memory area; the counter is +increased whenever a new reference to that data type is acquired, and +decreased whenever the reference is released. Once the last reference +is released, the resources associated to that data type are freed. + +GLib uses reference counting in many of its data types, and provides +the #grefcount and #gatomicrefcount types to implement safe and atomic +reference counting semantics in new data types. + +It is important to note that #grefcount and #gatomicrefcount should be +considered completely opaque types; you should always use the provided +API to increase and decrease the counters, and you should never check +their content directly, or compare their content with other values. + + + Reference counted strings are normal C strings that have been augmented +with a reference counter to manage their resources. You allocate a new +reference counted string and acquire and release references as needed, +instead of copying the string among callers; when the last reference on +the string is released, the resources allocated for it are freed. + +Typically, reference counted strings can be used when parsing data from +files and storing them into data structures that are passed to various +callers: + +|[<!-- language="C" --> +PersonDetails * +person_details_from_data (const char *data) +{ + // Use g_autoptr() to simplify error cases + g_autoptr(GRefString) full_name = NULL; + g_autoptr(GRefString) address = NULL; + g_autoptr(GRefString) city = NULL; + g_autoptr(GRefString) state = NULL; + g_autoptr(GRefString) zip_code = NULL; + + // parse_person_details() is defined elsewhere; returns refcounted strings + if (!parse_person_details (data, &full_name, &address, &city, &state, &zip_code)) + return NULL; + + if (!validate_zip_code (zip_code)) + return NULL; + + // add_address_to_cache() and add_full_name_to_cache() are defined + // elsewhere; they add strings to various caches, using refcounted + // strings to avoid copying data over and over again + add_address_to_cache (address, city, state, zip_code); + add_full_name_to_cache (full_name); + + // person_details_new() is defined elsewhere; it takes a reference + // on each string + PersonDetails *res = person_details_new (full_name, + address, + city, + state, + zip_code); + + return res; +} +]| + +In the example above, we have multiple functions taking the same strings +for different uses; with typical C strings, we'd have to copy the strings +every time the life time rules of the data differ from the life time of +the string parsed from the original buffer. With reference counted strings, +each caller can take a reference on the data, and keep it as long as it +needs to own the string. + +Reference counted strings can also be "interned" inside a global table +owned by GLib; while an interned string has at least a reference, creating +a new interned reference counted string with the same contents will return +a reference to the existing string instead of creating a new reference +counted string instance. Once the string loses its last reference, it will +be automatically removed from the global interned strings table. + Checks whether @replacement is a valid replacement string (see g_regex_replace()), i.e. that all escape sequences in @@ -44487,6 +48714,10 @@ on your system. + + The #GScanner and its associated functions provide a +general purpose lexical scanner. + Adds a symbol to the default scope. Use g_scanner_scope_add_symbol() instead. @@ -44552,6 +48783,50 @@ on your system. + + The #GSequence data structure has the API of a list, but is +implemented internally with a balanced binary tree. This means that +most of the operations (access, search, insertion, deletion, ...) on +#GSequence are O(log(n)) in average and O(n) in worst case for time +complexity. But, note that maintaining a balanced sorted list of n +elements is done in time O(n log(n)). +The data contained in each element can be either integer values, by using +of the [Type Conversion Macros][glib-Type-Conversion-Macros], or simply +pointers to any type of data. + +A #GSequence is accessed through "iterators", represented by a +#GSequenceIter. An iterator represents a position between two +elements of the sequence. For example, the "begin" iterator +represents the gap immediately before the first element of the +sequence, and the "end" iterator represents the gap immediately +after the last element. In an empty sequence, the begin and end +iterators are the same. + +Some methods on #GSequence operate on ranges of items. For example +g_sequence_foreach_range() will call a user-specified function on +each element with the given range. The range is delimited by the +gaps represented by the passed-in iterators, so if you pass in the +begin and end iterators, the range in question is the entire +sequence. + +The function g_sequence_get() is used with an iterator to access the +element immediately following the gap that the iterator represents. +The iterator is said to "point" to that element. + +Iterators are stable across most operations on a #GSequence. For +example an iterator pointing to some element of a sequence will +continue to point to that element even after the sequence is sorted. +Even moving an element to another sequence using for example +g_sequence_move_range() will not invalidate the iterators pointing +to it. The only operation that will invalidate an iterator is when +the element it points to is removed from any sequence. + +To sort the data, either use g_sequence_insert_sorted() or +g_sequence_insert_sorted_iter() to add data to the #GSequence or, if +you want to add a large amount of data, it is more efficient to call +g_sequence_sort() or g_sequence_sort_iter() after doing unsorted +insertions. + Returns the data that @iter points to. @@ -44916,6 +49191,15 @@ array directly to execvpe(), g_spawn_async(), or the like. + + GLib provides the functions g_shell_quote() and g_shell_unquote() +to handle shell-like quoting in strings. The function g_shell_parse_argv() +parses a string similar to the way a POSIX shell (/bin/sh) would. + +Note that string handling in shells has many obscure and historical +corner-cases which these functions do not necessarily reproduce. They +are good enough in practice, though. + @@ -45490,6 +49774,61 @@ each prime is approximately 1.5-2 times the previous prime. + + GLib supports spawning of processes with an API that is more +convenient than the bare UNIX fork() and exec(). + +The g_spawn family of functions has synchronous (g_spawn_sync()) +and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()), +as well as convenience variants that take a complete shell-like +commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()). + +See #GSubprocess in GIO for a higher-level API that provides +stream interfaces for communication with child processes. + +An example of using g_spawn_async_with_pipes(): +|[<!-- language="C" --> +const gchar * const argv[] = { "my-favourite-program", "--args", NULL }; +gint child_stdout, child_stderr; +GPid child_pid; +g_autoptr(GError) error = NULL; + +// Spawn child process. +g_spawn_async_with_pipes (NULL, argv, NULL, G_SPAWN_DO_NOT_REAP_CHILD, NULL, + NULL, &child_pid, NULL, &child_stdout, + &child_stderr, &error); +if (error != NULL) + { + g_error ("Spawning child failed: %s", error->message); + return; + } + +// Add a child watch function which will be called when the child process +// exits. +g_child_watch_add (child_pid, child_watch_cb, NULL); + +// You could watch for output on @child_stdout and @child_stderr using +// #GUnixInputStream or #GIOChannel here. + +static void +child_watch_cb (GPid pid, + gint status, + gpointer user_data) +{ + g_message ("Child %" G_PID_FORMAT " exited %s", pid, + g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally"); + + // Free any resources associated with the child here, such as I/O channels + // on its stdout and stderr FDs. If you have no code to put in the + // child_watch_cb() callback, you can remove it and the g_child_watch_add() + // call, but you must also remove the G_SPAWN_DO_NOT_REAP_CHILD flag, + // otherwise the child process will stay around as a zombie until this + // process exits. + + g_spawn_close_pid (pid); +} +]| + See g_spawn_async_with_pipes() for a full description; this function simply calls the g_spawn_async_with_pipes() without any pipes. @@ -46783,6 +51122,30 @@ If @str_array is %NULL, this function simply returns. + + String chunks are used to store groups of strings. Memory is +allocated in blocks, and as strings are added to the #GStringChunk +they are copied into the next free position in a block. When a block +is full a new block is allocated. + +When storing a large number of strings, string chunks are more +efficient than using g_strdup() since fewer calls to malloc() are +needed, and less memory is wasted in memory allocation overheads. + +By adding strings with g_string_chunk_insert_const() it is also +possible to remove duplicates. + +To create a new #GStringChunk use g_string_chunk_new(). + +To add strings to a #GStringChunk use g_string_chunk_insert(). + +To add strings to a #GStringChunk, but without duplicating strings +which are already in the #GStringChunk, use +g_string_chunk_insert_const(). + +To free the entire #GStringChunk use g_string_chunk_free(). It is +not possible to free individual strings. + Creates a new #GString, initialized with the given string. @@ -46840,6 +51203,52 @@ too often. + + This section describes a number of utility functions for creating, +duplicating, and manipulating strings. + +Note that the functions g_printf(), g_fprintf(), g_sprintf(), +g_vprintf(), g_vfprintf(), g_vsprintf() and g_vasprintf() +are declared in the header `gprintf.h` which is not included in `glib.h` +(otherwise using `glib.h` would drag in `stdio.h`), so you'll have to +explicitly include `<glib/gprintf.h>` in order to use the GLib +printf() functions. + +## String precision pitfalls # {#string-precision} + +While you may use the printf() functions to format UTF-8 strings, +notice that the precision of a \%Ns parameter is interpreted +as the number of bytes, not characters to print. On top of that, +the GNU libc implementation of the printf() functions has the +"feature" that it checks that the string given for the \%Ns +parameter consists of a whole number of characters in the current +encoding. So, unless you are sure you are always going to be in an +UTF-8 locale or your know your text is restricted to ASCII, avoid +using \%Ns. If your intention is to format strings for a +certain number of columns, then \%Ns is not a correct solution +anyway, since it fails to take wide characters (see g_unichar_iswide()) +into account. + +Note also that there are various printf() parameters which are platform +dependent. GLib provides platform independent macros for these parameters +which should be used instead. A common example is %G_GUINT64_FORMAT, which +should be used instead of `%llu` or similar parameters for formatting +64-bit integers. These macros are all named `G_*_FORMAT`; see +[Basic Types][glib-Basic-Types]. + + + A #GString is an object that handles the memory management of a C +string for you. The emphasis of #GString is on text, typically +UTF-8. Crucially, the "str" member of a #GString is guaranteed to +have a trailing nul character, and it is therefore always safe to +call functions such as strchr() or g_strdup() on it. + +However, a #GString can also hold arbitrary binary data, because it +has a "len" member, which includes any possible embedded nul +characters in the data. Conceptually then, #GString is like a +#GByteArray with the addition of many convenience methods for text, +and a guaranteed nul terminator. + An auxiliary function for gettext() support (see Q_()). @@ -47225,7 +51634,8 @@ to delimit UTF-8 strings for anything but ASCII characters. A nul-terminated string containing bytes that are used - to split the string. + to split the string (it can accept an empty string, which will result + in no string splitting). @@ -47633,8 +52043,11 @@ same relative path as the test binary. - Create a new #GTestCase, named @test_name, this API is fairly -low level, calling g_test_add() or g_test_add_func() is preferable. + Create a new #GTestCase, named @test_name. + +This API is fairly low level, and calling g_test_add() or g_test_add_func() +is preferable. + When this test is executed, a fixture structure of size @data_size will be automatically allocated and filled with zeros. Then @data_setup is called to initialize the fixture. After fixture setup, the actual test @@ -47643,10 +52056,10 @@ fixture structure is torn down by calling @data_teardown and after that the memory is automatically released by the test framework. Splitting up a test run into fixture setup, test function and -fixture teardown is most useful if the same fixture is used for +fixture teardown is most useful if the same fixture type is used for multiple tests. In this cases, g_test_create_case() will be -called with the same fixture, but varying @test_name and -@data_test arguments. +called with the same type of fixture (the @data_size argument), but varying +@test_name and @data_test arguments. a newly allocated #GTestCase. @@ -48220,16 +52633,14 @@ in a program. - Changes the behaviour of g_assert_cmpstr(), g_assert_cmpint(), -g_assert_cmpuint(), g_assert_cmphex(), g_assert_cmpfloat(), -g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(), -g_assert_error(), g_test_assert_expected_messages() and the various -g_test_trap_assert_*() macros to not abort to program, but instead + Changes the behaviour of the various `g_assert_*()` macros, +g_test_assert_expected_messages() and the various +`g_test_trap_assert_*()` macros to not abort to program, but instead call g_test_fail() and continue. (This also changes the behavior of g_test_fail() so that it will not cause the test program to abort after completing the failed test.) -Note that the g_assert_not_reached() and g_assert() are not +Note that the g_assert_not_reached() and g_assert() macros are not affected by this. This function can only be called after g_test_init(). @@ -48543,6 +52954,184 @@ message. + + GLib provides a framework for writing and maintaining unit tests +in parallel to the code they are testing. The API is designed according +to established concepts found in the other test frameworks (JUnit, NUnit, +RUnit), which in turn is based on smalltalk unit testing concepts. + +- Test case: Tests (test methods) are grouped together with their + fixture into test cases. + +- Fixture: A test fixture consists of fixture data and setup and + teardown methods to establish the environment for the test + functions. We use fresh fixtures, i.e. fixtures are newly set + up and torn down around each test invocation to avoid dependencies + between tests. + +- Test suite: Test cases can be grouped into test suites, to allow + subsets of the available tests to be run. Test suites can be + grouped into other test suites as well. + +The API is designed to handle creation and registration of test suites +and test cases implicitly. A simple call like +|[<!-- language="C" --> + g_test_add_func ("/misc/assertions", test_assertions); +]| +creates a test suite called "misc" with a single test case named +"assertions", which consists of running the test_assertions function. + +In addition to the traditional g_assert_true(), the test framework provides +an extended set of assertions for comparisons: g_assert_cmpfloat(), +g_assert_cmpfloat_with_epsilon(), g_assert_cmpint(), g_assert_cmpuint(), +g_assert_cmphex(), g_assert_cmpstr(), g_assert_cmpmem() and +g_assert_cmpvariant(). The +advantage of these variants over plain g_assert_true() is that the assertion +messages can be more elaborate, and include the values of the compared +entities. + +Note that g_assert() should not be used in unit tests, since it is a no-op +when compiling with `G_DISABLE_ASSERT`. Use g_assert() in production code, +and g_assert_true() in unit tests. + +A full example of creating a test suite with two tests using fixtures: +|[<!-- language="C" --> +#include <glib.h> +#include <locale.h> + +typedef struct { + MyObject *obj; + OtherObject *helper; +} MyObjectFixture; + +static void +my_object_fixture_set_up (MyObjectFixture *fixture, + gconstpointer user_data) +{ + fixture->obj = my_object_new (); + my_object_set_prop1 (fixture->obj, "some-value"); + my_object_do_some_complex_setup (fixture->obj, user_data); + + fixture->helper = other_object_new (); +} + +static void +my_object_fixture_tear_down (MyObjectFixture *fixture, + gconstpointer user_data) +{ + g_clear_object (&fixture->helper); + g_clear_object (&fixture->obj); +} + +static void +test_my_object_test1 (MyObjectFixture *fixture, + gconstpointer user_data) +{ + g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "initial-value"); +} + +static void +test_my_object_test2 (MyObjectFixture *fixture, + gconstpointer user_data) +{ + my_object_do_some_work_using_helper (fixture->obj, fixture->helper); + g_assert_cmpstr (my_object_get_property (fixture->obj), ==, "updated-value"); +} + +int +main (int argc, char *argv[]) +{ + setlocale (LC_ALL, ""); + + g_test_init (&argc, &argv, NULL); + + // Define the tests. + g_test_add ("/my-object/test1", MyObjectFixture, "some-user-data", + my_object_fixture_set_up, test_my_object_test1, + my_object_fixture_tear_down); + g_test_add ("/my-object/test2", MyObjectFixture, "some-user-data", + my_object_fixture_set_up, test_my_object_test2, + my_object_fixture_tear_down); + + return g_test_run (); +} +]| + +### Integrating GTest in your project + +If you are using the [Meson](http://mesonbuild.com) build system, you will +typically use the provided `test()` primitive to call the test binaries, +e.g.: + +|[<!-- language="plain" --> + test( + 'foo', + executable('foo', 'foo.c', dependencies: deps), + env: [ + 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), + 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), + ], + ) + + test( + 'bar', + executable('bar', 'bar.c', dependencies: deps), + env: [ + 'G_TEST_SRCDIR=@0@'.format(meson.current_source_dir()), + 'G_TEST_BUILDDIR=@0@'.format(meson.current_build_dir()), + ], + ) +]| + +If you are using Autotools, you're strongly encouraged to use the Automake +[TAP](https://testanything.org/) harness; GLib provides template files for +easily integrating with it: + + - [glib-tap.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib-tap.mk) + - [tap-test](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-test) + - [tap-driver.sh](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/tap-driver.sh) + +You can copy these files in your own project's root directory, and then +set up your `Makefile.am` file to reference them, for instance: + +|[<!-- language="plain" --> +include $(top_srcdir)/glib-tap.mk + +# test binaries +test_programs = \ + foo \ + bar + +# data distributed in the tarball +dist_test_data = \ + foo.data.txt \ + bar.data.txt + +# data not distributed in the tarball +test_data = \ + blah.data.txt +]| + +Make sure to distribute the TAP files, using something like the following +in your top-level `Makefile.am`: + +|[<!-- language="plain" --> +EXTRA_DIST += \ + tap-driver.sh \ + tap-test +]| + +`glib-tap.mk` will be distributed implicitly due to being included in a +`Makefile.am`. All three files should be added to version control. + +If you don't have access to the Autotools TAP harness, you can use the +[gtester][gtester] and [gtester-report][gtester-report] tools, and use +the [glib.mk](https://gitlab.gnome.org/GNOME/glib/blob/glib-2-58/glib.mk) +Automake template provided by GLib. Note, however, that since GLib 2.62, +[gtester][gtester] and [gtester-report][gtester-report] have been deprecated +in favour of using TAP. The `--tap` argument to tests is enabled by default +as of GLib 2.62. + @@ -48652,6 +53241,37 @@ regularly stop all unused threads e.g. from g_timeout_add(). + + Sometimes you wish to asynchronously fork out the execution of work +and continue working in your own thread. If that will happen often, +the overhead of starting and destroying a thread each time might be +too high. In such cases reusing already started threads seems like a +good idea. And it indeed is, but implementing this can be tedious +and error-prone. + +Therefore GLib provides thread pools for your convenience. An added +advantage is, that the threads can be shared between the different +subsystems of your program, when they are using GLib. + +To create a new thread pool, you use g_thread_pool_new(). +It is destroyed by g_thread_pool_free(). + +If you want to execute a certain task within a thread pool, +you call g_thread_pool_push(). + +To get the current number of running threads you call +g_thread_pool_get_num_threads(). To get the number of still +unprocessed tasks you call g_thread_pool_unprocessed(). To control +the maximal number of threads for a thread pool, you use +g_thread_pool_get_max_threads() and g_thread_pool_set_max_threads(). + +Finally you can control the number of unused threads, that are kept +alive by GLib for future use. The current number can be fetched with +g_thread_pool_get_num_unused_threads(). The maximal number can be +controlled by g_thread_pool_get_max_unused_threads() and +g_thread_pool_set_max_unused_threads(). All currently unused threads +can be stopped by calling g_thread_pool_stop_unused_threads(). + This function returns the #GThread corresponding to the current thread. Note that this function does not increase @@ -48663,7 +53283,7 @@ APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as g_thread_join()) on these threads. - + the #GThread representing the current thread @@ -48678,6 +53298,97 @@ This function is often used as a method to make busy wait less evil. + + Threads act almost like processes, but unlike processes all threads +of one process share the same memory. This is good, as it provides +easy communication between the involved threads via this shared +memory, and it is bad, because strange things (so called +"Heisenbugs") might happen if the program is not carefully designed. +In particular, due to the concurrent nature of threads, no +assumptions on the order of execution of code running in different +threads can be made, unless order is explicitly forced by the +programmer through synchronization primitives. + +The aim of the thread-related functions in GLib is to provide a +portable means for writing multi-threaded software. There are +primitives for mutexes to protect the access to portions of memory +(#GMutex, #GRecMutex and #GRWLock). There is a facility to use +individual bits for locks (g_bit_lock()). There are primitives +for condition variables to allow synchronization of threads (#GCond). +There are primitives for thread-private data - data that every +thread has a private instance of (#GPrivate). There are facilities +for one-time initialization (#GOnce, g_once_init_enter()). Finally, +there are primitives to create and manage threads (#GThread). + +The GLib threading system used to be initialized with g_thread_init(). +This is no longer necessary. Since version 2.32, the GLib threading +system is automatically initialized at the start of your program, +and all thread-creation functions and synchronization primitives +are available right away. + +Note that it is not safe to assume that your program has no threads +even if you don't call g_thread_new() yourself. GLib and GIO can +and will create threads for their own purposes in some cases, such +as when using g_unix_signal_source_new() or when using GDBus. + +Originally, UNIX did not have threads, and therefore some traditional +UNIX APIs are problematic in threaded programs. Some notable examples +are + +- C library functions that return data in statically allocated + buffers, such as strtok() or strerror(). For many of these, + there are thread-safe variants with a _r suffix, or you can + look at corresponding GLib APIs (like g_strsplit() or g_strerror()). + +- The functions setenv() and unsetenv() manipulate the process + environment in a not thread-safe way, and may interfere with getenv() + calls in other threads. Note that getenv() calls may be hidden behind + other APIs. For example, GNU gettext() calls getenv() under the + covers. In general, it is best to treat the environment as readonly. + If you absolutely have to modify the environment, do it early in + main(), when no other threads are around yet. + +- The setlocale() function changes the locale for the entire process, + affecting all threads. Temporary changes to the locale are often made + to change the behavior of string scanning or formatting functions + like scanf() or printf(). GLib offers a number of string APIs + (like g_ascii_formatd() or g_ascii_strtod()) that can often be + used as an alternative. Or you can use the uselocale() function + to change the locale only for the current thread. + +- The fork() function only takes the calling thread into the child's + copy of the process image. If other threads were executing in critical + sections they could have left mutexes locked which could easily + cause deadlocks in the new child. For this reason, you should + call exit() or exec() as soon as possible in the child and only + make signal-safe library calls before that. + +- The daemon() function uses fork() in a way contrary to what is + described above. It should not be used with GLib programs. + +GLib itself is internally completely thread-safe (all global data is +automatically locked), but individual data structure instances are +not automatically locked for performance reasons. For example, +you must coordinate accesses to the same #GHashTable from multiple +threads. The two notable exceptions from this rule are #GMainLoop +and #GAsyncQueue, which are thread-safe and need no further +application-level locking to be accessed from multiple threads. +Most refcounting functions such as g_object_ref() are also thread-safe. + +A common use for #GThreads is to move a long-running blocking operation out +of the main thread and into a worker thread. For GLib functions, such as +single GIO operations, this is not necessary, and complicates the code. +Instead, the `…_async()` version of the function should be used from the main +thread, eliminating the need for locking and synchronisation between multiple +threads. If an operation does need to be moved to a worker thread, consider +using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a +better choice than #GThread, as it handles thread reuse and task queueing; +#GTask uses this internally. + +However, if multiple blocking operations need to be performed in sequence, +and it is not possible to use #GTask for them, moving them to a worker thread +can clarify the code. + Converts a string containing an ISO 8601 encoded date and time to a #GTimeVal and puts it into @time_. @@ -48976,6 +53687,53 @@ See g_get_monotonic_time(). + + #GTimer records a start time, and counts microseconds elapsed since +that time. This is done somewhat differently on different platforms, +and can be tricky to get exactly right, so #GTimer provides a +portable/convenient interface. + + + #GTimeZone is a structure that represents a time zone, at no +particular point in time. It is refcounted and immutable. + +Each time zone has an identifier (for example, ‘Europe/London’) which is +platform dependent. See g_time_zone_new() for information on the identifier +formats. The identifier of a time zone can be retrieved using +g_time_zone_get_identifier(). + +A time zone contains a number of intervals. Each interval has +an abbreviation to describe it (for example, ‘PDT’), an offset to UTC and a +flag indicating if the daylight savings time is in effect during that +interval. A time zone always has at least one interval — interval 0. Note +that interval abbreviations are not the same as time zone identifiers +(apart from ‘UTC’), and cannot be passed to g_time_zone_new(). + +Every UTC time is contained within exactly one interval, but a given +local time may be contained within zero, one or two intervals (due to +incontinuities associated with daylight savings time). + +An interval may refer to a specific period of time (eg: the duration +of daylight savings time during 2010) or it may refer to many periods +of time that share the same properties (eg: all periods of daylight +savings time). It is also possible (usually for political reasons) +that some properties (like the abbreviation) change between intervals +without other properties changing. + +#GTimeZone is available since GLib 2.26. + + + A #GTrashStack is an efficient way to keep a stack of unused allocated +memory chunks. Each memory chunk is required to be large enough to hold +a #gpointer. This allows the stack to be maintained without any space +overhead, since the stack pointers can be stored inside the memory chunks. + +There is no function to create a #GTrashStack. A %NULL #GTrashStack* +is a perfectly valid empty stack. + +There is no longer any good reason to use #GTrashStack. If you have +extra pieces of memory, free() them and allocate them again later. + Returns the height of a #GTrashStack. @@ -49043,6 +53801,64 @@ which may be %NULL. + + The #GTree structure and its associated functions provide a sorted +collection of key/value pairs optimized for searching and traversing +in order. This means that most of the operations (access, search, +insertion, deletion, ...) on #GTree are O(log(n)) in average and O(n) +in worst case for time complexity. But, note that maintaining a +balanced sorted #GTree of n elements is done in time O(n log(n)). + +To create a new #GTree use g_tree_new(). + +To insert a key/value pair into a #GTree use g_tree_insert() +(O(n log(n))). + +To remove a key/value pair use g_tree_remove() (O(n log(n))). + +To look up the value corresponding to a given key, use +g_tree_lookup() and g_tree_lookup_extended(). + +To find out the number of nodes in a #GTree, use g_tree_nnodes(). To +get the height of a #GTree, use g_tree_height(). + +To traverse a #GTree, calling a function for each node visited in +the traversal, use g_tree_foreach(). + +To destroy a #GTree, use g_tree_destroy(). + + + The #GNode struct and its associated functions provide a N-ary tree +data structure, where nodes in the tree can contain arbitrary data. + +To create a new tree use g_node_new(). + +To insert a node into a tree use g_node_insert(), +g_node_insert_before(), g_node_append() and g_node_prepend(). + +To create a new node and insert it into a tree use +g_node_insert_data(), g_node_insert_data_after(), +g_node_insert_data_before(), g_node_append_data() +and g_node_prepend_data(). + +To reverse the children of a node use g_node_reverse_children(). + +To find a node use g_node_get_root(), g_node_find(), +g_node_find_child(), g_node_child_index(), g_node_child_position(), +g_node_first_child(), g_node_last_child(), g_node_nth_child(), +g_node_first_sibling(), g_node_prev_sibling(), g_node_next_sibling() +or g_node_last_sibling(). + +To get information about a node or tree use G_NODE_IS_LEAF(), +G_NODE_IS_ROOT(), g_node_depth(), g_node_n_nodes(), +g_node_n_children(), g_node_is_ancestor() or g_node_max_height(). + +To traverse a tree, calling a function for each node visited in the +traversal, use g_node_traverse() or g_node_children_foreach(). + +To remove a node or subtree from a tree use g_node_unlink() or +g_node_destroy(). + Attempts to allocate @n_bytes, and returns %NULL on failure. Contrast with g_malloc(), which aborts the program on failure. @@ -49206,6 +54022,70 @@ The function returns %NULL if an overflow occurs. + + Many times GLib, GTK+, and other libraries allow you to pass "user +data" to a callback, in the form of a void pointer. From time to time +you want to pass an integer instead of a pointer. You could allocate +an integer, with something like: +|[<!-- language="C" --> + int *ip = g_new (int, 1); + *ip = 42; +]| +But this is inconvenient, and it's annoying to have to free the +memory at some later time. + +Pointers are always at least 32 bits in size (on all platforms GLib +intends to support). Thus you can store at least 32-bit integer values +in a pointer value. Naively, you might try this, but it's incorrect: +|[<!-- language="C" --> + gpointer p; + int i; + p = (void*) 42; + i = (int) p; +]| +Again, that example was not correct, don't copy it. +The problem is that on some systems you need to do this: +|[<!-- language="C" --> + gpointer p; + int i; + p = (void*) (long) 42; + i = (int) (long) p; +]| +The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care +to do the right thing on every platform. + +Warning: You may not store pointers in integers. This is not +portable in any way, shape or form. These macros only allow storing +integers in pointers, and only preserve 32 bits of the integer; values +outside the range of a 32-bit integer will be mangled. + + + GLib defines a number of commonly used types, which can be divided +into several groups: +- New types which are not part of standard C (but are defined in + various C standard library header files) — #gboolean, #gssize. +- Integer types which are guaranteed to be the same size across + all platforms — #gint8, #guint8, #gint16, #guint16, #gint32, + #guint32, #gint64, #guint64. +- Types which are easier to use than their standard C counterparts - + #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong. +- Types which correspond exactly to standard C types, but are + included for completeness — #gchar, #gint, #gshort, #glong, + #gfloat, #gdouble. +- Types which correspond exactly to standard C99 types, but are available + to use even if your compiler does not support C99 — #gsize, #goffset, + #gintptr, #guintptr. + +GLib also defines macros for the limits of some of the standard +integer and floating point types, as well as macros for suitable +printf() formats for these types. + +Note that depending on the platform and build configuration, the format +macros might not be compatible with the system provided printf() function, +because GLib might use a different printf() implementation internally. +The format macros will always work with GLib API (like g_print()), and with +any C99 compatible printf() implementation. + Convert a string from UCS-4 to UTF-16. A 0 character will be added to the result after the converted text. @@ -49834,7 +54714,7 @@ pass both this test and g_unichar_iszerowidth(). - Determines if a character is a hexidecimal digit. + Determines if a character is a hexadecimal digit. %TRUE if the character is a hexadecimal digit @@ -49968,7 +54848,7 @@ character, though it's normally a string terminator. - Determines the numeric value of a character as a hexidecimal + Determines the numeric value of a character as a hexadecimal digit. @@ -49983,6 +54863,36 @@ g_unichar_isxdigit()), its numeric value. Otherwise, -1. + + This section describes a number of functions for dealing with +Unicode characters and strings. There are analogues of the +traditional `ctype.h` character classification and case conversion +functions, UTF-8 analogues of some string utility functions, +functions to perform normalization, case conversion and collation +on UTF-8 strings and finally functions to convert between the UTF-8, +UTF-16 and UCS-4 encodings of Unicode. + +The implementations of the Unicode functions in GLib are based +on the Unicode Character Data tables, which are available from +[www.unicode.org](http://www.unicode.org/). + + * Unicode 4.0 was added in GLib 2.8 + * Unicode 4.1 was added in GLib 2.10 + * Unicode 5.0 was added in GLib 2.12 + * Unicode 5.1 was added in GLib 2.16.3 + * Unicode 6.0 was added in GLib 2.30 + * Unicode 6.1 was added in GLib 2.32 + * Unicode 6.2 was added in GLib 2.36 + * Unicode 6.3 was added in GLib 2.40 + * Unicode 7.0 was added in GLib 2.42 + * Unicode 8.0 was added in GLib 2.48 + * Unicode 9.0 was added in GLib 2.50.1 + * Unicode 10.0 was added in GLib 2.54 + * Unicode 11.10 was added in GLib 2.58 + * Unicode 12.0 was added in GLib 2.62 + * Unicode 12.1 was added in GLib 2.62 + * Unicode 13.0 was added in GLib 2.66 + Computes the canonical decomposition of a Unicode character. Use the more flexible g_unichar_fully_decompose() @@ -50391,19 +55301,162 @@ array directly to execvpe(), g_spawn_async(), or the like. - - Escapes a string for use in a URI. + + Creates a new #GUri from the given components according to @flags. -Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical -characters plus dash, dot, underscore and tilde) are escaped. -But if you specify characters in @reserved_chars_allowed 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. +See also g_uri_build_with_user(), which allows specifying the +components of the "userinfo" separately. - an escaped version of @unescaped. The returned string should be -freed when no longer needed. + a new #GUri + + + + + flags describing how to build the #GUri + + + + the URI scheme + + + + the userinfo component, or %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + Creates a new #GUri from the given components according to @flags +(%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be +coherent with the passed values, in particular use `%`-encoded values with +%G_URI_FLAGS_ENCODED. + +In contrast to g_uri_build(), this allows specifying the components +of the ‘userinfo’ field separately. Note that @user must be non-%NULL +if either @password or @auth_params is non-%NULL. + + + a new #GUri + + + + + flags describing how to build the #GUri + + + + the URI scheme + + + + the user component of the userinfo, or %NULL + + + + the password component of the userinfo, or %NULL + + + + the auth params of the userinfo, or %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + + + + + + Escapes arbitrary data for use in a URI. + +Normally all characters that are not ‘unreserved’ (i.e. ASCII +alphanumerical characters plus dash, dot, underscore and tilde) are +escaped. But if you specify characters in @reserved_chars_allowed +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. + +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. + + + + + the unescaped input data. + + + + + + the length of @unescaped + + + + a string of reserved + characters that are allowed to be used, or %NULL. + + + + + + Escapes a string for use in a URI. + +Normally all characters that are not "unreserved" (i.e. ASCII +alphanumerical characters plus dash, dot, underscore and tilde) are +escaped. But if you specify characters in @reserved_chars_allowed +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. @@ -50412,8 +55465,8 @@ freed when no longer needed. - a string of reserved characters that - are allowed to be used, or %NULL. + a string of reserved + characters that are allowed to be used, or %NULL. @@ -50422,7 +55475,147 @@ freed when no longer needed. - + + Parses @uri_string according to @flags, to determine whether it is a valid +[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved +relative to another URI using g_uri_parse_relative(). + +If it’s not a valid URI, an error is returned explaining how it’s invalid. + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags. + + + %TRUE if @uri_string is a valid absolute URI, %FALSE on error. + + + + + a string containing an absolute URI + + + + flags for parsing @uri_string + + + + + + Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +When @host is present, @path must either be empty or begin with a slash (`/`) +character. When @host is not present, @path cannot begin with two slash + characters (`//`). See +[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3). + +See also g_uri_join_with_user(), which allows specifying the +components of the ‘userinfo’ separately. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags. + + + an absolute URI string + + + + + flags describing how to build the URI string + + + + the URI scheme, or %NULL + + + + the userinfo component, or %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + + Joins the given components together according to @flags to create +an absolute URI string. @path may not be %NULL (though it may be the empty +string). + +In contrast to g_uri_join(), this allows specifying the components +of the ‘userinfo’ separately. It otherwise behaves the same. + +%G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set +in @flags. + + + an absolute URI string + + + + + flags describing how to build the URI string + + + + the URI scheme, or %NULL + + + + the user component of the userinfo, or %NULL + + + + the password component of the userinfo, or + %NULL + + + + the auth params of the userinfo, or + %NULL + + + + the host component, or %NULL + + + + the port, or `-1` + + + + the path component + + + + the query component, or %NULL + + + + the fragment, or %NULL + + + + + Splits an URI list conforming to the text/uri-list mime type defined in RFC 2483 into individual URIs, discarding any comments. The URIs are not validated. @@ -50442,16 +55635,97 @@ discarding any comments. The URIs are not validated. - - Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as: + + Parses @uri_string according to @flags. If the result is not a +valid [absolute URI][relative-absolute-uris], it will be discarded, and an +error returned. + + + a new #GUri. + + + + + a string representing an absolute URI + + + + flags describing how to parse @uri_string + + + + + + Many URI schemes include one or more attribute/value pairs as part of the URI +value. This method can be used to parse them into a hash table. When an +attribute has multiple occurrences, the last value is the final returned +value. If you need to handle repeated attributes differently, use +#GUriParamsIter. + +The @params string is assumed to still be `%`-encoded, but the returned +values will be fully decoded. (Thus it is possible that the returned values +may contain `=` or @separators, if the value was encoded in the input.) +Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED +rules for g_uri_parse(). (However, if @params is the path or query string +from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and +%G_URI_FLAGS_ENCODED, then you already know that it does not contain any +invalid encoding.) + +%G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init(). + +If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be +compared case-insensitively, so a params string `attr=123&Attr=456` will only +return a single attribute–value pair, `Attr=456`. Case will be preserved in +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 `%`-encoded string containing `attribute=value` + parameters + + + + the length of @params, or `-1` if it is nul-terminated + + + + the separator byte character set between parameters. (usually + `&`, but sometimes `;` or both `&;`). Note that this function works on + bytes not characters, so it can't be used to delimit UTF-8 strings for + anything but ASCII characters. You may pass an empty set, in which case + no splitting will occur. + + + + flags to modify the way the parameters are handled. + + + + + + Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: |[ URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] ]| -Common schemes include "file", "http", "svn+ssh", etc. +Common schemes include `file`, `https`, `svn+ssh`, etc. - - The "Scheme" component of the URI, or %NULL on error. -The returned string should be freed when no longer needed. + + The ‘scheme’ component of the URI, or + %NULL on error. The returned string should be freed when no longer needed. @@ -50461,14 +55735,287 @@ The returned string should be freed when no longer needed. - + + Gets the scheme portion of a URI string. +[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme +as: +|[ +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +]| +Common schemes include `file`, `https`, `svn+ssh`, etc. + +Unlike g_uri_parse_scheme(), the returned scheme is normalized to +all-lowercase and does not need to be freed. + + + The ‘scheme’ component of the URI, or + %NULL on error. The returned string is normalized to all-lowercase, and + interned via g_intern_string(), so it does not need to be freed. + + + + + a valid URI. + + + + + + Parses @uri_ref according to @flags and, if it is a +[relative URI][relative-absolute-uris], resolves it relative to +@base_uri_string. If the result is not a valid absolute URI, it will be +discarded, and an error returned. + +(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. + + + + + a string representing a base URI + + + + a string representing a relative or absolute URI + + + + flags describing how to parse @uri_ref + + + + + + Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in +@uri_ref will remain encoded in the output strings. (If not, +then all such characters will be decoded.) Note that decoding will +only work if the URI components are ASCII or UTF-8, so you will +need to use %G_URI_FLAGS_ENCODED if they are not. + +Note that the %G_URI_FLAGS_HAS_PASSWORD and +%G_URI_FLAGS_HAS_AUTH_PARAMS @flags are ignored by g_uri_split(), +since it always returns only the full userinfo; use +g_uri_split_with_user() if you want it split up. + + + %TRUE if @uri_ref parsed successfully, %FALSE + on error. + + + + + a string containing a relative or absolute URI + + + + flags for parsing @uri_ref + + + + on return, contains + the scheme (converted to lowercase), or %NULL + + + + on return, contains + the userinfo, or %NULL + + + + on return, contains the + host, or %NULL + + + + on return, contains the + port, or `-1` + + + + on return, contains the + path + + + + on return, contains the + query, or %NULL + + + + on return, contains + the fragment, or %NULL + + + + + + Parses @uri_string (which must be an [absolute URI][relative-absolute-uris]) +according to @flags, and returns the pieces relevant to connecting to a host. +See the documentation for g_uri_split() for more details; this is +mostly a wrapper around that function with simpler arguments. +However, it will return an error if @uri_string is a relative URI, +or does not contain a hostname component. + + + %TRUE if @uri_string parsed successfully, + %FALSE on error. + + + + + a string containing an absolute URI + + + + flags for parsing @uri_string + + + + on return, contains + the scheme (converted to lowercase), or %NULL + + + + on return, contains the + host, or %NULL + + + + on return, contains the + port, or `-1` + + + + + + Parses @uri_ref (which can be an +[absolute or relative URI][relative-absolute-uris]) according to @flags, and +returns the pieces. Any component that doesn't appear in @uri_ref will be +returned as %NULL (but note that all URIs always have a path component, +though it may be the empty string). + +See g_uri_split(), and the definition of #GUriFlags, for more +information on the effect of @flags. Note that @password will only +be parsed out if @flags contains %G_URI_FLAGS_HAS_PASSWORD, and +@auth_params will only be parsed out if @flags contains +%G_URI_FLAGS_HAS_AUTH_PARAMS. + + + %TRUE if @uri_ref parsed successfully, %FALSE + on error. + + + + + a string containing a relative or absolute URI + + + + flags for parsing @uri_ref + + + + on return, contains + the scheme (converted to lowercase), or %NULL + + + + on return, contains + the user, or %NULL + + + + on return, contains + the password, or %NULL + + + + on return, contains + the auth_params, or %NULL + + + + on return, contains the + host, or %NULL + + + + on return, contains the + port, or `-1` + + + + on return, contains the + path + + + + on return, contains the + query, or %NULL + + + + on return, contains + the fragment, or %NULL + + + + + + Unescapes a segment of an escaped string as binary data. + +Note that in contrast to g_uri_unescape_string(), this does allow +nul bytes to appear in the output. + +If any of the characters in @illegal_characters 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 or %NULL on + error (if decoding failed, using %G_URI_ERROR_FAILED error code). The + returned #GBytes should be unreffed when no longer needed. + + + + + A URI-escaped string + + + + the length (in bytes) of @escaped_string to escape, or `-1` if it + is nul-terminated. + + + + a string of illegal characters + not to be allowed, or %NULL. + + + + + Unescapes a segment of an escaped string. -If any of the characters in @illegal_characters or the character zero appears -as an escaped character in @escaped_string then that is an error and %NULL -will be returned. This is useful it you want to avoid for instance having a -slash being expanded in an escaped path element, which might confuse pathname -handling. +If any of the characters in @illegal_characters or the NUL +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. + +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. @@ -50483,23 +56030,25 @@ will return %NULL. - Pointer to end of @escaped_string, may be %NULL + Pointer to end of @escaped_string, + may be %NULL - An optional string of illegal characters not to be allowed, may be %NULL + An optional string of illegal + characters not to be allowed, may be %NULL - + Unescapes a whole escaped string. -If any of the characters in @illegal_characters or the character zero appears -as an escaped character in @escaped_string then that is an error and %NULL -will be returned. This is useful it you want to avoid for instance having a -slash being expanded in an escaped path element, which might confuse pathname -handling. +If any of the characters in @illegal_characters or the NUL +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 @@ -50512,8 +56061,8 @@ should be freed when no longer needed. - a string of illegal characters not to be - allowed, or %NULL. + a string of illegal characters + not to be allowed, or %NULL. @@ -50578,7 +56127,7 @@ terminated with a 0 byte. Note that the input is expected to be already in native endianness, an initial byte-order-mark character is not handled specially. g_convert() can be used to convert a byte buffer of UTF-16 data of -ambiguous endianess. +ambiguous endianness. Further note that this function does not validate the result string; it may e.g. include embedded NUL characters. The only @@ -51358,6 +56907,21 @@ will always return %FALSE if any of the bytes of @str are nul. + + A UUID, or Universally unique identifier, is intended to uniquely +identify information in a distributed environment. For the +definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html). + +The creation of UUIDs does not require a centralized authority. + +UUIDs are of relatively small size (128 bits, or 16 bytes). The +common string representation (ex: +1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes. + +The UUID specification defines 5 versions, and calling +g_uuid_string_random() will generate a unique (or rather random) +UUID of the most common version, version 4. + Parses the string @str and verify if it is a UUID. @@ -51660,6 +57224,23 @@ multibyte representation is available for the given character. + + GLib provides version information, primarily useful in configure +checks for builds that have a configure script. Applications will +not typically use the features described here. + +The GLib headers annotate deprecated APIs in a way that produces +compiler warnings if these deprecated APIs are used. The warnings +can be turned off by defining the macro %GLIB_DISABLE_DEPRECATION_WARNINGS +before including the glib.h header. + +GLib also provides support for building applications against +defined subsets of deprecated or new GLib APIs. Define the macro +%GLIB_VERSION_MIN_REQUIRED to specify up to what version of GLib +you want to receive warnings about deprecated APIs. Define the +macro %GLIB_VERSION_MAX_ALLOWED to specify the newest version of +GLib whose API you want to use. + An implementation of the standard fprintf() function which supports positional parameters, as specified in the Single Unix Specification. @@ -51818,5 +57399,51 @@ and g_warn_if_fail() macros. + + GLib defines several warning functions and assertions which can be used to +warn of programmer errors when calling functions, and print error messages +from command line programs. + +The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and +g_return_val_if_reached() macros are intended as pre-condition assertions, to +be used at the top of a public function to check that the function’s +arguments are acceptable. Any failure of such a pre-condition assertion is +considered a programming error on the part of the caller of the public API, +and the program is considered to be in an undefined state afterwards. They +are similar to the libc assert() function, but provide more context on +failures. + +For example: +|[<!-- language="C" --> +gboolean +g_dtls_connection_shutdown (GDtlsConnection *conn, + gboolean shutdown_read, + gboolean shutdown_write, + GCancellable *cancellable, + GError **error) +{ + // local variable declarations + + g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE); + g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); + g_return_val_if_fail (error == NULL || *error == NULL, FALSE); + + // function body + + return return_val; +} +]| + +g_print(), g_printerr() and g_set_print_handler() are intended to be used for +output from command line applications, since they output to standard output +and standard error by default — whereas functions like g_message() and +g_log() may be redirected to special purpose message windows, files, or the +system journal. + + + These functions provide some level of UNIX emulation on the +Windows platform. If your application really needs the POSIX +APIs, we suggest you try the Cygwin project. + diff --git a/gir-files/GModule-2.0.gir b/gir-files/GModule-2.0.gir index a873bc978..28d054622 100644 --- a/gir-files/GModule-2.0.gir +++ b/gir-files/GModule-2.0.gir @@ -262,5 +262,79 @@ directory it will return `\Windows\mylibrary.dll`. + + These functions provide a portable way to dynamically load object files +(commonly known as 'plug-ins'). The current implementation supports all +systems that provide an implementation of dlopen() (e.g. Linux/Sun), as +well as Windows platforms via DLLs. + +A program which wants to use these functions must be linked to the +libraries output by the command `pkg-config --libs gmodule-2.0`. + +To use them you must first determine whether dynamic loading +is supported on the platform by calling g_module_supported(). +If it is, you can open a module with g_module_open(), +find the module's symbols (e.g. function names) with g_module_symbol(), +and later close the module with g_module_close(). +g_module_name() will return the file name of a currently opened module. + +If any of the above functions fail, the error status can be found with +g_module_error(). + +The #GModule implementation features reference counting for opened modules, +and supports hook functions within a module which are called when the +module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). + +If your module introduces static data to common subsystems in the running +program, e.g. through calling +`g_quark_from_static_string ("my-module-stuff")`, +it must ensure that it is never unloaded, by calling g_module_make_resident(). + +Example: Calling a function defined in a GModule +|[<!-- language="C" --> +// the function signature for 'say_hello' +typedef void (* SayHelloFunc) (const char *message); + +gboolean +just_say_hello (const char *filename, GError **error) +{ + SayHelloFunc say_hello; + GModule *module; + + module = g_module_open (filename, G_MODULE_BIND_LAZY); + if (!module) + { + g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH, + "%s", g_module_error ()); + return FALSE; + } + + if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello)) + { + g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, + "%s: %s", filename, g_module_error ()); + if (!g_module_close (module)) + g_warning ("%s: %s", filename, g_module_error ()); + return FALSE; + } + + if (say_hello == NULL) + { + g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, + "symbol say_hello is NULL"); + if (!g_module_close (module)) + g_warning ("%s: %s", filename, g_module_error ()); + return FALSE; + } + + // call our function in the module + say_hello ("Hello world!"); + + if (!g_module_close (module)) + g_warning ("%s: %s", filename, g_module_error ()); + return TRUE; + } +]| + diff --git a/gir-files/GObject-2.0.gir b/gir-files/GObject-2.0.gir index 8a729057f..c13b8bc9c 100644 --- a/gir-files/GObject-2.0.gir +++ b/gir-files/GObject-2.0.gir @@ -3040,7 +3040,7 @@ initial reference count, if it is unowned, we instead can write: g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); ]| -Generally, this function is used together with g_closure_ref(). Ane example +Generally, this function is used together with g_closure_ref(). An example of storing a closure for later notification looks like: |[<!-- language="C" --> static GClosure *notify_closure = NULL; @@ -4745,7 +4745,9 @@ to the #GObject implementation and should never be accessed directly. Creates a new instance of a #GObject subtype and sets its properties. Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) -which are not explicitly specified are set to their default values. +which are not explicitly specified are set to their default values. Any +private data for the object is guaranteed to be initialized with zeros, as +per g_type_create_instance(). Note that in C, small integer types in variable argument lists are promoted up to #gint or #guint as appropriate, and read back accordingly. #gint is 32 @@ -6126,7 +6128,7 @@ Note that the @destroy callback is not called if @data is %NULL. This sets an opaque, named pointer on an object. -The name is specified through a #GQuark (retrived e.g. via +The name is specified through a #GQuark (retrieved e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the @object with g_object_get_qdata() until the @object is finalized. @@ -6270,7 +6272,7 @@ object_add_to_user_list (GObject *object, { // the quark, naming the object data GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); - // retrive the old string list + // retrieve the old string list GList *list = g_object_steal_qdata (object, quark_string_list); // prepend new string @@ -7326,8 +7328,8 @@ required to specify parameters, such as e.g. #GObject properties. ## Parameter names # {#canonical-parameter-names} -A property name consists of segments consisting of ASCII letters and -digits, separated by either the `-` or `_` character. The first +A property name consists of one or more segments consisting of ASCII letters +and digits, separated by either the `-` or `_` character. The first character of a property name must be a letter. These are the same rules as for signal naming (see g_signal_new()). @@ -7375,6 +7377,25 @@ e.g. a tooltip. The @nick and @blurb should ideally be localized. + + Validate a property name for a #GParamSpec. This can be useful for +dynamically-generated properties which need to be validated at run-time +before actually trying to create them. + +See [canonical parameter names][canonical-parameter-names] for details of +the rules for valid names. + + + %TRUE if @name is a valid property name, %FALSE otherwise. + + + + + the canonical name of the property + + + + @@ -7998,7 +8019,7 @@ properties. another paramspec. All operations other than getting or setting the value are redirected, including accessing the nick and blurb, validating a value, and so forth. See -g_param_spec_get_redirect_target() for retrieving the overidden +g_param_spec_get_redirect_target() for retrieving the overridden property. #GParamSpecOverride is used in implementing g_object_class_override_property(), and will not be directly useful unless you are implementing a new base type similar to GObject. @@ -10676,10 +10697,26 @@ from type %G_TYPE_BOXED. + + For string values, indicates that the string contained is canonical and will +exist for the duration of the process. See g_value_set_interned_string(). + + + + + Checks whether @value contains a string which is canonical. + + + + a valid #GValue structure + + + If passed to G_VALUE_COLLECT(), allocated data won't be copied but used verbatim. This does not affect ref-counted types like -objects. +objects. This does not affect usage of g_value_copy(), the data will +be copied if it is not ref-counted. @@ -11455,6 +11492,25 @@ value_table's collect_value() function. + + Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is +assumed to be static and interned (canonical, for example from +g_intern_string()), and is thus not duplicated when setting the #GValue. + + + + + + + a valid #GValue of type %G_TYPE_STRING + + + + static string to be set + + + + Set the contents of a %G_TYPE_LONG #GValue to @v_long. @@ -11608,7 +11664,10 @@ when setting the #GValue. Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is assumed to be static, and is thus not duplicated -when setting the #GValue. +when setting the #GValue. + +If the the string is a canonical string, using g_value_set_interned_string() +is more appropriate. @@ -13559,6 +13618,35 @@ may change in the future. + + The GLib type system provides fundamental types for enumeration and +flags types. (Flags types are like enumerations, but allow their +values to be combined by bitwise or). A registered enumeration or +flags type associates a name and a nickname with each allowed +value, and the methods g_enum_get_value_by_name(), +g_enum_get_value_by_nick(), g_flags_get_value_by_name() and +g_flags_get_value_by_nick() can look up values by their name or +nickname. When an enumeration or flags type is registered with the +GLib type system, it can be used as value type for object +properties, using g_param_spec_enum() or g_param_spec_flags(). + +GObject ships with a utility called [glib-mkenums][glib-mkenums], +that can construct suitable type registration functions from C enumeration +definitions. + +Example of how to get a string representation of an enum value: +|[<!-- language="C" --> +GEnumClass *enum_class; +GEnumValue *enum_value; + +enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); +enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); + +g_print ("Name: %s\n", enum_value->value_name); + +g_type_class_unref (enum_class); +]| + This function is meant to be called from the complete_type_info() function of a #GTypePlugin implementation, see the example for @@ -13687,12 +13775,231 @@ may change in the future. + + #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only +thing the type system needs to know about the structures is how to copy them +(a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that +they are treated as opaque chunks of memory. + +Boxed types are useful for simple value-holder structures like rectangles or +points. They can also be used for wrapping structures defined in non-#GObject +based libraries. They allow arbitrary structures to be handled in a uniform +way, allowing uniform copying (or referencing) and freeing (or unreferencing) +of them, and uniform representation of the type of the contained structure. +In turn, this allows any type which can be boxed to be set as the data in a +#GValue, which allows for polymorphic handling of a much wider range of data +types, and hence usage of such types as #GObject property values. + +#GBoxed is designed so that reference counted types can be boxed. Use the +type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the +#GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is +g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref(). + + + The #GValue structure is basically a variable container that consists +of a type identifier and a specific value of that type. +The type identifier within a #GValue structure always determines the +type of the associated value. +To create an undefined #GValue structure, simply create a zero-filled +#GValue structure. To initialize the #GValue, use the g_value_init() +function. A #GValue cannot be used until it is initialized. +The basic type operations (such as freeing and copying) are determined +by the #GTypeValueTable associated with the type ID stored in the #GValue. +Other #GValue operations (such as converting values between types) are +provided by this interface. + +The code in the example program below demonstrates #GValue's +features. + +|[<!-- language="C" --> +#include <glib-object.h> + +static void +int2string (const GValue *src_value, + GValue *dest_value) +{ + if (g_value_get_int (src_value) == 42) + g_value_set_static_string (dest_value, "An important number"); + else + g_value_set_static_string (dest_value, "What's that?"); +} + +int +main (int argc, + char *argv[]) +{ + // GValues must be initialized + GValue a = G_VALUE_INIT; + GValue b = G_VALUE_INIT; + const gchar *message; + + // The GValue starts empty + g_assert (!G_VALUE_HOLDS_STRING (&a)); + + // Put a string in it + g_value_init (&a, G_TYPE_STRING); + g_assert (G_VALUE_HOLDS_STRING (&a)); + g_value_set_static_string (&a, "Hello, world!"); + g_printf ("%s\n", g_value_get_string (&a)); + + // Reset it to its pristine state + g_value_unset (&a); + + // It can then be reused for another type + g_value_init (&a, G_TYPE_INT); + g_value_set_int (&a, 42); + + // Attempt to transform it into a GValue of type STRING + g_value_init (&b, G_TYPE_STRING); + + // An INT is transformable to a STRING + g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); + + g_value_transform (&a, &b); + g_printf ("%s\n", g_value_get_string (&b)); + + // Attempt to transform it again using a custom transform function + g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); + g_value_transform (&a, &b); + g_printf ("%s\n", g_value_get_string (&b)); + return 0; +} +]| + + + The GType API is the foundation of the GObject system. It provides the +facilities for registering and managing all fundamental data types, +user-defined object and interface types. + +For type creation and registration purposes, all types fall into one of +two categories: static or dynamic. Static types are never loaded or +unloaded at run-time as dynamic types may be. Static types are created +with g_type_register_static() that gets type specific information passed +in via a #GTypeInfo structure. + +Dynamic types are created with g_type_register_dynamic() which takes a +#GTypePlugin structure instead. The remaining type information (the +#GTypeInfo structure) is retrieved during runtime through #GTypePlugin +and the g_type_plugin_*() API. + +These registration functions are usually called only once from a +function whose only purpose is to return the type identifier for a +specific class. Once the type (or class or interface) is registered, +it may be instantiated, inherited, or implemented depending on exactly +what sort of type it is. + +There is also a third registration function for registering fundamental +types called g_type_register_fundamental() which requires both a #GTypeInfo +structure and a #GTypeFundamentalInfo structure but it is seldom used +since most fundamental types are predefined rather than user-defined. + +Type instance and class structs are limited to a total of 64 KiB, +including all parent types. Similarly, type instances' private data +(as created by G_ADD_PRIVATE()) are limited to a total of +64 KiB. If a type instance needs a large static buffer, allocate it +separately (typically by using #GArray or #GPtrArray) and put a pointer +to the buffer in the structure. + +As mentioned in the [GType conventions][gtype-conventions], type names must +be at least three characters long. There is no upper length limit. The first +character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent +characters can be letters, numbers or any of ‘-_+’. + + + GObject is the fundamental type providing the common attributes and +methods for all object types in GTK+, Pango and other libraries +based on GObject. The GObject class provides methods for object +construction and destruction, property access methods, and signal +support. Signals are described in detail [here][gobject-Signals]. + +For a tutorial on implementing a new GObject class, see [How to define and +implement a new GObject][howto-gobject]. For a list of naming conventions for +GObjects and their methods, see the [GType conventions][gtype-conventions]. +For the high-level concepts behind GObject, read [Instantiable classed types: +Objects][gtype-instantiable-classed]. + +## Floating references # {#floating-ref} + +**Note**: Floating references are a C convenience API and should not be +used in modern GObject code. Language bindings in particular find the +concept highly problematic, as floating references are not identifiable +through annotations, and neither are deviations from the floating reference +behavior, like types that inherit from #GInitiallyUnowned and still return +a full reference from g_object_new(). + +GInitiallyUnowned is derived from GObject. The only difference between +the two is that the initial reference of a GInitiallyUnowned is flagged +as a "floating" reference. This means that it is not specifically +claimed to be "owned" by any code portion. The main motivation for +providing floating references is C convenience. In particular, it +allows code to be written as: +|[<!-- language="C" --> +container = create_container (); +container_add_child (container, create_child()); +]| +If container_add_child() calls g_object_ref_sink() on the passed-in child, +no reference of the newly created child is leaked. Without floating +references, container_add_child() can only g_object_ref() the new child, +so to implement this code without reference leaks, it would have to be +written as: +|[<!-- language="C" --> +Child *child; +container = create_container (); +child = create_child (); +container_add_child (container, child); +g_object_unref (child); +]| +The floating reference can be converted into an ordinary reference by +calling g_object_ref_sink(). For already sunken objects (objects that +don't have a floating reference anymore), g_object_ref_sink() is equivalent +to g_object_ref() and returns a new reference. + +Since floating references are useful almost exclusively for C convenience, +language bindings that provide automated reference and memory ownership +maintenance (such as smart pointers or garbage collection) should not +expose floating references in their API. The best practice for handling +types that have initially floating references is to immediately sink those +references after g_object_new() returns, by checking if the #GType +inherits from #GInitiallyUnowned. For instance: + +|[<!-- language="C" --> +GObject *res = g_object_new_with_properties (gtype, + n_props, + prop_names, + prop_values); + +// or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) +if (G_IS_INITIALLY_UNOWNED (res)) + g_object_ref_sink (res); + +return res; +]| + +Some object implementations may need to save an objects floating state +across certain code portions (an example is #GtkMenu), to achieve this, +the following sequence can be used: + +|[<!-- language="C" --> +// save floating state +gboolean was_floating = g_object_is_floating (object); +g_object_ref_sink (object); +// protected code portion + +... + +// restore floating state +if (was_floating) + g_object_force_floating (object); +else + g_object_unref (object); // release previously acquired reference +]| + Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN property. In many cases, it may be more appropriate to use an enum with @@ -14587,7 +14894,7 @@ g_param_value_validate(). - souce #GValue + source #GValue @@ -14637,6 +14944,19 @@ without modifications + + #GValue provides an abstract container structure which can be +copied, transformed and compared while holding a value of any +(derived) type, which is registered as a #GType with a +#GTypeValueTable in its #GTypeInfo structure. Parameter +specifications for most value types can be created as #GParamSpec +derived instances, to implement e.g. #GObject properties which +operate on #GValue containers. + +Parameter names need to start with a letter (a-z or A-Z). Subsequent +characters can be letters, numbers or a '-'. +All other characters are replaced by a '-' during construction. + Ensures that the contents of @value comply with the specifications set out by @pspec. For example, a #GParamSpecInt might require @@ -14738,7 +15058,7 @@ One convenient usage of this function is in implementing property setters: Updates a pointer to weakly refer to @new_object. It assigns @new_object to @weak_pointer_location and ensures that @weak_pointer_location will -automaticaly be set to %NULL if @new_object gets destroyed. The assignment +automatically be set to %NULL if @new_object gets destroyed. The assignment is not atomic. The weak reference is not thread-safe, see g_object_add_weak_pointer() for details. @@ -15276,7 +15596,7 @@ specified signal returns a value, but may be ignored otherwise. Blocks a handler of an instance so it will not be called during any signal emissions unless it is unblocked again. Thus "blocking" a -signal handler means to temporarily deactive it, a signal handler +signal handler means to temporarily deactivate it, a signal handler has to be unblocked exactly the same amount of times it has been blocked before to become active again. @@ -15660,6 +15980,25 @@ of building the arguments. + + Validate a signal name. This can be useful for dynamically-generated signals +which need to be validated at run-time before actually trying to create them. + +See [canonical parameter names][canonical-parameter-names] for details of +the rules for valid names. The rules for signal names are the same as those +for property names. + + + %TRUE if @name is a valid signal name, %FALSE otherwise. + + + + + the canonical name of the signal + + + + Lists the signals by id that a certain instance or interface type created. Further information about the signals can be acquired through @@ -15813,7 +16152,7 @@ This is a variant of g_signal_new() that takes a C callback instead of a class offset for the signal's class handler. This function doesn't need a function pointer exposed in the class structure of an object definition, instead the function pointer is passed -directly and can be overriden by derived classes with +directly and can be overridden by derived classes with g_signal_override_class_closure() or g_signal_override_class_handler()and chained to with g_signal_chain_from_overridden() or @@ -16224,6 +16563,92 @@ identified by @itype. + + The basic concept of the signal system is that of the emission +of a signal. Signals are introduced per-type and are identified +through strings. Signals introduced for a parent type are available +in derived types as well, so basically they are a per-type facility +that is inherited. + +A signal emission mainly involves invocation of a certain set of +callbacks in precisely defined manner. There are two main categories +of such callbacks, per-object ones and user provided ones. +(Although signals can deal with any kind of instantiatable type, I'm +referring to those types as "object types" in the following, simply +because that is the context most users will encounter signals in.) +The per-object callbacks are most often referred to as "object method +handler" or "default (signal) handler", while user provided callbacks are +usually just called "signal handler". + +The object method handler is provided at signal creation time (this most +frequently happens at the end of an object class' creation), while user +provided handlers are frequently connected and disconnected to/from a +certain signal on certain object instances. + +A signal emission consists of five stages, unless prematurely stopped: + +1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + +2. Invocation of normal user-provided signal handlers (where the @after + flag is not set) + +3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + +4. Invocation of user provided signal handlers (where the @after flag is set) + +5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + +The user-provided signal handlers are called in the order they were +connected in. + +All handlers may prematurely stop a signal emission, and any number of +handlers may be connected, disconnected, blocked or unblocked during +a signal emission. + +There are certain criteria for skipping user handlers in stages 2 and 4 +of a signal emission. + +First, user handlers may be blocked. Blocked handlers are omitted during +callback invocation, to return from the blocked state, a handler has to +get unblocked exactly the same amount of times it has been blocked before. + +Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional +@detail argument passed in to g_signal_emit() has to match the detail +argument of the signal handler currently subject to invocation. +Specification of no detail argument for signal handlers (omission of the +detail part of the signal specification upon connection) serves as a +wildcard and matches any detail argument passed in to emission. + +While the @detail argument is typically used to pass an object property name +(as with #GObject::notify), no specific format is mandated for the detail +string, other than that it must be non-empty. + +## Memory management of signal handlers # {#signal-memory-management} + +If you are connecting handlers to signals and using a #GObject instance as +your signal handler user data, you should remember to pair calls to +g_signal_connect() with calls to g_signal_handler_disconnect() or +g_signal_handlers_disconnect_by_func(). While signal handlers are +automatically disconnected when the object emitting the signal is finalised, +they are not automatically disconnected when the signal handler user data is +destroyed. If this user data is a #GObject instance, using it from a +signal handler after it has been finalised is an error. + +There are two strategies for managing such user data. The first is to +disconnect the signal handler (using g_signal_handler_disconnect() or +g_signal_handlers_disconnect_by_func()) when the user data (object) is +finalised; this has to be implemented manually. For non-threaded programs, +g_signal_connect_object() can be used to implement this automatically. +Currently, however, it is unsafe to use in threaded programs. + +The second is to hold a strong reference on the user data until after the +signal is disconnected for other reasons. This can be implemented +automatically using g_signal_connect_data(). + +The first approach is recommended, as the second approach can result in +effective memory leaks of the user data if the signal handler is never +disconnected for some reason. + Set the callback for a source as a #GClosure. @@ -16638,7 +17063,7 @@ can be instantiated. The type system only performs basic allocation and structure setups for instances: actual instance creation should happen through functions supplied by the type's fundamental type implementation. So use of g_type_create_instance() is reserved for -implementators of fundamental types only. E.g. instances of the +implementers of fundamental types only. E.g. instances of the #GObject hierarchy should be created via g_object_new() and never directly through g_type_create_instance() which doesn't handle things like singleton objects or object construction. @@ -16684,7 +17109,7 @@ default interface vtable. and returns the default interface vtable for the type. If the type is not currently in use, then the default vtable -for the type will be created and initalized by calling +for the type will be created and initialized by calling the base interface init and default vtable init functions for the type (the @base_init and @class_init members of #GTypeInfo). Calling g_type_default_interface_ref() is useful when you @@ -17395,6 +17820,29 @@ that implements or has internal knowledge of the implementation of + + The prime purpose of a #GValueArray is for it to be used as an +object property that holds an array of values. A #GValueArray wraps +an array of #GValue elements in order for it to be used as a boxed +type through %G_TYPE_VALUE_ARRAY. + +#GValueArray is deprecated in favour of #GArray since GLib 2.32. It +is possible to create a #GArray that behaves like a #GValueArray by +using the size of #GValue as the element size, and by setting +g_value_unset() as the clear function using g_array_set_clear_func(), +for instance, the following code: + +|[<!-- language="C" --> + GValueArray *array = g_value_array_new (10); +]| + +can be replaced by: + +|[<!-- language="C" --> + GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); + g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); +]| + Registers a value transformation function for use in g_value_transform(). A previously registered transformation function for @src_type and @dest_type diff --git a/gir-files/Gio-2.0.gir b/gir-files/Gio-2.0.gir index 81002126f..f61925247 100644 --- a/gir-files/Gio-2.0.gir +++ b/gir-files/Gio-2.0.gir @@ -2448,7 +2448,7 @@ g_app_info_get_fallback_for_type(). Gets the default #GAppInfo for a given content type. - + #GAppInfo for given @content_type or %NULL on error. @@ -2471,8 +2471,9 @@ the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ':', e.g. "http", "ftp" or "sip". - - #GAppInfo for given @uri_scheme or %NULL on error. + + #GAppInfo for given @uri_scheme or + %NULL on error. @@ -4544,7 +4545,7 @@ desktop login. When your application is launched again, its arguments are passed through platform communication to the already running program. The already running instance of the program is called the "primary instance"; for non-unique applications this is -the always the current instance. On Linux, the D-Bus session bus +always the current instance. On Linux, the D-Bus session bus is used for communication. The use of #GApplication differs from some other commonly-used @@ -5298,7 +5299,7 @@ g_application_release() before the application stops running. g_application_mark_busy() or g_application_bind_busy_property(). - %TRUE if @application is currenty marked as busy + %TRUE if @application is currently marked as busy @@ -7145,6 +7146,7 @@ foo_init_async (GAsyncInitable *initable, GTask *task; task = g_task_new (initable, cancellable, callback, user_data); + g_task_set_name (task, G_STRFUNC); switch (self->priv->state) { @@ -10081,22 +10083,26 @@ credentials over a Unix Domain Socket, see #GUnixCredentialsMessage, g_unix_connection_send_credentials() and g_unix_connection_receive_credentials() for details. -On Linux, the native credential type is a struct ucred - see the +On Linux, the native credential type is a `struct ucred` - see the unix(7) man page for details. This corresponds to %G_CREDENTIALS_TYPE_LINUX_UCRED. +On Apple operating systems (including iOS, tvOS, and macOS), +the native credential type is a `struct xucred`. +This corresponds to %G_CREDENTIALS_TYPE_APPLE_XUCRED. + On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native -credential type is a struct cmsgcred. This corresponds +credential type is a `struct cmsgcred`. This corresponds to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. -On NetBSD, the native credential type is a struct unpcbid. +On NetBSD, the native credential type is a `struct unpcbid`. This corresponds to %G_CREDENTIALS_TYPE_NETBSD_UNPCBID. -On OpenBSD, the native credential type is a struct sockpeercred. +On OpenBSD, the native credential type is a `struct sockpeercred`. This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED. On Solaris (including OpenSolaris and its derivatives), the native -credential type is a ucred_t. This corresponds to +credential type is a `ucred_t`. This corresponds to %G_CREDENTIALS_TYPE_SOLARIS_UCRED. @@ -10140,7 +10146,8 @@ method is only available on UNIX platforms. 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 process ID. +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. @@ -10271,19 +10278,22 @@ returned string may change in future GLib release. Indicates an invalid native credential type. - The native credentials type is a struct ucred. + The native credentials type is a `struct ucred`. - The native credentials type is a struct cmsgcred. + The native credentials type is a `struct cmsgcred`. - The native credentials type is a struct sockpeercred. Added in 2.30. + The native credentials type is a `struct sockpeercred`. Added in 2.30. - The native credentials type is a ucred_t. Added in 2.40. + The native credentials type is a `ucred_t`. Added in 2.40. - The native credentials type is a struct unpcbid. + The native credentials type is a `struct unpcbid`. Added in 2.42. + + + The native credentials type is a `struct xucred`. Added in 2.66. @@ -19308,8 +19318,9 @@ authentication method. A #GDBusConnection. - - The unique bus name of the sender of the signal. + + The unique bus name of the sender of the signal, + or %NULL on a peer-to-peer D-Bus connection. @@ -21617,7 +21628,14 @@ applications that matched @search_string with an equal score. The outer list is sorted by score so that the first strv contains the best-matching applications, and so on. The algorithm for determining matches is undefined and may change at -any time. +any time. + +None of the search results are subjected to the normal validation +checks performed by g_desktop_app_info_new() (for example, checking that +the executable referenced by a result exists), and so it is possible for +g_desktop_app_info_new() to return %NULL when passed an app ID returned by +this function. It is expected that calling code will do this when +subsequently creating a #GDesktopAppInfo for each result. a @@ -22137,8 +22155,9 @@ directly. Applications should use g_app_info_get_default_for_uri_scheme(). The #GDesktopAppInfoLookup interface is deprecated and unused by GIO. - - #GAppInfo for given @uri_scheme or %NULL on error. + + #GAppInfo for given @uri_scheme or + %NULL on error. @@ -22164,8 +22183,9 @@ directly. Applications should use g_app_info_get_default_for_uri_scheme(). The #GDesktopAppInfoLookup interface is deprecated and unused by GIO. - - #GAppInfo for given @uri_scheme or %NULL on error. + + #GAppInfo for given @uri_scheme or + %NULL on error. @@ -22190,8 +22210,9 @@ handlers with URI schemes. - - #GAppInfo for given @uri_scheme or %NULL on error. + + #GAppInfo for given @uri_scheme or + %NULL on error. @@ -22243,7 +22264,7 @@ automatically detected and ejecting the media. If the #GDrive reports that media isn't automatically detected, one can poll for media; typically one should not do this periodically -as a poll for media operation is potententially expensive and may +as a poll for media operation is potentially expensive and may spin up the drive creating noise. #GDrive supports starting and stopping drives with authentication @@ -22636,10 +22657,10 @@ for more details. - Checks if @drive is capabable of automatically detecting media changes. + Checks if @drive is capable of automatically detecting media changes. - %TRUE if the @drive is capabable of automatically detecting + %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. @@ -23197,10 +23218,10 @@ for more details. - Checks if @drive is capabable of automatically detecting media changes. + Checks if @drive is capable of automatically detecting media changes. - %TRUE if the @drive is capabable of automatically detecting + %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. @@ -23576,7 +23597,7 @@ been pressed. - %TRUE if the @drive is capabable of automatically detecting + %TRUE if the @drive is capable of automatically detecting media changes, %FALSE otherwise. @@ -24223,7 +24244,7 @@ virtual hosts. What steps to perform when validating a certificate received from -a server. Server certificates that fail to validate in all of the +a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GDtlsConnection::accept-certificate. @@ -24276,6 +24297,25 @@ error on further I/O. + + + + + + + + + + + + + + + + + + + Gets the name of the application-layer protocol negotiated during the handshake. @@ -24631,7 +24671,7 @@ case @error will be set Gets @conn's certificate, as set by g_dtls_connection_set_certificate(). - + @conn's certificate, or %NULL @@ -24642,11 +24682,48 @@ g_dtls_connection_set_certificate(). + + Query the TLS backend for TLS channel binding data of @type for @conn. + +This call retrieves TLS channel binding data as specified in RFC +[5056](https://tools.ietf.org/html/rfc5056), RFC +[5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The +binding data is returned in @data. The @data is resized by the callee +using #GByteArray buffer management and will be freed when the @data +is destroyed by g_byte_array_unref(). If @data is %NULL, it will only +check whether TLS backend is able to fetch the data (e.g. whether @type +is supported by the TLS backend). It does not guarantee that the data +will be available though. That could happen if TLS connection does not +support @type or the binding data is not available yet due to additional +negotiation or input required. + + + %TRUE on success, %FALSE otherwise + + + + + a #GDtlsConnection + + + + #GTlsChannelBindingType type of data to fetch + + + + #GByteArray is + filled with the binding data, or %NULL + + + + + + Gets the certificate database that @conn uses to verify peer certificates. See g_dtls_connection_set_database(). - + the certificate database that @conn uses or %NULL @@ -24662,7 +24739,7 @@ peer certificates. See g_dtls_connection_set_database(). for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. - + The interaction object. @@ -24694,11 +24771,11 @@ g_dtls_connection_set_advertised_protocols(). - Gets @conn's peer's certificate after the handshake has completed. -(It is not set during the emission of + Gets @conn's peer's certificate after the handshake has completed +or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) - + @conn's peer's certificate, or %NULL @@ -24711,8 +24788,8 @@ g_dtls_connection_set_advertised_protocols(). Gets the errors associated with validating @conn's peer's -certificate, after the handshake has completed. (It is not set -during the emission of #GDtlsConnection::accept-certificate.) +certificate, after the handshake has completed or failed. (It is +not set during the emission of #GDtlsConnection::accept-certificate.) @conn's peer's certificate errors @@ -24933,7 +25010,7 @@ client-side connections, unless that bit is not set in a #GDtlsConnection - + a #GTlsDatabase @@ -25161,16 +25238,15 @@ handshake. See g_dtls_connection_get_negotiated_protocol(). The connection's peer's certificate, after the TLS handshake has -completed and the certificate has been accepted. Note in -particular that this is not yet set during the emission of -#GDtlsConnection::accept-certificate. +completed or failed. Note in particular that this is not yet set +during the emission of #GDtlsConnection::accept-certificate. (You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.) - The errors noticed-and-ignored while verifying + The errors noticed while verifying #GDtlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GDtlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -25458,6 +25534,27 @@ case @error will be set + + + + + + + + + + + + + + + + + + + + + #GDtlsServerConnection is the server-side subclass of #GDtlsConnection, @@ -26079,7 +26176,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the description of the file. The description is a utf8 string that describes the file, generally containing -the filename, but can also contain furter information. Example descriptions +the filename, but can also contain further information. Example descriptions could be "filename (on hostname)" for a remote file or "filename (in trash)" for a file in the trash. This is useful for instance as the window title when displaying a directory or for a bookmarks menu. @@ -26090,8 +26187,8 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the display name of the file. -A display name is guaranteed to be in UTF8 and can thus be displayed in -the UI. +A display name is guaranteed to be in UTF-8 and can thus be displayed in +the UI. It is guaranteed to be set on every file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. @@ -26163,7 +26260,8 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for getting the name of the file. The name is the on-disk filename which may not be in any known encoding, -and can thus not be generally displayed as is. +and can thus not be generally displayed as is. It is guaranteed to be set on +every file. Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user interface. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. @@ -26280,7 +26378,8 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was created, in seconds since the UNIX epoch. -This corresponds to the NTFS ctime. +This may correspond to Linux stx_btime, FreeBSD st_birthtim, NetBSD +st_birthtime or NTFS ctime. @@ -27334,6 +27433,21 @@ g_file_create_readwrite_async(). Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). +If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows +for deletion to be implemented avoiding +[time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): +|[ +g_autoptr(GError) local_error = NULL; +if (!g_file_delete (my_file, my_cancellable, &local_error) && + !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) + { + // deletion failed for some reason other than the file not existing: + // so report the error + g_warning ("Failed to delete %s: %s", + g_file_peek_path (my_file), local_error->message); + } +]| + If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. @@ -29754,7 +29868,9 @@ with g_file_stop_mountable(). Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Not all file systems support trashing, so this call can return the -%G_IO_ERROR_NOT_SUPPORTED error. +%G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix +mount option can be used to disable g_file_trash() support for certain +mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -30464,6 +30580,21 @@ g_file_create_readwrite_async(). Deletes a file. If the @file is a directory, it will only be deleted if it is empty. This has the same semantics as g_unlink(). +If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows +for deletion to be implemented avoiding +[time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use): +|[ +g_autoptr(GError) local_error = NULL; +if (!g_file_delete (my_file, my_cancellable, &local_error) && + !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND)) + { + // deletion failed for some reason other than the file not existing: + // so report the error + g_warning ("Failed to delete %s: %s", + g_file_peek_path (my_file), local_error->message); + } +]| + If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. @@ -33930,7 +34061,9 @@ If this returns %FALSE, you cannot perform asynchronous operations on Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. Not all file systems support trashing, so this call can return the -%G_IO_ERROR_NOT_SUPPORTED error. +%G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix +mount option can be used to disable g_file_trash() support for certain +mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -34332,8 +34465,8 @@ in the given @ns, %FALSE otherwise. Gets the next matched attribute from a #GFileAttributeMatcher. - - a string containing the next attribute or %NULL if + + a string containing the next attribute or, %NULL if no more attribute exist. @@ -34471,7 +34604,7 @@ the @matcher is automatically freed. The data types for file attributes. - indicates an invalid or uninitalized type. + indicates an invalid or uninitialized type. a null terminated UTF8 string. @@ -34542,7 +34675,9 @@ the @matcher is automatically freed. rather than a "save new version of" replace operation. You can think of it as "unlink destination" before writing to it, although the implementation may not - be exactly like that. Since 2.20 + be exactly like that. This flag can only be used with + g_file_replace() and its variants, including g_file_replace_contents(). + Since 2.20 @@ -38585,7 +38720,7 @@ and then copies all of the file attributes from @src_info to @dest_info. - Gets the value of a attribute, formated as a string. + Gets the value of a attribute, formatted as a string. This escapes things as needed to make the string valid UTF-8. @@ -38629,7 +38764,7 @@ contain a boolean value, %FALSE will be returned. Gets the value of a byte string attribute. If the attribute does not contain a byte string, %NULL will be returned. - + the contents of the @attribute value as a byte string, or %NULL otherwise. @@ -38721,9 +38856,9 @@ attribute does not contain a signed 64-bit integer, or is invalid, Gets the value of a #GObject attribute. If the attribute does not contain a #GObject, %NULL will be returned. - - a #GObject associated with the given @attribute, or -%NULL otherwise. + + a #GObject associated with the given @attribute, +or %NULL otherwise. @@ -38760,9 +38895,9 @@ not contain a #GObject, %NULL will be returned. Gets the value of a string attribute. If the attribute does not contain a string, %NULL will be returned. - - the contents of the @attribute value as a UTF-8 string, or -%NULL otherwise. + + the contents of the @attribute value as a UTF-8 string, +or %NULL otherwise. @@ -38780,9 +38915,9 @@ not contain a string, %NULL will be returned. Gets the value of a stringv attribute. If the attribute does not contain a stringv, %NULL will be returned. - - the contents of the @attribute value as a stringv, or -%NULL otherwise. Do not free. These returned strings are UTF-8. + + the contents of the @attribute value as a stringv, +or %NULL otherwise. Do not free. These returned strings are UTF-8. @@ -38860,8 +38995,9 @@ attribute does not contain an unsigned 64-bit integer, or is invalid, Gets the file's content type. - - a string containing the file's content type. + + a string containing the file's content type, +or %NULL if unknown. @@ -38876,7 +39012,7 @@ attribute does not contain an unsigned 64-bit integer, or is invalid, available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. - + a #GDateTime, or %NULL. @@ -38888,7 +39024,7 @@ G_FILE_ATTRIBUTE_TRASH_DELETION_DATE attribute is unset, %NULL is returned. - Gets a display name for a file. + Gets a display name for a file. This is guaranteed to always be set. a string containing the display name. @@ -39041,7 +39177,7 @@ in @result. - Gets the name for a file. + Gets the name for a file. This is guaranteed to always be set. a string containing the file name. @@ -42660,7 +42796,7 @@ already set or @stream is closed, it will return %FALSE and set - Asyncronously splice the output stream of @stream1 to the input stream of + Asynchronously splice the output stream of @stream1 to the input stream of @stream2, and splice the output stream of @stream2 to the input stream of @stream1. @@ -44697,7 +44833,7 @@ 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. + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. @@ -44771,7 +44907,7 @@ 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. + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. @@ -44903,7 +45039,7 @@ use in a #GHashTable or similar data structure. - a #GVariant, or %NULL when serialization fails. + a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating. @@ -44970,9 +45106,9 @@ for @family. Parses @string as an IP address and creates a new #GInetAddress. - - a new #GInetAddress corresponding to @string, or %NULL if -@string could not be parsed. + + a new #GInetAddress corresponding +to @string, or %NULL if @string could not be parsed. Free the returned object with g_object_unref(). @@ -45549,9 +45685,9 @@ on error. If @address is an IPv6 address, it can also contain a scope ID (separated from the address by a `%`). - - a new #GInetSocketAddress, or %NULL if @address cannot be -parsed. + + a new #GInetSocketAddress, +or %NULL if @address cannot be parsed. @@ -45675,7 +45811,7 @@ setting a #GError on failure (at which point the instance is unreferenced). For bindings in languages where the native constructor supports -exceptions the binding could check for objects implemention %GInitable +exceptions the binding could check for objects implementing %GInitable during normal construction and automatically initialize them, throwing an exception on failure. @@ -47256,7 +47392,7 @@ return the same object for a given position until all references to it are gone. On the other side, a consumer is expected only to hold references on -objects that are currently "user visible", in order to faciliate the +objects that are currently "user visible", in order to facilitate the maximum level of laziness in the implementation of the list and to reduce the required number of signal connections at a given time. @@ -48472,6 +48608,13 @@ Possible actions to take when the signal is received are: - Run a garbage collection cycle - Try and compress fragmented allocations - Exit on idle if the process has no reason to stay around +- Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + the kernel (if supported by your libc) + +Note that some actions may not always improve system performance, and so +should be profiled for your application. `malloc_trim()`, for example, may +make future heap allocations slower (due to releasing cached heap pages back +to the kernel). See #GMemoryMonitorWarningLevel for details on the various warning levels. @@ -50642,7 +50785,7 @@ You must free the iterator with g_object_unref() when you are done. - Emitted when a change has occured to the menu. + Emitted when a change has occurred to the menu. The only changes that can occur to a menu is that items are removed or added. Items may not change (except by being removed and added @@ -53334,7 +53477,7 @@ primary text in a #GtkMessageDialog. - string containing a mesage to display to the user + string containing a message to display to the user @@ -54489,7 +54632,7 @@ ASCII-encoded, depending on what @srv was created with. - Get's the URI scheme used to resolve proxies. By default, the service name + Gets the URI scheme used to resolve proxies. By default, the service name is used as scheme. @@ -61640,6 +61783,13 @@ program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable mu set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will abort. +`json-stripblanks` which will use the `json-glib-format` command to strip +ignorable whitespace from the JSON file. For this to work, the +`JSON_GLIB_FORMAT` environment variable must be set to the full path to the +`json-glib-format` executable, or it must be in the `PATH`; +otherwise the preprocessing step is skipped. In addition, at least version +1.6 of `json-glib-format` is required. + Resource files will be exported in the GResource namespace using the combination of the given `prefix` and the filename from the `file` element. The `alias` attribute can be used to alter the filename to expose them at a @@ -62444,7 +62594,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Sets the length of the stream to @offset. If the stream was previously larger than @offset, the extra data is discarded. If the stream was -previouly shorter than @offset, it is extended with NUL ('\0') bytes. +previously shorter than @offset, it is extended with NUL ('\0') bytes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -62560,7 +62710,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Sets the length of the stream to @offset. If the stream was previously larger than @offset, the extra data is discarded. If the stream was -previouly shorter than @offset, it is extended with NUL ('\0') bytes. +previously shorter than @offset, it is extended with NUL ('\0') bytes. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -62990,6 +63140,12 @@ rules. It should not be committed to version control or included in Creates a new #GSettings object with the schema specified by @schema_id. +It is an error for the schema to not exist: schemas are an +essential part of a program, as they provide type information. +If schemas need to be dynamically loaded (for example, from an +optional runtime dependency), g_settings_schema_source_lookup() +can be used to test for their existence before loading them. + Signals on the newly created #GSettings object will be dispatched via the thread-default #GMainContext in effect at the time of the call to g_settings_new(). The new #GSettings will hold a reference @@ -67880,6 +68036,7 @@ This method can be expected to be available on the following platforms: - OpenBSD since GLib 2.30 - Solaris, Illumos and OpenSolaris since GLib 2.40 - NetBSD since GLib 2.42 +- macOS, tvOS, iOS since GLib 2.66 Other ways to obtain credentials from a foreign peer includes the #GUnixCredentialsMessage type and @@ -68359,14 +68516,14 @@ the peer, or -1 on error a #GSocket - - a buffer to - read data into (which should be at least @size bytes long). + + + a buffer to read data into (which should be at least @size bytes long). - + the number of bytes you want to read from the socket @@ -68400,14 +68557,14 @@ the peer, or -1 on error pointer, or %NULL - - a buffer to - read data into (which should be at least @size bytes long). + + + a buffer to read data into (which should be at least @size bytes long). - + the number of bytes you want to read from the socket @@ -68627,14 +68784,14 @@ the peer, or -1 on error a #GSocket - - a buffer to - read data into (which should be at least @size bytes long). + + + a buffer to read data into (which should be at least @size bytes long). - + the number of bytes you want to read from the socket @@ -69548,7 +69705,7 @@ g_socket_address_enumerator_next_async() and g_socket_address_enumerator_next_finish() should be used where possible. Each #GSocketAddressEnumerator can only be enumerated once. Once -g_socket_address_enumerator_next() has returned %NULL (and no error), further +g_socket_address_enumerator_next() has returned %NULL, further enumeration with that #GSocketAddressEnumerator is not possible, and it can be unreffed. @@ -75671,7 +75828,7 @@ task's #GTaskThreadFunc had called g_task_return_error_if_cancelled() and then returned. This allows you to create a cancellable wrapper around an -uninterruptable function. The #GTaskThreadFunc just needs to be +uninterruptible function. The #GTaskThreadFunc just needs to be careful that it does not modify any externally-visible state after it has been cancelled. To do that, the thread should call g_task_set_return_on_cancel() again to (atomically) set @@ -75895,7 +76052,7 @@ actually created is not directly a #GSocketConnection. - Get's @conn's base #GIOStream + Gets @conn's base #GIOStream @conn's base #GIOStream @@ -76374,7 +76531,7 @@ not return until the connection is closed. a new #GSocketConnection object. - + the source_object passed to g_socket_listener_add_address(). @@ -77153,6 +77310,57 @@ g_tls_interaction_invoke_request_certificate(). No flags + + An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to +indicate a TLS channel binding retrieval error. + + Either entire binding + retrieval facility or specific binding type is not implemented in the + TLS backend. + + + The handshake is not yet + complete on the connection which is a strong requirement for any existing + binding type. + + + Handshake is complete but + binding data is not available. That normally indicates the TLS + implementation failed to provide the binding data. For example, some + implementations do not provide a peer certificate for resumed connections. + + + Binding type is not supported + on the current connection. This error could be triggered when requesting + `tls-server-end-point` binding data for a certificate which has no hash + function or uses multiple hash functions. + + + Any other backend error + preventing binding data retrieval. + + + Gets the TLS channel binding error quark. + + a #GQuark. + + + + + + The type of TLS channel binding data to retrieve from #GTlsConnection +or #GDtlsConnection, as documented by RFC 5929. The +[`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5) +binding type is not currently implemented. + + [`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding + type + + + [`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) + binding type + + #GTlsClientConnection is the client-side subclass of #GTlsConnection, representing a client-side TLS connection. @@ -77446,7 +77654,7 @@ g_tls_client_connection_set_use_ssl3() for details. What steps to perform when validating a certificate received from -a server. Server certificates that fail to validate in all of the +a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application overrides the default via #GTlsConnection::accept-certificate. @@ -77503,6 +77711,25 @@ For DTLS (Datagram TLS) support, see #GDtlsConnection. + + + + + + + + + + + + + + + + + + + Attempts a TLS handshake on @conn. @@ -77629,7 +77856,7 @@ case @error will be set. Gets @conn's certificate, as set by g_tls_connection_set_certificate(). - + @conn's certificate, or %NULL @@ -77640,11 +77867,48 @@ g_tls_connection_set_certificate(). + + Query the TLS backend for TLS channel binding data of @type for @conn. + +This call retrieves TLS channel binding data as specified in RFC +[5056](https://tools.ietf.org/html/rfc5056), RFC +[5929](https://tools.ietf.org/html/rfc5929), and related RFCs. The +binding data is returned in @data. The @data is resized by the callee +using #GByteArray buffer management and will be freed when the @data +is destroyed by g_byte_array_unref(). If @data is %NULL, it will only +check whether TLS backend is able to fetch the data (e.g. whether @type +is supported by the TLS backend). It does not guarantee that the data +will be available though. That could happen if TLS connection does not +support @type or the binding data is not available yet due to additional +negotiation or input required. + + + %TRUE on success, %FALSE otherwise + + + + + a #GTlsConnection + + + + #GTlsChannelBindingType type of data to fetch + + + + #GByteArray is + filled with the binding data, or %NULL + + + + + + Gets the certificate database that @conn uses to verify peer certificates. See g_tls_connection_set_database(). - + the certificate database that @conn uses or %NULL @@ -77660,7 +77924,7 @@ peer certificates. See g_tls_connection_set_database(). for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. - + The interaction object. @@ -77692,11 +77956,11 @@ g_tls_connection_set_advertised_protocols(). - Gets @conn's peer's certificate after the handshake has completed. -(It is not set during the emission of + Gets @conn's peer's certificate after the handshake has completed +or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) - + @conn's peer's certificate, or %NULL @@ -77709,8 +77973,8 @@ g_tls_connection_set_advertised_protocols(). Gets the errors associated with validating @conn's peer's -certificate, after the handshake has completed. (It is not set -during the emission of #GTlsConnection::accept-certificate.) +certificate, after the handshake has completed or failed. (It is +not set during the emission of #GTlsConnection::accept-certificate.) @conn's peer's certificate errors @@ -77953,7 +78217,7 @@ client-side connections, unless that bit is not set in a #GTlsConnection - + a #GTlsDatabase @@ -78111,16 +78375,15 @@ handshake. See g_tls_connection_get_negotiated_protocol(). The connection's peer's certificate, after the TLS handshake has -completed and the certificate has been accepted. Note in -particular that this is not yet set during the emission of -#GTlsConnection::accept-certificate. +completed or failed. Note in particular that this is not yet set +during the emission of #GTlsConnection::accept-certificate. (You can watch for a #GObject::notify signal on this property to detect when a handshake has occurred.) - The errors noticed-and-ignored while verifying + The errors noticed while verifying #GTlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GTlsClientConnection:validation-flags is not %G_TLS_CERTIFICATE_VALIDATE_ALL, or if @@ -78298,8 +78561,29 @@ case @error will be set. + + + + + + + + + + + + + + + + + + + + + - + @@ -78663,9 +78947,13 @@ is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENT which means that the certificate is being used to authenticate a server (and we are acting as the client). -The @identity is used to check for pinned certificates (trust exceptions) -in the database. These will override the normal verification process on a -host by host basis. +The @identity is used to ensure the server certificate is valid for +the expected peer identity. If the identity does not match the +certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the +return value. If @identity is %NULL, that bit will never be set in +the return value. The peer identity may also be used to check for +pinned certificates (trust exceptions) in the database. These may +override the normal verification process on a host-by-host basis. Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be used. @@ -79139,9 +79427,13 @@ is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENT which means that the certificate is being used to authenticate a server (and we are acting as the client). -The @identity is used to check for pinned certificates (trust exceptions) -in the database. These will override the normal verification process on a -host by host basis. +The @identity is used to ensure the server certificate is valid for +the expected peer identity. If the identity does not match the +certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the +return value. If @identity is %NULL, that bit will never be set in +the return value. The peer identity may also be used to check for +pinned certificates (trust exceptions) in the database. These may +override the normal verification process on a host-by-host basis. Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be used. @@ -82314,6 +82606,30 @@ The result is a translated string. + + Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it +will be filled with a unix timestamp for checking if the mount points have +changed since with g_unix_mount_points_changed_since(). + +If more mount points have the same mount path, the last matching mount point +is returned. + + + a #GUnixMountPoint, or %NULL if no match +is found. + + + + + path for a possible unix mount point. + + + + guint64 to contain a timestamp. + + + + #GUnixOutputStream implements #GOutputStream for writing to a UNIX @@ -86111,7 +86427,7 @@ g_app_info_get_fallback_for_type(). Gets the default #GAppInfo for a given content type. - + #GAppInfo for given @content_type or %NULL on error. @@ -86134,8 +86450,9 @@ the given URI scheme. A URI scheme is the initial part of the URI, up to but not including the ':', e.g. "http", "ftp" or "sip". - - #GAppInfo for given @uri_scheme or %NULL on error. + + #GAppInfo for given @uri_scheme or + %NULL on error. @@ -87732,6 +88049,59 @@ assumed to communicate with the server identified by @server_identity. + + #GIOExtensionPoint provides a mechanism for modules to extend the +functionality of the library or application that loaded it in an +organized fashion. + +An extension point is identified by a name, and it may optionally +require that any implementation must be of a certain type (or derived +thereof). Use g_io_extension_point_register() to register an +extension point, and g_io_extension_point_set_required_type() to +set a required type. + +A module can implement an extension point by specifying the #GType +that implements the functionality. Additionally, each implementation +of an extension point has a name, and a priority. Use +g_io_extension_point_implement() to implement an extension point. + + |[<!-- language="C" --> + GIOExtensionPoint *ep; + + // Register an extension point + ep = g_io_extension_point_register ("my-extension-point"); + g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); + ]| + + |[<!-- language="C" --> + // Implement an extension point + G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE) + g_io_extension_point_implement ("my-extension-point", + my_example_impl_get_type (), + "my-example", + 10); + ]| + + It is up to the code that registered the extension point how + it uses the implementations that have been associated with it. + Depending on the use case, it may use all implementations, or + only the one with the highest priority, or pick a specific + one by name. + + To avoid opening all modules just to find out what extension + points they implement, GIO makes use of a caching mechanism, + see [gio-querymodules][gio-querymodules]. + You are expected to run this command after installing a + GIO module. + + The `GIO_EXTRA_MODULES` environment variable can be used to + specify additional directories to automatically load modules + from. This environment variable has the same syntax as the + `PATH`. If two modules have the same base name in different + directories, then the latter one will be ignored. If additional + directories are specified GIO will load modules from the built-in + directory last. + Creates a #GFile with the given argument from the command line. The value of @arg can be either a URI, an absolute path or a @@ -87870,6 +88240,364 @@ the @parse_name cannot be parsed. + + These functions support exporting a #GActionGroup on D-Bus. +The D-Bus interface that is used is a private implementation +detail. + +To access an exported #GActionGroup remotely, use +g_dbus_action_group_get() to obtain a #GDBusActionGroup. + + + A content type is a platform specific string that defines the type +of a file. On UNIX it is a +[MIME type](http://www.wikipedia.org/wiki/Internet_media_type) +like `text/plain` or `image/png`. +On Win32 it is an extension string like `.doc`, `.txt` or a perceived +string like `audio`. Such strings can be looked up in the registry at +`HKEY_CLASSES_ROOT`. +On macOS it is a [Uniform Type Identifier](https://en.wikipedia.org/wiki/Uniform_Type_Identifier) +such as `com.apple.application`. + + + Routines for working with D-Bus addresses. A D-Bus address is a string +like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses +is explained in detail in the +[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses). + +TCP D-Bus connections are supported, but accessing them via a proxy is +currently not supported. + + + All facilities that return errors from remote methods (such as +g_dbus_connection_call_sync()) use #GError to represent both D-Bus +errors (e.g. errors returned from the other peer) and locally +in-process generated errors. + +To check if a returned #GError is an error from a remote peer, use +g_dbus_error_is_remote_error(). To get the actual D-Bus error name, +use g_dbus_error_get_remote_error(). Before presenting an error, +always use g_dbus_error_strip_remote_error(). + +In addition, facilities used to return errors to a remote peer also +use #GError. See g_dbus_method_invocation_return_error() for +discussion about how the D-Bus error name is set. + +Applications can associate a #GError error domain with a set of D-Bus errors in order to +automatically map from D-Bus errors to #GError and back. This +is typically done in the function returning the #GQuark for the +error domain: +|[<!-- language="C" --> +// foo-bar-error.h: + +#define FOO_BAR_ERROR (foo_bar_error_quark ()) +GQuark foo_bar_error_quark (void); + +typedef enum +{ + FOO_BAR_ERROR_FAILED, + FOO_BAR_ERROR_ANOTHER_ERROR, + FOO_BAR_ERROR_SOME_THIRD_ERROR, + FOO_BAR_N_ERRORS / *< skip >* / +} FooBarError; + +// foo-bar-error.c: + +static const GDBusErrorEntry foo_bar_error_entries[] = +{ + {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"}, + {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"}, + {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"}, +}; + +// Ensure that every error code has an associated D-Bus error name +G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS); + +GQuark +foo_bar_error_quark (void) +{ + static volatile gsize quark_volatile = 0; + g_dbus_error_register_error_domain ("foo-bar-error-quark", + &quark_volatile, + foo_bar_error_entries, + G_N_ELEMENTS (foo_bar_error_entries)); + return (GQuark) quark_volatile; +} +]| +With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and +other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError. + +If the other peer is using GDBus, and has registered the association with +g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark +generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead +of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover +org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error(). + +Note that the %G_DBUS_ERROR error domain is intended only +for returning errors from a remote message bus process. Errors +generated locally in-process by e.g. #GDBusConnection should use the +%G_IO_ERROR domain. + + + Various data structures and convenience routines to parse and +generate D-Bus introspection XML. Introspection information is +used when registering objects with g_dbus_connection_register_object(). + +The format of D-Bus introspection XML is specified in the +[D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format) + + + Convenience API for owning bus names. + +A simple example for owning a name can be found in +[gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c) + + + Convenience API for watching bus names. + +A simple example for watching a name can be found in +[gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c) + + + Various utility routines related to D-Bus. + + + File attributes in GIO consist of a list of key-value pairs. + +Keys are strings that contain a key namespace and a key name, separated +by a colon, e.g. "namespace::keyname". Namespaces are included to sort +key-value pairs by namespaces for relevance. Keys can be retrieved +using wildcards, e.g. "standard::*" will return all of the keys in the +"standard" namespace. + +The list of possible attributes for a filesystem (pointed to by a #GFile) is +available as a #GFileAttributeInfoList. This list is queryable by key names +as indicated earlier. + +Information is stored within the list in #GFileAttributeInfo structures. +The info structure can store different types, listed in the enum +#GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will +be set to %G_FILE_ATTRIBUTE_TYPE_INVALID. + +Classes that implement #GFileIface will create a #GFileAttributeInfoList and +install default keys and values for their given file system, architecture, +and other possible implementation details (e.g., on a UNIX system, a file +attribute key will be registered for the user id for a given file). + +## Default Namespaces + +- `"standard"`: The "Standard" namespace. General file information that + any application may need should be put in this namespace. Examples + include the file's name, type, and size. +- `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key + in this namespace is "value", which contains the value of the current + entity tag. +- `"id"`: The "Identification" namespace. This namespace is used by file + managers and applications that list directories to check for loops and + to uniquely identify files. +- `"access"`: The "Access" namespace. Used to check if a user has the + proper privileges to access files and perform file operations. Keys in + this namespace are made to be generic and easily understood, e.g. the + "can_read" key is %TRUE if the current user has permission to read the + file. UNIX permissions and NTFS ACLs in Windows should be mapped to + these values. +- `"mountable"`: The "Mountable" namespace. Includes simple boolean keys + for checking if a file or path supports mount operations, e.g. mount, + unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. +- `"time"`: The "Time" namespace. Includes file access, changed, created + times. +- `"unix"`: The "Unix" namespace. Includes UNIX-specific information and + may not be available for all files. Examples include the UNIX "UID", + "GID", etc. +- `"dos"`: The "DOS" namespace. Includes DOS-specific information and may + not be available for all files. Examples include "is_system" for checking + if a file is marked as a system file, and "is_archive" for checking if a + file is marked as an archive file. +- `"owner"`: The "Owner" namespace. Includes information about who owns a + file. May not be available for all file systems. Examples include "user" + for getting the user name of the file owner. This information is often + mapped from some backend specific data such as a UNIX UID. +- `"thumbnail"`: The "Thumbnail" namespace. Includes information about file + thumbnails and their location within the file system. Examples of keys in + this namespace include "path" to get the location of a thumbnail, "failed" + to check if thumbnailing of the file failed, and "is-valid" to check if + the thumbnail is outdated. +- `"filesystem"`: The "Filesystem" namespace. Gets information about the + file system where a file is located, such as its type, how much space is + left available, and the overall size of the file system. +- `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information + about the current GVFS backend in use. +- `"xattr"`: The "xattr" namespace. Gets information about extended + user attributes. See attr(5). The "user." prefix of the extended user + attribute name is stripped away when constructing keys in this namespace, + e.g. "xattr::mime_type" for the extended attribute with the name + "user.mime_type". Note that this information is only available if + GLib has been built with extended attribute support. +- `"xattr-sys"`: The "xattr-sys" namespace. Gets information about + extended attributes which are not user-specific. See attr(5). Note + that this information is only available if GLib has been built with + extended attribute support. +- `"selinux"`: The "SELinux" namespace. Includes information about the + SELinux context of files. Note that this information is only available + if GLib has been built with SELinux support. + +Please note that these are not all of the possible namespaces. +More namespaces can be added from GIO modules or by individual applications. +For more information about writing GIO modules, see #GIOModule. + +<!-- TODO: Implementation note about using extended attributes on supported +file systems --> + +## Default Keys + +For a list of the built-in keys and their types, see the +[GFileInfo][GFileInfo] documentation. + +Note that there are no predefined keys in the "xattr" and "xattr-sys" +namespaces. Keys for the "xattr" namespace are constructed by stripping +away the "user." prefix from the extended user attribute, and prepending +"xattr::". Keys for the "xattr-sys" namespace are constructed by +concatenating "xattr-sys::" with the extended attribute name. All extended +attribute values are returned as hex-encoded strings in which bytes outside +the ASCII range are encoded as escape sequences of the form \x`nn` +where `nn` is a 2-digit hexadecimal number. + + + Contains helper functions for reporting errors to the user. + + + As of GLib 2.36, #GIOScheduler is deprecated in favor of +#GThreadPool and #GTask. + +Schedules asynchronous I/O operations. #GIOScheduler integrates +into the main event loop (#GMainLoop) and uses threads. + + + These functions support exporting a #GMenuModel on D-Bus. +The D-Bus interface that is used is a private implementation +detail. + +To access an exported #GMenuModel remotely, use +g_dbus_menu_model_get() to obtain a #GDBusMenuModel. + + + The `<gio/gnetworking.h>` header can be included to get +various low-level networking-related system headers, automatically +taking care of certain portability issues for you. + +This can be used, for example, if you want to call setsockopt() +on a #GSocket. + +Note that while WinSock has many of the same APIs as the +traditional UNIX socket API, most of them behave at least slightly +differently (particularly with respect to error handling). If you +want your code to work under both UNIX and Windows, you will need +to take these differences into account. + +Also, under GNU libc, certain non-portable functions are only visible +in the headers if you define %_GNU_SOURCE before including them. Note +that this symbol must be defined before including any headers, or it +may not take effect. + + + Utility functions for #GPollableInputStream and +#GPollableOutputStream implementations. + + + #GTlsConnection and related classes provide TLS (Transport Layer +Security, previously known as SSL, Secure Sockets Layer) support for +gio-based network streams. + +#GDtlsConnection and related classes provide DTLS (Datagram TLS) support for +GIO-based network sockets, using the #GDatagramBased interface. The TLS and +DTLS APIs are almost identical, except TLS is stream-based and DTLS is +datagram-based. They share certificate and backend infrastructure. + +In the simplest case, for a client TLS connection, you can just set the +#GSocketClient:tls flag on a #GSocketClient, and then any +connections created by that client will have TLS negotiated +automatically, using appropriate default settings, and rejecting +any invalid or self-signed certificates (unless you change that +default by setting the #GSocketClient:tls-validation-flags +property). The returned object will be a #GTcpWrapperConnection, +which wraps the underlying #GTlsClientConnection. + +For greater control, you can create your own #GTlsClientConnection, +wrapping a #GSocketConnection (or an arbitrary #GIOStream with +pollable input and output streams) and then connect to its signals, +such as #GTlsConnection::accept-certificate, before starting the +handshake. + +Server-side TLS is similar, using #GTlsServerConnection. At the +moment, there is no support for automatically wrapping server-side +connections in the way #GSocketClient does for client-side +connections. + + + Routines for managing mounted UNIX mount points and paths. + +Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO +interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config +file when using it. + + + #GWin32InputStream implements #GInputStream for reading from a +Windows file handle. + +Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO +interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file +when using it. + + + #GWin32OutputStream implements #GOutputStream for writing to a +Windows file handle. + +Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO +interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file +when using it. + + + #GWin32RegistryKey represents a single Windows Registry key. + +#GWin32RegistryKey is used by a number of helper functions that read +Windows Registry. All keys are opened with read-only access, and at +the moment there is no API for writing into registry keys or creating +new ones. + +#GWin32RegistryKey implements the #GInitable interface, so if it is manually +constructed by e.g. g_object_new() you must call g_initable_init() and check +the results before using the object. This is done automatically +in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these +functions can return %NULL. + +To increase efficiency, a UTF-16 variant is available for all functions +that deal with key or value names in the registry. Use these to perform +deep registry queries or other operations that require querying a name +of a key or a value and then opening it (or querying its data). The use +of UTF-16 functions avoids the overhead of converting names to UTF-8 and +back. + +All functions operate in current user's context (it is not possible to +access registry tree of a different user). + +Key paths must use '\\' as a separator, '/' is not supported. Key names +must not include '\\', because it's used as a separator. Value names +can include '\\'. + +Key and value names are not case sensitive. + +Full key name (excluding the pre-defined ancestor's name) can't exceed +255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 +characters. Tree depth is limited to 512 levels. + + + #GZlibCompressor is an implementation of #GConverter that +compresses data using zlib. + + + #GZlibDecompressor is an implementation of #GConverter that +decompresses data compressed with zlib. + Deserializes a #GIcon previously serialized using g_icon_serialize(). @@ -88101,7 +88829,7 @@ any extension point implemented by a module is registered. This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when -an extension point it implementes is used with e.g. +an extension point it implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name(). @@ -88125,7 +88853,7 @@ any extension point implemented by a module is registered. This may not actually load and initialize all the types in each module, some modules may be lazily loaded and initialized when -an extension point it implementes is used with e.g. +an extension point it implements is used with e.g. g_io_extension_point_get_extensions() or g_io_extension_point_get_extension_by_name(). @@ -88842,6 +89570,13 @@ ownership of @error, so the caller does not have to free it any more. + + Gets the TLS channel binding error quark. + + a #GQuark. + + + Creates a new #GTlsClientConnection wrapping @base_io_stream (which must have pollable input and output streams) which is assumed to @@ -89252,6 +89987,30 @@ file system types and device paths are ignored. + + Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it +will be filled with a unix timestamp for checking if the mount points have +changed since with g_unix_mount_points_changed_since(). + +If more mount points have the same mount path, the last matching mount point +is returned. + + + a #GUnixMountPoint, or %NULL if no match +is found. + + + + + path for a possible unix mount point. + + + + guint64 to contain a timestamp. + + + + Checks if the unix mount points have changed since a given unix time.