[glibmm] Glib, Gio: Regenerate docs.xml and .defs files

From: Kjell Ahlstedt <kjellahl src gnome org>
To: commits-list gnome org
Cc:
Subject: [glibmm] Glib, Gio: Regenerate docs.xml and .defs files
Date: Mon, 26 Mar 2018 09:12:14 +0000 (UTC)
commit ed8ae73179bca4dd13991cf2e0db34238013321d
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Mon Mar 26 11:10:29 2018 +0200

    Glib, Gio: Regenerate docs.xml and .defs files

 gio/src/gio_docs.xml            |  321 ++++++++++++++++++++----
 gio/src/gio_methods.defs        |   53 ++++
 gio/src/gio_signals.defs        |    1 +
 glib/src/glib_docs.xml          |  533 ++++++++++++++++++++++++++++++++-------
 glib/src/glib_enums.defs        |    4 +-
 glib/src/glib_functions.defs    |   34 +++
 glib/src/gobject_functions.defs |    4 +-
 7 files changed, 803 insertions(+), 147 deletions(-)
---
diff --git a/gio/src/gio_docs.xml b/gio/src/gio_docs.xml
index 38ba91c..b55b91b 100644
--- a/gio/src/gio_docs.xml
+++ b/gio/src/gio_docs.xml
@@ -4101,11 +4101,7 @@ appears to be able to reach the full Internet.
 
 <signal name="GNetworkMonitor::network-changed">
 <description>
-Emitted when the network configuration changes. If @available is
-%TRUE, then some hosts may be reachable that were not reachable
-before, while others that were reachable before may no longer be
-reachable. If @available is %FALSE, then no remote hosts are
-reachable.
+Emitted when the network configuration changes.
 
 Since: 2.32
 
@@ -4115,7 +4111,7 @@ Since: 2.32
 <parameter_description> a #GNetworkMonitor
 </parameter_description>
 </parameter>
-<parameter name="available">
+<parameter name="network_available">
 <parameter_description> the current value of #GNetworkMonitor:network-available
 </parameter_description>
 </parameter>
@@ -5423,7 +5419,7 @@ of fixed maximum length (e.g. SCTP).
 <description>
 Flags to define the behaviour of a #GSubprocess.
 
-Note that the default for stdin is to redirect from /dev/null.  For
+Note that the default for stdin is to redirect from `/dev/null`.  For
 stdout and stderr the default are for them to inherit the
 corresponding descriptor from the calling process.
 
@@ -5458,7 +5454,7 @@ g_subprocess_get_stdout_pipe().
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDOUT_SILENCE">
 <parameter_description> silence the stdout of the spawned
-process (ie: redirect to /dev/null).
+process (ie: redirect to `/dev/null`).
 </parameter_description>
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDERR_PIPE">
@@ -5469,7 +5465,7 @@ g_subprocess_get_stderr_pipe().
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDERR_SILENCE">
 <parameter_description> silence the stderr of the spawned
-process (ie: redirect to /dev/null).
+process (ie: redirect to `/dev/null`).
 </parameter_description>
 </parameter>
 <parameter name="G_SUBPROCESS_FLAGS_STDERR_MERGE">
@@ -5793,19 +5789,22 @@ Since: 2.28
 
 <property name="GTlsClientConnection:use-ssl3">
 <description>
-If %TRUE, tells the connection to use a fallback version of TLS
+If %TRUE, forces the connection to use a fallback version of TLS
 or SSL, rather than trying to negotiate the best version of TLS
 to use. This can be used when talking to servers that don't
 implement version negotiation correctly and therefore refuse to
-handshake at all with a &quot;modern&quot; TLS handshake.
+handshake at all with a modern TLS handshake.
 
-Despite the property name, the fallback version is not
-necessarily SSL 3.0; if SSL 3.0 has been disabled, the
-#GTlsClientConnection will use the next highest available version
-(normally TLS 1.0) as the fallback version.
+Despite the property name, the fallback version is usually not
+SSL 3.0, because SSL 3.0 is generally disabled by the #GTlsBackend.
+#GTlsClientConnection will use the next-highest available version
+as the fallback version.
 
 Since: 2.28
 
+Deprecated: 2.56: SSL 3.0 is insecure, and this property does not
+generally enable or disable it, despite its name.
+
 </description>
 </property>
 
@@ -9872,23 +9871,47 @@ Checks if @application_id is a valid application identifier.
 A valid ID is required for calls to g_application_new() and
 g_application_set_application_id().
 
+Application identifiers follow the same format as
+[D-Bus well-known bus 
names](https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-bus).
 For convenience, the restrictions on application identifiers are
 reproduced here:
 
-- Application identifiers must contain only the ASCII characters
-&quot;[A-Z][a-z][0-9]_-.&quot; and must not begin with a digit.
+- Application identifiers are composed of 1 or more elements separated by a
+period (`.`) character. All elements must contain at least one character.
 
-- Application identifiers must contain at least one '.' (period)
-character (and thus at least two elements).
+- Each element must only contain the ASCII characters `[A-Z][a-z][0-9]_-`,
+with `-` discouraged in new application identifiers. Each element must not
+begin with a digit.
 
-- Application identifiers must not begin or end with a '.' (period)
-character.
+- Application identifiers must contain at least one `.` (period) character
+(and thus at least two elements).
 
-- Application identifiers must not contain consecutive '.' (period)
-characters.
+- Application identifiers must not begin with a `.` (period) character.
 
 - Application identifiers must not exceed 255 characters.
 
+Note that the hyphen (`-`) character is allowed in application identifiers,
+but is problematic or not allowed in various specifications and APIs that
+refer to D-Bus, such as
+[Flatpak application IDs](http://docs.flatpak.org/en/latest/introduction.html#identifiers),
+the
+[`DBusActivatable` interface in the Desktop Entry 
Specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus),
+and the convention that an application's &quot;main&quot; interface and object path
+resemble its application identifier and bus name. To avoid situations that
+require special-case handling, it is recommended that new application
+identifiers consistently replace hyphens with underscores.
+
+Like D-Bus interface names, application identifiers should start with the
+reversed DNS domain name of the author of the interface (in lower-case), and
+it is conventional for the rest of the application identifier to consist of
+words run together, with initial capital letters.
+
+As with D-Bus interface names, if the author's DNS domain name contains
+hyphen/minus characters they should be replaced by underscores, and if it
+contains leading digits they should be escaped by prepending an underscore.
+For example, if the owner of 7-zip.org used an application identifier for an
+archiving application, it might be named `org._7_zip.Archiver`.
+
 
 </description>
 <parameters>
@@ -10371,6 +10394,78 @@ Since: 2.28
 <return></return>
 </function>
 
+<function name="g_application_set_option_context_description">
+<description>
+Adds a description to the @application option context.
+
+See g_option_context_set_description() for more information.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="description">
+<parameter_description> a string to be shown in `--help` output
+after the list of options, or %NULL
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_application_set_option_context_parameter_string">
+<description>
+Sets the parameter string to be used by the commandline handling of @application.
+
+This function registers the argument to be passed to g_option_context_new()
+when the internal #GOptionContext of @application is created.
+
+See g_option_context_new() for more information about @parameter_string.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="parameter_string">
+<parameter_description> a string which is displayed
+in the first line of `--help` output, after the usage summary `programname [OPTION...]`.
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
+<function name="g_application_set_option_context_summary">
+<description>
+Adds a summary to the @application option context.
+
+See g_option_context_set_summary() for more information.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="application">
+<parameter_description> the #GApplication
+</parameter_description>
+</parameter>
+<parameter name="summary">
+<parameter_description> a string to be shown in `--help` output
+before the list of options, or %NULL
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
 <function name="g_application_set_resource_base_path">
 <description>
 Sets (or unsets) the base resource path of @application.
@@ -13483,6 +13578,8 @@ functions will be marked as deprecated in a future release.  Use
 g_data_input_stream_read_upto() instead, but note that that function
 does not consume the stop character.
 
+Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more
+consistent behaviour regarding the stop character.
 
 </description>
 <parameters>
@@ -13533,6 +13630,8 @@ will be marked as deprecated in a future release.  Use
 g_data_input_stream_read_upto_async() instead.
 
 Since: 2.20
+Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which
+has more consistent behaviour regarding the stop character.
 
 </description>
 <parameters>
@@ -13571,6 +13670,8 @@ g_data_input_stream_read_until_async().
 
 Since: 2.20
 
+Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which
+has more consistent behaviour regarding the stop character.
 
 </description>
 <parameters>
@@ -13611,6 +13712,8 @@ g_data_input_stream_read_upto() again.
 Note that @stop_chars may contain '\0' if @stop_chars_len is
 specified.
 
+The returned string will always be nul-terminated on success.
+
 Since: 2.26
 
 </description>
@@ -13712,6 +13815,8 @@ Note that this function does not consume the stop character. You
 have to use g_data_input_stream_read_byte() to get it before calling
 g_data_input_stream_read_upto_async() again.
 
+The returned string will always be nul-terminated on success.
+
 Since: 2.24
 
 </description>
@@ -14805,7 +14910,9 @@ not compatible with the D-Bus protocol, the operation fails with
 
 If @reply_type is non-%NULL then the reply will be checked for having this type and an
 error will be raised if it does not match.  Said another way, if you give a @reply_type
-then any non-%NULL return value will be of this type.
+then any non-%NULL return value will be of this type. Unless it’s
+%G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more
+values.
 
 If the @parameters #GVariant is floating, it is consumed. This allows
 convenient 'inline' use of g_variant_new(), e.g.:
@@ -14868,7 +14975,8 @@ or %NULL if not passing parameters
 </parameter_description>
 </parameter>
 <parameter name="reply_type">
-<parameter_description> the expected type of the reply, or %NULL
+<parameter_description> the expected type of the reply (which will be a
+tuple), or %NULL
 </parameter_description>
 </parameter>
 <parameter name="flags">
@@ -15311,7 +15419,9 @@ Emits a signal.
 
 If the parameters GVariant is floating, it is consumed.
 
-This can only fail if @parameters is not compatible with the D-Bus protocol.
+This can only fail if @parameters is not compatible with the D-Bus protocol
+(%G_IO_ERROR_INVALID_ARGUMENT), or if @connection has been closed
+(%G_IO_ERROR_CLOSED).
 
 Since: 2.26
 
@@ -17396,7 +17506,7 @@ emitted immediately.
 
 For example, an exported D-Bus interface may queue up property
 changes and emit the
-`org.freedesktop.DBus.Properties::PropertiesChanged`
+`org.freedesktop.DBus.Properties.PropertiesChanged`
 signal later (e.g. in an idle handler). This technique is useful
 for collapsing multiple property changes into one.
 
@@ -19339,7 +19449,7 @@ else
 g_dbus_method_invocation_return_value (invocation,
 g_variant_new (&quot;(s)&quot;, result_string));
 
-/&lt;!-- --&gt;* Do not free @invocation here; returning a value does that *&lt;!-- --&gt;/
+// Do not free @invocation here; returning a value does that
 ]|
 
 This method will take ownership of @invocation. See
@@ -20771,9 +20881,9 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A reference to the #GVariant instance that holds the value
-for @property_name or %NULL if the value is not in the cache. The
-returned reference must be freed with g_variant_unref().
+<return> A reference to the #GVariant instance
+that holds the value for @property_name or %NULL if the value is not in
+the cache. The returned reference must be freed with g_variant_unref().
 
 </return>
 </function>
@@ -20791,7 +20901,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A %NULL-terminated array of strings or %NULL if
+<return> A
+%NULL-terminated array of strings or %NULL if
 @proxy has no cached properties. Free the returned array with
 g_strfreev().
 
@@ -20871,8 +20982,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusInterfaceInfo or %NULL. Do not unref the returned
-object, it is owned by @proxy.
+<return> A #GDBusInterfaceInfo or %NULL.
+Do not unref the returned object, it is owned by @proxy.
 
 </return>
 </function>
@@ -20929,7 +21040,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> The name owner or %NULL if no name owner exists. Free with g_free().
+<return> The name owner or %NULL if no name
+owner exists. Free with g_free().
 
 </return>
 </function>
@@ -21039,7 +21151,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if @error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21111,7 +21224,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if @error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21160,7 +21274,8 @@ that @proxy conforms to or %NULL.
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21223,7 +21338,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 </parameters>
-<return> A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+<return> A #GDBusProxy or %NULL if error is set.
+Free with g_object_unref().
 
 </return>
 </function>
@@ -21323,7 +21439,8 @@ Since: 2.26
 </parameter_description>
 </parameter>
 <parameter name="info">
-<parameter_description> Minimum interface this proxy conforms to or %NULL to unset.
+<parameter_description> Minimum interface this proxy conforms to
+or %NULL to unset.
 </parameter_description>
 </parameter>
 </parameters>
@@ -21690,6 +21807,32 @@ Since: 2.32
 </return>
 </function>
 
+<function name="g_desktop_app_info_get_locale_string">
+<description>
+Looks up a localized string value in the keyfile backing @info
+translated to the current locale.
+
+The @key is looked up in the &quot;Desktop Entry&quot; group.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="info">
+<parameter_description> a #GDesktopAppInfo
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> the key to look up
+</parameter_description>
+</parameter>
+</parameters>
+<return> a newly allocated string, or %NULL if the key
+is not found
+
+</return>
+</function>
+
 <function name="g_desktop_app_info_get_nodisplay">
 <description>
 Gets the value of the NoDisplay key, which helps determine if the
@@ -28971,6 +29114,30 @@ the @parse_name cannot be parsed.
 </return>
 </function>
 
+<function name="g_file_peek_path">
+<description>
+Exactly like g_file_get_path(), but caches the result via
+g_object_set_qdata_full().  This is useful for example in C
+applications which mix `g_file_*` APIs with native ones.  It
+also avoids an extra duplicated string when possible, so will be
+generally more efficient.
+
+This call does no blocking I/O.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="file">
+<parameter_description> input #GFile
+</parameter_description>
+</parameter>
+</parameters>
+<return> string containing the #GFile's path,
+or %NULL if no such path exists. The returned string is owned by @file.
+</return>
+</function>
+
 <function name="g_file_poll_mountable">
 <description>
 Polls a file of type #G_FILE_TYPE_MOUNTABLE.
@@ -29074,7 +29241,7 @@ When you are done with it, release it with g_object_unref()
 Utility function to check if a particular file exists. This is
 implemented using g_file_query_info() and as such does blocking I/O.
 
-Note that in many cases it is racy to first check for file existence
+Note that in many cases it is [racy to first check for file 
existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
 and then execute something based on the outcome of that, because the
 file might have been created or removed in between the operations. The
 general approach to handling that is to not check, but just do the
@@ -33217,6 +33384,14 @@ This function is run after the module has been loaded into GIO,
 to initialize the module. Typically, this function will call
 g_io_extension_point_implement().
 
+Since 2.56, this function should be named `g_io_&lt;modulename&gt;_load`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
 </description>
 <parameters>
 <parameter name="module">
@@ -33271,6 +33446,14 @@ When installing a module that implements g_io_module_query() you must
 run gio-querymodules in order to build the cache files required for
 lazy loading.
 
+Since 2.56, this function should be named `g_io_&lt;modulename&gt;_query`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
 Since: 2.24
 
 </description>
@@ -33351,6 +33534,14 @@ Required API for GIO modules to implement.
 This function is run when the module is being unloaded from GIO,
 to finalize the module.
 
+Since 2.56, this function should be named `g_io_&lt;modulename&gt;_unload`, where
+`modulename` is the plugin’s filename with the `lib` or `libgio` prefix and
+everything after the first dot removed, and with `-` replaced with `_`
+throughout. For example, `libgiognutls-helper.so` becomes `gnutls_helper`.
+Using the new symbol names avoids name clashes when building modules
+statically. The old symbol names continue to be supported, but cannot be used
+for static builds.
+
 </description>
 <parameters>
 <parameter name="module">
@@ -37374,7 +37565,7 @@ If no port is specified in @host_and_port then @default_port will be
 used as the port number to connect to.
 
 In general, @host_and_port is expected to be provided by the user
-(allowing them to give the hostname, and a port overide if necessary)
+(allowing them to give the hostname, and a port override if necessary)
 and @default_port is expected to be provided by the application.
 
 (The port component of @host_and_port can also be specified as a
@@ -38146,6 +38337,8 @@ Since: 2.40
 Deprecated in favor of g_notification_set_priority().
 
 Since: 2.40
+Deprecated: 2.42: Since 2.42, this has been deprecated in favour of
+g_notification_set_priority().
 
 </description>
 <parameters>
@@ -39608,6 +39801,9 @@ if @cancellable has already been cancelled when you call, which
 may happen if you call this method after a source triggers due
 to having been cancelled.
 
+Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
+transports like D/TLS require that you send the same @buffer and @count.
+
 Virtual: write_nonblocking
 
 </description>
@@ -42699,7 +42895,7 @@ with it.
 
 <function name="g_settings_list_relocatable_schemas">
 <description>
-&lt;!-- --&gt;
+Deprecated.
 
 Since: 2.28
 
@@ -42717,7 +42913,7 @@ modified or freed.
 
 <function name="g_settings_list_schemas">
 <description>
-&lt;!-- --&gt;
+Deprecated.
 
 Since: 2.26
 
@@ -47933,6 +48129,10 @@ is helpful for determining the port number that was used for when
 requesting a binding to port 0 (ie: &quot;any port&quot;).  This address, if
 requested, belongs to the caller and must be freed.
 
+Call g_socket_listener_close() to stop listening on @address; this will not
+be done automatically when you drop your final reference to @listener, as
+references may be held internally.
+
 Since: 2.22
 
 </description>
@@ -48018,6 +48218,10 @@ to accept to identify this particular source, which is
 useful if you're listening on multiple addresses and do
 different things depending on what address is connected to.
 
+Call g_socket_listener_close() to stop listening on @port; this will not
+be done automatically when you drop your final reference to @listener, as
+references may be held internally.
+
 Since: 2.22
 
 </description>
@@ -52522,12 +52726,15 @@ known.
 
 <function name="g_tls_client_connection_get_use_ssl3">
 <description>
-Gets whether @conn will use SSL 3.0 rather than the
-highest-supported version of TLS; see
-g_tls_client_connection_set_use_ssl3().
+Gets whether @conn will force the lowest-supported TLS protocol
+version rather than attempt to negotiate the highest mutually-
+supported version of TLS; see g_tls_client_connection_set_use_ssl3().
 
 Since: 2.28
 
+Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+actually indicate whether it is enabled.
+
 </description>
 <parameters>
 <parameter name="conn">
@@ -52535,7 +52742,7 @@ Since: 2.28
 </parameter_description>
 </parameter>
 </parameters>
-<return> whether @conn will use SSL 3.0
+<return> whether @conn will use the lowest-supported TLS protocol version
 
 </return>
 </function>
@@ -52616,14 +52823,20 @@ Since: 2.28
 
 <function name="g_tls_client_connection_set_use_ssl3">
 <description>
-If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
-trying to properly negotiate the right version of TLS or SSL to use.
-This can be used when talking to servers that do not implement the
-fallbacks correctly and which will therefore fail to handshake with
-a &quot;modern&quot; TLS handshake attempt.
+If @use_ssl3 is %TRUE, this forces @conn to use the lowest-supported
+TLS protocol version rather than trying to properly negotiate the
+highest mutually-supported protocol version with the peer. This can
+be used when talking to broken TLS servers that exhibit protocol
+version intolerance.
+
+Be aware that SSL 3.0 is generally disabled by the #GTlsBackend, so
+the lowest-supported protocol version is probably not SSL 3.0.
 
 Since: 2.28
 
+Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+generally enable or disable it, despite its name.
+
 </description>
 <parameters>
 <parameter name="conn">
@@ -52631,7 +52844,7 @@ Since: 2.28
 </parameter_description>
 </parameter>
 <parameter name="use_ssl3">
-<parameter_description> whether to use SSL 3.0
+<parameter_description> whether to use the lowest-supported protocol version
 </parameter_description>
 </parameter>
 </parameters>
diff --git a/gio/src/gio_methods.defs b/gio/src/gio_methods.defs
index 7e54a15..06924b0 100644
--- a/gio/src/gio_methods.defs
+++ b/gio/src/gio_methods.defs
@@ -759,6 +759,13 @@
   (gtype-id "G_TYPE_WIN32_INPUT_STREAM")
 )
 
+(define-object 32NetworkMonitor
+  (in-module "GWin")
+  (parent "GNetworkMonitorBase")
+  (c-name "GWin32NetworkMonitor")
+  (gtype-id "G_TYPE_WIN32_NETWORK_MONITOR")
+)
+
 (define-object 32OutputStream
   (in-module "GWin")
   (parent "GOutputStream")
@@ -2753,6 +2760,33 @@
   )
 )
 
+(define-method set_option_context_parameter_string
+  (of-object "GApplication")
+  (c-name "g_application_set_option_context_parameter_string")
+  (return-type "none")
+  (parameters
+    '("const-gchar*" "parameter_string")
+  )
+)
+
+(define-method set_option_context_summary
+  (of-object "GApplication")
+  (c-name "g_application_set_option_context_summary")
+  (return-type "none")
+  (parameters
+    '("const-gchar*" "summary")
+  )
+)
+
+(define-method set_option_context_description
+  (of-object "GApplication")
+  (c-name "g_application_set_option_context_description")
+  (return-type "none")
+  (parameters
+    '("const-gchar*" "description")
+  )
+)
+
 (define-method get_is_registered
   (of-object "GApplication")
   (c-name "g_application_get_is_registered")
@@ -6870,6 +6904,15 @@
   )
 )
 
+(define-method get_locale_string
+  (of-object "GDesktopAppInfo")
+  (c-name "g_desktop_app_info_get_locale_string")
+  (return-type "char*")
+  (parameters
+    '("const-char*" "key")
+  )
+)
+
 (define-method get_boolean
   (of-object "GDesktopAppInfo")
   (c-name "g_desktop_app_info_get_boolean")
@@ -7882,6 +7925,12 @@
   (return-type "char*")
 )
 
+(define-method peek_path
+  (of-object "GFile")
+  (c-name "g_file_peek_path")
+  (return-type "const-char*")
+)
+
 (define-method get_uri
   (of-object "GFile")
   (c-name "g_file_get_uri")
@@ -20137,6 +20186,10 @@
 
 
 
+;; From gwin32networkmonitor.h
+
+
+
 ;; From gwin32outputstream.h
 
 (define-function g_win32_output_stream_get_type
diff --git a/gio/src/gio_signals.defs b/gio/src/gio_signals.defs
index 90e1ecb..0f875dd 100644
--- a/gio/src/gio_signals.defs
+++ b/gio/src/gio_signals.defs
@@ -2286,6 +2286,7 @@
   (readable #t)
   (writable #t)
   (construct-only #f)
+  (deprecated #t)
   (default-value "FALSE")
 )
 
diff --git a/glib/src/glib_docs.xml b/glib/src/glib_docs.xml
index 3d3c71e..de2fe40 100644
--- a/glib/src/glib_docs.xml
+++ b/glib/src/glib_docs.xml
@@ -195,7 +195,9 @@ sets is not supported.
 </parameter_description>
 </parameter>
 <parameter name="G_CONVERT_ERROR_ILLEGAL_SEQUENCE">
-<parameter_description> Invalid byte sequence in conversion input.
+<parameter_description> Invalid byte sequence in conversion input;
+or the character sequence could not be represented in the target
+character set.
 </parameter_description>
 </parameter>
 <parameter name="G_CONVERT_ERROR_FAILED">
@@ -218,6 +220,12 @@ sets is not supported.
 <parameter_description> No memory available. Since: 2.40
 </parameter_description>
 </parameter>
+<parameter name="G_CONVERT_ERROR_EMBEDDED_NUL">
+<parameter_description> An embedded NUL character is present in
+conversion output where a NUL-terminated string is expected.
+Since: 2.56
+</parameter_description>
+</parameter>
 </parameters>
 </enum>
 
@@ -4333,7 +4341,8 @@ Sets a function to clear an element of @array.
 
 The @clear_func will be called when an element in the array
 data segment is removed and when the array is freed and data
-segment is deallocated as well.
+segment is deallocated as well. @clear_func will be passed a
+pointer to the element to clear, rather than the element itself.
 
 Note that in contrast with other uses of #GDestroyNotify
 functions, @clear_func is expected to clear the contents of
@@ -6891,9 +6900,9 @@ g_autofree guint8* membuf = NULL;
 
 membuf = g_malloc (8192);
 
-/&lt;!-- --&gt;* Some computation on membuf *&lt;!-- --&gt;/
+// Some computation on membuf
 
-/&lt;!-- --&gt;* membuf will be automatically freed here *&lt;!-- --&gt;/
+// membuf will be automatically freed here
 return TRUE;
 }
 ]|
@@ -6906,6 +6915,41 @@ Since: 2.44
 <return></return>
 </function>
 
+<function name="g_autolist">
+<description>
+Helper to declare a list variable with automatic deep cleanup.
+
+The list is deeply freed, in a way appropriate to the specified type, when the
+variable goes out of scope.  The type must support this.
+
+This feature is only supported on GCC and clang.  This macro is not
+defined on other compilers and should not be used in programs that
+are intended to be portable to those compilers.
+
+This is meant to be used to declare lists of a type with a cleanup
+function.  The type of the variable is a GList *.  You
+must not add your own '*'.
+
+This macro can be used to avoid having to do explicit cleanups of
+local variables when exiting functions.  It often vastly simplifies
+handling of error conditions, removing the need for various tricks
+such as 'goto out' or repeating of cleanup code.  It is also helpful
+for non-error cases.
+
+See also g_autoslist(), g_autoptr() and g_steal_pointer().
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="TypeName">
+<parameter_description> a supported variable type
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
 <function name="g_autoptr">
 <description>
 Helper to declare a pointer variable with automatic cleanup.
@@ -6972,6 +7016,41 @@ Since: 2.44
 <return></return>
 </function>
 
+<function name="g_autoslist">
+<description>
+Helper to declare a singly linked list variable with automatic deep cleanup.
+
+The list is deeply freed, in a way appropriate to the specified type, when the
+variable goes out of scope.  The type must support this.
+
+This feature is only supported on GCC and clang.  This macro is not
+defined on other compilers and should not be used in programs that
+are intended to be portable to those compilers.
+
+This is meant to be used to declare lists of a type with a cleanup
+function.  The type of the variable is a GSList *.  You
+must not add your own '*'.
+
+This macro can be used to avoid having to do explicit cleanups of
+local variables when exiting functions.  It often vastly simplifies
+handling of error conditions, removing the need for various tricks
+such as 'goto out' or repeating of cleanup code.  It is also helpful
+for non-error cases.
+
+See also g_autolist(), g_autoptr() and g_steal_pointer().
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="TypeName">
+<parameter_description> a supported variable type
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
 <function name="g_base64_decode">
 <description>
 Decode a sequence of Base-64 encoded text into binary data.  Note
@@ -8094,7 +8173,8 @@ Since: 2.12
 </parameter_description>
 </parameter>
 <parameter name="data">
-<parameter_description> desktop bookmarks loaded in memory
+<parameter_description> desktop bookmarks
+loaded in memory
 </parameter_description>
 </parameter>
 <parameter name="length">
@@ -8471,7 +8551,8 @@ Since: 2.12
 </parameter_description>
 </parameter>
 <parameter name="groups">
-<parameter_description> an array of group names, or %NULL to remove all groups
+<parameter_description> an array of
+group names, or %NULL to remove all groups
 </parameter_description>
 </parameter>
 <parameter name="length">
@@ -8679,8 +8760,8 @@ Since: 2.12
 </parameter_description>
 </parameter>
 </parameters>
-<return> a newly allocated string holding
-the contents of the #GBookmarkFile
+<return>
+a newly allocated string holding the contents of the #GBookmarkFile
 
 </return>
 </function>
@@ -9421,6 +9502,12 @@ Creates a #GBytes which is a subsection of another #GBytes. The @offset +
 A reference to @bytes will be held by the newly created #GBytes until
 the byte data is no longer needed.
 
+Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
+@bytes will be returned with the reference count incremented by 1. If @bytes
+is a slice of another #GBytes, then the resulting #GBytes will reference
+the same #GBytes instead of @bytes. This allows consumers to simplify the
+usage of #GBytes when asynchronously writing to streams.
+
 Since: 2.32
 
 </description>
@@ -12323,6 +12410,32 @@ pointer
 <return></return>
 </function>
 
+<function name="g_clear_weak_pointer">
+<description>
+Clears a weak reference to a #GObject.
+
+@weak_pointer_location must not be %NULL.
+
+If the weak reference is %NULL then this function does nothing.
+Otherwise, the weak reference to the object is removed for that location
+and the pointer is set to %NULL.
+
+A macro is also included that allows this function to be used without
+pointer casts. The function itself is static inline, so its address may vary
+between compilation units.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="weak_pointer_location">
+<parameter_description> The memory address of a pointer
+</parameter_description>
+</parameter>
+</parameters>
+<return></return>
+</function>
+
 <function name="g_close">
 <description>
 This wraps the close() call; in case of error, %errno will be
@@ -13418,7 +13531,7 @@ Since: 2.32
 Converts a string from one character set to another.
 
 Note that you should use g_iconv() for streaming conversions. 
-Despite the fact that @byes_read can return information about partial 
+Despite the fact that @bytes_read can return information about partial
 characters, the g_convert_... functions are not generally suitable
 for streaming. If the underlying converter maintains internal state,
 then this won't be preserved across successive calls to g_convert(),
@@ -13434,7 +13547,8 @@ well) on many platforms.  Consider using g_str_to_ascii() instead.
 </description>
 <parameters>
 <parameter name="str">
-<parameter_description>           the string to convert
+<parameter_description>
+the string to convert.
 </parameter_description>
 </parameter>
 <parameter name="len">
@@ -13453,19 +13567,19 @@ for the @len parameter is unsafe)
 </parameter_description>
 </parameter>
 <parameter name="bytes_read">
-<parameter_description>   location to store the number of bytes in the
-input string that were successfully converted, or %NULL.
+<parameter_description> location to store the number of bytes in
+the input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input. If the error
 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
-stored will the byte offset after the last valid
+stored will be the byte offset after the last valid
 input sequence.
 </parameter_description>
 </parameter>
 <parameter name="bytes_written">
-<parameter_description> the number of bytes stored in the output buffer (not 
-including the terminating nul).
+<parameter_description> the number of bytes stored in
+the output buffer (not including the terminating nul).
 </parameter_description>
 </parameter>
 <parameter name="error">
@@ -13474,9 +13588,10 @@ errors. Any of the errors in #GConvertError may occur.
 </parameter_description>
 </parameter>
 </parameters>
-<return> If the conversion was successful, a newly allocated
-nul-terminated string, which must be freed with
-g_free(). Otherwise %NULL and @error will be set.
+<return>
+If the conversion was successful, a newly allocated buffer
+containing the converted string, which must be freed with g_free().
+Otherwise %NULL and @error will be set.
 </return>
 </function>
 
@@ -13491,7 +13606,7 @@ to @to_codeset in their iconv() functions,
 in which case GLib will simply return that approximate conversion.
 
 Note that you should use g_iconv() for streaming conversions. 
-Despite the fact that @byes_read can return information about partial 
+Despite the fact that @bytes_read can return information about partial
 characters, the g_convert_... functions are not generally suitable
 for streaming. If the underlying converter maintains internal state,
 then this won't be preserved across successive calls to g_convert(),
@@ -13504,7 +13619,8 @@ could combine with the base character.)
 </description>
 <parameters>
 <parameter name="str">
-<parameter_description>          the string to convert
+<parameter_description>
+the string to convert.
 </parameter_description>
 </parameter>
 <parameter name="len">
@@ -13523,7 +13639,7 @@ for the @len parameter is unsafe)
 </parameter_description>
 </parameter>
 <parameter name="fallback">
-<parameter_description>     UTF-8 string to use in place of character not
+<parameter_description>     UTF-8 string to use in place of characters not
 present in the target encoding. (The string must be
 representable in the target encoding). 
 If %NULL, characters not in the target encoding will 
@@ -13531,16 +13647,16 @@ be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
 </parameter_description>
 </parameter>
 <parameter name="bytes_read">
-<parameter_description>   location to store the number of bytes in the
-input string that were successfully converted, or %NULL.
+<parameter_description> location to store the number of bytes in
+the input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input.
 </parameter_description>
 </parameter>
 <parameter name="bytes_written">
-<parameter_description> the number of bytes stored in the output buffer (not 
-including the terminating nul).
+<parameter_description> the number of bytes stored in
+the output buffer (not including the terminating nul).
 </parameter_description>
 </parameter>
 <parameter name="error">
@@ -13549,9 +13665,10 @@ errors. Any of the errors in #GConvertError may occur.
 </parameter_description>
 </parameter>
 </parameters>
-<return> If the conversion was successful, a newly allocated
-nul-terminated string, which must be freed with
-g_free(). Otherwise %NULL and @error will be set.
+<return>
+If the conversion was successful, a newly allocated buffer
+containing the converted string, which must be freed with g_free().
+Otherwise %NULL and @error will be set.
 </return>
 </function>
 
@@ -13560,7 +13677,7 @@ g_free(). Otherwise %NULL and @error will be set.
 Converts a string from one character set to another. 
 
 Note that you should use g_iconv() for streaming conversions. 
-Despite the fact that @byes_read can return information about partial 
+Despite the fact that @bytes_read can return information about partial
 characters, the g_convert_... functions are not generally suitable
 for streaming. If the underlying converter maintains internal state,
 then this won't be preserved across successive calls to g_convert(),
@@ -13569,11 +13686,20 @@ this is the GNU C converter for CP1255 which does not emit a base
 character until it knows that the next character is not a mark that
 could combine with the base character.)
 
+Characters which are valid in the input character set, but which have no
+representation in the output character set will result in a
+%G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv()
+specification, which leaves this behaviour implementation defined. Note that
+this is the same error code as is returned for an invalid byte sequence in
+the input character set. To get defined behaviour for conversion of
+unrepresentable characters, use g_convert_with_fallback().
+
 
 </description>
 <parameters>
 <parameter name="str">
-<parameter_description>           the string to convert
+<parameter_description>
+the string to convert.
 </parameter_description>
 </parameter>
 <parameter name="len">
@@ -13588,19 +13714,19 @@ for the @len parameter is unsafe)
 </parameter_description>
 </parameter>
 <parameter name="bytes_read">
-<parameter_description>    location to store the number of bytes in the
-input string that were successfully converted, or %NULL.
+<parameter_description> location to store the number of bytes in
+the input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input. If the error
 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
-stored will the byte offset after the last valid
+stored will be the byte offset after the last valid
 input sequence.
 </parameter_description>
 </parameter>
 <parameter name="bytes_written">
-<parameter_description> the number of bytes stored in the output buffer (not 
-including the terminating nul).
+<parameter_description> the number of bytes stored in
+the output buffer (not including the terminating nul).
 </parameter_description>
 </parameter>
 <parameter name="error">
@@ -13609,8 +13735,9 @@ errors. Any of the errors in #GConvertError may occur.
 </parameter_description>
 </parameter>
 </parameters>
-<return> If the conversion was successful, a newly allocated
-nul-terminated string, which must be freed with
+<return>
+If the conversion was successful, a newly allocated buffer
+containing the converted string, which must be freed with
 g_free(). Otherwise %NULL and @error will be set.
 </return>
 </function>
@@ -13904,7 +14031,7 @@ operation, for a member of @datalist.
 
 If the previous value was replaced then ownership of the
 old value (@oldval) is passed to the caller, including
-the registred destroy notify for it (passed out in @old_destroy).
+the registered destroy notify for it (passed out in @old_destroy).
 Its up to the caller to free this as he wishes, which may
 or may not include using @old_destroy as sometimes replacement
 should not destroy the object in the normal way.
@@ -15425,6 +15552,11 @@ g_date_time_unref().
 Creates a copy of @datetime and adds the specified number of months to the
 copy. Add negative values to subtract months.
 
+The day of the month of the resulting #GDateTime is clamped to the number
+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.
+
 Since: 2.26
 
 </description>
@@ -15497,6 +15629,9 @@ g_date_time_unref().
 Creates a copy of @datetime and adds the specified number of years to the
 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.
+
 Since: 2.26
 
 </description>
@@ -15679,6 +15814,14 @@ for the specifier.
 - 0: Pad a numeric result with zeros. This overrides the default padding
 for the specifier.
 
+Additionally, when O is used with B, b, or h, it produces the alternative
+form of a month name. The alternative form should be used when the month
+name is used without a day number (e.g., standalone). It is required in
+some languages (Baltic, Slavic, Greek, and more) due to their grammatical
+rules. For other languages there is no difference. \%OB is a GNU and BSD
+strftime() extension expected to be added to the future POSIX specification,
+\%Ob and \%Oh are GNU strftime() extensions. Since: 2.56
+
 Since: 2.26
 
 </description>
@@ -18034,11 +18177,17 @@ filenames. Note that on Windows GLib uses UTF-8 for filenames;
 on other platforms, this function indirectly depends on the 
 [current locale][setlocale].
 
+The input string shall not contain nul characters even if the @len
+argument is positive. A nul character found inside the string will result
+in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
+not UTF-8 and the conversion output contains a nul character, the error
+%G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL.
+
 
 </description>
 <parameters>
 <parameter name="utf8string">
-<parameter_description>    a UTF-8 encoded string.
+<parameter_description> a UTF-8 encoded string.
 </parameter_description>
 </parameter>
 <parameter name="len">
@@ -18052,14 +18201,14 @@ the input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input. If the error
-#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
-stored will the byte offset after the last valid
+%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+stored will be the byte offset after the last valid
 input sequence.
 </parameter_description>
 </parameter>
 <parameter name="bytes_written">
-<parameter_description> the number of bytes stored in the output buffer (not 
-including the terminating nul).
+<parameter_description> the number of bytes stored in
+the output buffer (not including the terminating nul).
 </parameter_description>
 </parameter>
 <parameter name="error">
@@ -18109,6 +18258,14 @@ filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8
 for filenames; on other platforms, this function indirectly depends on 
 the [current locale][setlocale].
 
+The input string shall not contain nul characters even if the @len
+argument is positive. A nul character found inside the string will result
+in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+If the source encoding is not UTF-8 and the conversion output contains a
+nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+function returns %NULL. Use g_convert() to produce output that
+may contain embedded nul characters.
+
 
 </description>
 <parameters>
@@ -18129,8 +18286,8 @@ input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input. If the error
-#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
-stored will the byte offset after the last valid
+%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+stored will be the byte offset after the last valid
 input sequence.
 </parameter_description>
 </parameter>
@@ -18553,6 +18710,10 @@ used by the &quot;narrow&quot; versions of C library and Win32 functions that
 handle file names. It might be different from the character set
 used by the C library's current locale.
 
+On Linux, the character set is found by consulting nl_langinfo() if
+available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG`
+and `CHARSET` are queried in order.
+
 The return value is %TRUE if the locale's encoding is UTF-8, in that
 case you can perhaps avoid calling g_convert().
 
@@ -18677,8 +18838,9 @@ Since: 2.6
 
 </description>
 <parameters>
-<parameter name="charsets">
-<parameter_description> return location for the %NULL-terminated list of encoding names
+<parameter name="filename_charsets">
+<parameter_description>
+return location for the %NULL-terminated list of encoding names
 </parameter_description>
 </parameter>
 </parameters>
@@ -18770,6 +18932,34 @@ that must not be modified or freed.
 </return>
 </function>
 
+<function name="g_get_language_names_with_category">
+<description>
+Computes a list of applicable locale names with a locale category name,
+which can be used to construct the fallback locale-dependent filenames
+or search paths. The returned list is sorted from most desirable to
+least desirable and always contains the default locale &quot;C&quot;.
+
+This function consults the environment variables `LANGUAGE`, `LC_ALL`,
+@category_name, and `LANG` to find the list of locales specified by the
+user.
+
+g_get_language_names() returns g_get_language_names_with_category(&quot;LC_MESSAGES&quot;).
+
+Since: 2.58
+
+</description>
+<parameters>
+<parameter name="category_name">
+<parameter_description> a locale category name
+</parameter_description>
+</parameter>
+</parameters>
+<return> a %NULL-terminated array of strings owned by GLib
+that must not be modified or freed.
+
+</return>
+</function>
+
 <function name="g_get_locale_variants">
 <description>
 Returns a list of derived variants of @locale, which can be used to
@@ -19183,6 +19373,10 @@ When a hash table only ever contains keys that have themselves as the
 corresponding value it is able to be stored more efficiently.  See
 the discussion in the section description.
 
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
 Since: 2.32
 
 </description>
@@ -19490,6 +19684,10 @@ value is freed using that function. If you supplied a
 @key_destroy_func when creating the #GHashTable, the passed
 key is freed using that function.
 
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
 
 </description>
 <parameters>
@@ -19877,6 +20075,10 @@ the #GHashTable, the old value is freed using that function.
 If you supplied a @key_destroy_func when creating the
 #GHashTable, the old key is freed using that function.
 
+Starting from GLib 2.40, this function returns a boolean value to
+indicate whether the newly added value was already in the hash table
+or not.
+
 
 </description>
 <parameters>
@@ -20860,6 +21062,13 @@ a native implementation.
 GLib provides g_convert() and g_locale_to_utf8() which are likely
 more convenient than the raw iconv wrappers.
 
+Note that the behaviour of iconv() for characters which are valid in the
+input character set, but which have no representation in the output character
+set, is implementation defined. This function may return success (with a
+positive number of non-reversible conversions as replacement characters were
+used), or it may return -1 and set an error such as %EILSEQ, in such a
+situation.
+
 
 </description>
 <parameters>
@@ -22676,12 +22885,55 @@ Use g_strfreev() to free it.
 </return>
 </function>
 
+<function name="g_key_file_get_locale_for_key">
+<description>
+Returns the actual locale which the result of
+g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
+came from.
+
+If calling g_key_file_get_locale_string() or
+g_key_file_get_locale_string_list() with exactly the same @key_file,
+@group_name, @key and @locale, the result of those functions will
+have originally been tagged with the locale that is the result of
+this function.
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="key_file">
+<parameter_description> a #GKeyFile
+</parameter_description>
+</parameter>
+<parameter name="group_name">
+<parameter_description> a group name
+</parameter_description>
+</parameter>
+<parameter name="key">
+<parameter_description> a key
+</parameter_description>
+</parameter>
+<parameter name="locale">
+<parameter_description> a locale identifier or %NULL
+</parameter_description>
+</parameter>
+</parameters>
+<return> the locale from the file, or %NULL if the key was not
+found or the entry in the file was was untranslated
+
+</return>
+</function>
+
 <function name="g_key_file_get_locale_string">
 <description>
 Returns the value associated with @key under @group_name
 translated in the given @locale if available.  If @locale is
 %NULL then the current locale is assumed. 
 
+If @locale is to be non-%NULL, or if the current locale will change over
+the lifetime of the #GKeyFile, it must be loaded with
+%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.
+
 If @key cannot be found then %NULL is returned and @error is set 
 to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the value associated
 with @key cannot be interpreted or no suitable translation can
@@ -22724,6 +22976,10 @@ Returns the values associated with @key under @group_name
 translated in the given @locale if available.  If @locale is
 %NULL then the current locale is assumed.
 
+If @locale is to be non-%NULL, or if the current locale will change over
+the lifetime of the #GKeyFile, it must be loaded with
+%G_KEY_FILE_KEEP_TRANSLATIONS in order to load strings for all locales.
+
 If @key cannot be found then %NULL is returned and @error is set 
 to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
 with @key cannot be interpreted or no suitable translations
@@ -24721,6 +24977,11 @@ the C runtime (usually the same as that used by the operating
 system) in the [current locale][setlocale]. On Windows this means
 the system codepage.
 
+The input string shall not contain nul characters even if the @len
+argument is positive. A nul character found inside the string will result
+in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert
+input that may contain embedded nul characters.
+
 
 </description>
 <parameters>
@@ -24730,9 +24991,7 @@ the system codepage.
 </parameter>
 <parameter name="len">
 <parameter_description>           the length of the string, or -1 if the string is
-nul-terminated (Note that some encodings may allow nul
-bytes to occur inside strings. In that case, using -1
-for the @len parameter is unsafe)
+nul-terminated.
 </parameter_description>
 </parameter>
 <parameter name="bytes_read">
@@ -24741,8 +25000,8 @@ input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input. If the error
-#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
-stored will the byte offset after the last valid
+%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+stored will be the byte offset after the last valid
 input sequence.
 </parameter_description>
 </parameter>
@@ -24757,7 +25016,8 @@ errors. Any of the errors in #GConvertError may occur.
 </parameter_description>
 </parameter>
 </parameters>
-<return> A newly-allocated buffer containing the converted string,
+<return>
+A newly-allocated buffer containing the converted string,
 or %NULL on an error, and error will be set.
 </return>
 </function>
@@ -24768,11 +25028,20 @@ Converts a string which is in the encoding used for strings by
 the C runtime (usually the same as that used by the operating
 system) in the [current locale][setlocale] into a UTF-8 string.
 
+If the source encoding is not UTF-8 and the conversion output contains a
+nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+function returns %NULL.
+If the source encoding is UTF-8, an embedded nul character is treated with
+the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with
+earlier versions of this library. Use g_convert() to produce output that
+may contain embedded nul characters.
+
 
 </description>
 <parameters>
 <parameter name="opsysstring">
-<parameter_description>   a string in the encoding of the current locale. On Windows
+<parameter_description> a string in the
+encoding of the current locale. On Windows
 this means the system codepage.
 </parameter_description>
 </parameter>
@@ -24789,8 +25058,8 @@ input string that were successfully converted, or %NULL.
 Even if the conversion was successful, this may be 
 less than @len if there were partial characters
 at the end of the input. If the error
-#G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
-stored will the byte offset after the last valid
+%G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+stored will be the byte offset after the last valid
 input sequence.
 </parameter_description>
 </parameter>
@@ -24805,8 +25074,7 @@ errors. Any of the errors in #GConvertError may occur.
 </parameter_description>
 </parameter>
 </parameters>
-<return> A newly-allocated buffer containing the converted string,
-or %NULL on an error, and error will be set.
+<return> The converted string, or %NULL on an error.
 </return>
 </function>
 
@@ -29782,8 +30050,8 @@ or %NULL
 </parameter_description>
 </parameter>
 <parameter name="notify">
-<parameter_description> function to be called when disposing the binding, to free the
-resources used by the transformation functions
+<parameter_description> a function to call when disposing the binding, to free
+resources used by the transformation functions, or %NULL if not required
 </parameter_description>
 </parameter>
 </parameters>
@@ -30478,6 +30746,8 @@ vtable initialization function (the @class_init member of
 #GTypeInfo.) It must not be called after after @class_init has
 been called for any object types implementing this interface.
 
+If @pspec is a floating reference, it will be consumed.
+
 Since: 2.4
 
 </description>
@@ -30861,7 +31131,7 @@ operation, for user data on an object.
 If the previous value was replaced then ownership of the
 old value (@oldval) is passed to the caller, including
 the registered destroy notify for it (passed out in @old_destroy).
-Its up to the caller to free this as he wishes, which may
+It’s up to the caller to free this as needed, which may
 or may not include using @old_destroy as sometimes replacement
 should not destroy the object in the normal way.
 
@@ -30912,7 +31182,7 @@ operation, for user data on an object.
 If the previous value was replaced then ownership of the
 old value (@oldval) is passed to the caller, including
 the registered destroy notify for it (passed out in @old_destroy).
-Its up to the caller to free this as he wishes, which may
+It’s up to the caller to free this as needed, which may
 or may not include using @old_destroy as sometimes replacement
 should not destroy the object in the normal way.
 
@@ -34346,8 +34616,7 @@ error message. If @err is %NULL (ie: no error variable) then do
 nothing.
 
 If *@err is %NULL (ie: an error variable is present but there is no
-error condition) then also do nothing. Whether or not it makes sense
-to take advantage of this feature is up to you.
+error condition) then also do nothing.
 
 Since: 2.16
 
@@ -39073,6 +39342,10 @@ It should return 0 if the items are equal, a negative value
 if the first item comes before the second, and a positive value
 if the second  item comes before the first.
 
+Note that when adding a large amount of data to a #GSequence,
+it is more efficient to do unsorted insertions and then call
+g_sequence_sort() or g_sequence_sort_iter().
+
 Since: 2.14
 
 </description>
@@ -39115,6 +39388,10 @@ return 0 if the iterators are equal, a negative value if the
 first iterator comes before the second, and a positive value
 if the second iterator comes before the first.
 
+Note that when adding a large amount of data to a #GSequence,
+it is more efficient to do unsorted insertions and then call
+g_sequence_sort() or g_sequence_sort_iter().
+
 Since: 2.14
 
 </description>
@@ -39340,10 +39617,7 @@ the first item comes before the second, and a positive value if
 the second item comes before the first.
 
 This function will fail if the data contained in the sequence is
-unsorted.  Use g_sequence_insert_sorted() or
-g_sequence_insert_sorted_iter() to add data to your sequence or, if
-you want to add a large amount of data, call g_sequence_sort() after
-doing unsorted insertions.
+unsorted.
 
 Since: 2.28
 
@@ -39384,10 +39658,7 @@ if the first iterator comes before the second, and a positive
 value if the second iterator comes before the first.
 
 This function will fail if the data contained in the sequence is
-unsorted.  Use g_sequence_insert_sorted() or
-g_sequence_insert_sorted_iter() to add data to your sequence or, if
-you want to add a large amount of data, call g_sequence_sort() after
-doing unsorted insertions.
+unsorted.
 
 Since: 2.28
 
@@ -39599,10 +39870,7 @@ If you are simply searching for an existing element of the sequence,
 consider using g_sequence_lookup().
 
 This function will fail if the data contained in the sequence is
-unsorted.  Use g_sequence_insert_sorted() or
-g_sequence_insert_sorted_iter() to add data to your sequence or, if
-you want to add a large amount of data, call g_sequence_sort() after
-doing unsorted insertions.
+unsorted.
 
 Since: 2.14
 
@@ -39645,10 +39913,7 @@ If you are simply searching for an existing element of the sequence,
 consider using g_sequence_lookup_iter().
 
 This function will fail if the data contained in the sequence is
-unsorted.  Use g_sequence_insert_sorted() or
-g_sequence_insert_sorted_iter() to add data to your sequence or, if
-you want to add a large amount of data, call g_sequence_sort() after
-doing unsorted insertions.
+unsorted.
 
 Since: 2.14
 
@@ -40045,6 +40310,53 @@ example.
 </return>
 </function>
 
+<function name="g_set_weak_pointer">
+<description>
+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
+is not atomic. The weak reference is not thread-safe, see
+g_object_add_weak_pointer() for details.
+
+@weak_pointer_location must not be %NULL.
+
+A macro is also included that allows this function to be used without
+pointer casts. The function itself is static inline, so its address may vary
+between compilation units.
+
+One convenient usage of this function is in implementing property setters:
+|[
+void
+foo_set_bar (Foo *foo,
+Bar *new_bar)
+{
+g_return_if_fail (IS_FOO (foo));
+g_return_if_fail (new_bar == NULL || IS_BAR (new_bar));
+
+if (g_set_weak_pointer (&amp;foo-&gt;bar, new_bar))
+g_object_notify (foo, &quot;bar&quot;);
+}
+]|
+
+Since: 2.56
+
+</description>
+<parameters>
+<parameter name="weak_pointer_location">
+<parameter_description> the memory address of a pointer
+</parameter_description>
+</parameter>
+<parameter name="new_object">
+<parameter_description> a pointer to the new #GObject to
+assign to it, or %NULL to clear the pointer
+</parameter_description>
+</parameter>
+</parameters>
+<return> %TRUE if the value of @weak_pointer_location changed, %FALSE otherwise
+
+</return>
+</function>
+
 <function name="g_setenv">
 <description>
 Sets an environment variable. On UNIX, both the variable's name and
@@ -44018,7 +44330,7 @@ will be discarded, instead of going to the same location as the parent's
 standard error. If you use this flag, @standard_error must be %NULL.
 %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
 standard input (by default, the child's standard input is attached to
-/dev/null). If you use this flag, @standard_input must be %NULL.
+`/dev/null`). If you use this flag, @standard_input must be %NULL.
 %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
 the file to execute, while the remaining elements are the actual
 argument vector to pass to the file. Normally g_spawn_async_with_pipes()
@@ -44055,8 +44367,8 @@ The caller of g_spawn_async_with_pipes() must close these file descriptors
 when they are no longer in use. If these parameters are %NULL, the
 corresponding pipe won't be created.
 
-If @standard_input is NULL, the child's standard input is attached to 
-/dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
+If @standard_input is %NULL, the child's standard input is attached to
+`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
 
 If @standard_error is NULL, the child's standard error goes to the same 
 location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL 
@@ -47816,15 +48128,16 @@ This can also be used to force a test to run that would otherwise
 be skipped (ie, a test whose name contains &quot;/subprocess&quot;).
 - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
 
-`perf`: Performance tests, may take long and report results.
+`perf`: Performance tests, may take long and report results (off by default).
 
-`slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage.
+`slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage
+(off by default).
 
-`quick`: Quick tests, should run really quickly and give good coverage.
+`quick`: Quick tests, should run really quickly and give good coverage (the default).
 
 `undefined`: Tests for undefined behaviour, may provoke programming errors
 under g_test_trap_subprocess() or g_test_expect_message() to check
-that appropriate assertions or warnings are given
+that appropriate assertions or warnings are given (the default).
 
 `no-undefined`: Avoid tests for undefined behaviour
 
@@ -48038,6 +48351,10 @@ Since: 2.16
 <description>
 Returns %TRUE if tests are run in performance mode.
 
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the option `-m perf` enables performance tests, while
+`-m quick` disables them.
+
 
 </description>
 <parameters>
@@ -48113,6 +48430,10 @@ Returns %TRUE if tests are run in quick mode.
 Exactly one of g_test_quick() and g_test_slow() is active in any run;
 there is no &quot;medium speed&quot;.
 
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the options `-m quick`, `-m slow` and `-m thorough`
+can be used to change this.
+
 
 </description>
 <parameters>
@@ -48124,6 +48445,8 @@ there is no &quot;medium speed&quot;.
 <function name="g_test_quiet">
 <description>
 Returns %TRUE if tests are run in quiet mode.
+In tests that use g_test_init(), the option `-q` or `--quiet` enables
+this, while `--verbose` disables it.
 The default is neither g_test_verbose() nor g_test_quiet().
 
 
@@ -48353,6 +48676,10 @@ Returns %TRUE if tests are run in slow mode.
 Exactly one of g_test_quick() and g_test_slow() is active in any run;
 there is no &quot;medium speed&quot;.
 
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the options `-m quick`, `-m slow` and `-m thorough`
+can be used to change this.
+
 
 </description>
 <parameters>
@@ -48422,6 +48749,10 @@ Since: 2.16
 Returns %TRUE if tests are run in thorough mode, equivalent to
 g_test_slow().
 
+By default, tests are run in quick mode. In tests that use
+g_test_init(), the options `-m quick`, `-m slow` and `-m thorough`
+can be used to change this.
+
 
 </description>
 <parameters>
@@ -48747,7 +49078,10 @@ Since: 2.38
 <description>
 Returns %TRUE if tests may provoke assertions and other formally-undefined
 behaviour, to verify that appropriate warnings are given. It might, in some
-cases, be useful to turn this off if running tests under valgrind.
+cases, be useful to turn this off with if running tests under valgrind;
+in tests that use g_test_init(), the option `-m no-undefined` disables
+those tests, while `-m undefined` explicitly enables them (the default
+behaviour).
 
 
 </description>
@@ -48760,6 +49094,8 @@ cases, be useful to turn this off if running tests under valgrind.
 <function name="g_test_verbose">
 <description>
 Returns %TRUE if tests are run in verbose mode.
+In tests that use g_test_init(), the option `--verbose` enables this,
+while `-q` or `--quiet` disables it.
 The default is neither g_test_verbose() nor g_test_quiet().
 
 
@@ -52035,6 +52371,9 @@ for the type in this plugin, nothing will be done.
 As long as any instances of the type exist, the type plugin will
 not be unloaded.
 
+Since 2.56 if @module is %NULL this will call g_type_add_interface_static()
+instead. This can be used when making a static build of the module.
+
 </description>
 <parameters>
 <parameter name="module">
@@ -52067,6 +52406,9 @@ is newly registered, and the resulting #GType identifier returned.
 As long as any instances of the type exist, the type plugin will
 not be unloaded.
 
+Since 2.56 if @module is %NULL this will call g_type_register_static()
+instead. This can be used when making a static build of the module.
+
 Since: 2.6
 
 
@@ -52102,6 +52444,9 @@ is newly registered, and the resulting #GType identifier returned.
 As long as any instances of the type exist, the type plugin will
 not be unloaded.
 
+Since 2.56 if @module is %NULL this will call g_type_register_static()
+instead. This can be used when making a static build of the module.
+
 Since: 2.6
 
 
@@ -52141,6 +52486,9 @@ be the same as they were previously.
 As long as any instances of the type exist, the type plugin will
 not be unloaded.
 
+Since 2.56 if @module is %NULL this will call g_type_register_static()
+instead. This can be used when making a static build of the module.
+
 
 </description>
 <parameters>
@@ -54751,6 +55099,9 @@ of characters instead of a given number of bytes. The @src string
 must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
 text before trying to use UTF-8 utility functions with it.)
 
+Note you must ensure @dest is at least 4 * @n to fit the
+largest possible UTF-8 characters
+
 
 </description>
 <parameters>
@@ -59105,7 +59456,7 @@ const gchar *some_strings[] = { &quot;a&quot;, &quot;b&quot;, &quot;c&quot;, NUL
 GVariant *new_variant;
 
 new_variant = g_variant_new (&quot;(t^as)&quot;,
-/&lt;!-- --&gt;* This cast is required. *&lt;!-- --&gt;/
+// This cast is required.
 (guint64) some_flags,
 some_strings);
 ]|
@@ -62127,7 +62478,9 @@ Values of this type can range from #G_MINLONG to #G_MAXLONG.
 <function name="goffset">
 <description>
 A signed integer type that is used for file offsets,
-corresponding to the C99 type off64_t.
+corresponding to the POSIX type `off_t` as if compiling with
+`_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on
+32-bit architectures.
 Values of this type can range from #G_MINOFFSET to
 #G_MAXOFFSET.
 
diff --git a/glib/src/glib_enums.defs b/glib/src/glib_enums.defs
index 361fd9b..1ff200d 100644
--- a/glib/src/glib_enums.defs
+++ b/glib/src/glib_enums.defs
@@ -80,7 +80,8 @@
 ;;   G_CONVERT_ERROR_PARTIAL_INPUT,
 ;;   G_CONVERT_ERROR_BAD_URI,
 ;;   G_CONVERT_ERROR_NOT_ABSOLUTE_PATH,
-;;   G_CONVERT_ERROR_NO_MEMORY
+;;   G_CONVERT_ERROR_NO_MEMORY,
+;;   G_CONVERT_ERROR_EMBEDDED_NUL
 ;; } GConvertError;
 
 (define-enum-extended ConvertError
@@ -94,6 +95,7 @@
     '("bad-uri" "G_CONVERT_ERROR_BAD_URI" "4")
     '("not-absolute-path" "G_CONVERT_ERROR_NOT_ABSOLUTE_PATH" "5")
     '("no-memory" "G_CONVERT_ERROR_NO_MEMORY" "6")
+    '("embedded-nul" "G_CONVERT_ERROR_EMBEDDED_NUL" "7")
   )
 )
 
diff --git a/glib/src/glib_functions.defs b/glib/src/glib_functions.defs
index 219feea..f8d3e05 100644
--- a/glib/src/glib_functions.defs
+++ b/glib/src/glib_functions.defs
@@ -53,6 +53,7 @@
     '("bad-uri" "G_CONVERT_ERROR_BAD_URI")
     '("not-absolute-path" "G_CONVERT_ERROR_NOT_ABSOLUTE_PATH")
     '("no-memory" "G_CONVERT_ERROR_NO_MEMORY")
+    '("embedded-nul" "G_CONVERT_ERROR_EMBEDDED_NUL")
   )
 )
 
@@ -2719,6 +2720,14 @@
   (return-type "const-gchar*-const*")
 )
 
+(define-function g_get_language_names_with_category
+  (c-name "g_get_language_names_with_category")
+  (return-type "const-gchar*-const*")
+  (parameters
+    '("const-gchar*" "category_name")
+  )
+)
+
 (define-function g_get_locale_variants
   (c-name "g_get_locale_variants")
   (return-type "gchar**")
@@ -5766,6 +5775,17 @@
   )
 )
 
+(define-method get_locale_for_key
+  (of-object "GKeyFile")
+  (c-name "g_key_file_get_locale_for_key")
+  (return-type "gchar*")
+  (parameters
+    '("const-gchar*" "group_name")
+    '("const-gchar*" "key")
+    '("const-gchar*" "locale")
+  )
+)
+
 (define-method set_locale_string
   (of-object "GKeyFile")
   (c-name "g_key_file_set_locale_string")
@@ -7818,6 +7838,20 @@
   )
 )
 
+(define-function g_log_structured_standard
+  (c-name "g_log_structured_standard")
+  (return-type "none")
+  (parameters
+    '("const-gchar*" "log_domain")
+    '("GLogLevelFlags" "log_level")
+    '("const-gchar*" "file")
+    '("const-gchar*" "line")
+    '("const-gchar*" "func")
+    '("const-gchar*" "message_format")
+  )
+  (varargs #t)
+)
+
 (define-function g_error
   (c-name "g_error")
   (return-type "none")
diff --git a/glib/src/gobject_functions.defs b/glib/src/gobject_functions.defs
index d03dd09..93ad8d2 100644
--- a/glib/src/gobject_functions.defs
+++ b/glib/src/gobject_functions.defs
@@ -3525,7 +3525,7 @@
   (c-name "g_type_check_value")
   (return-type "gboolean")
   (parameters
-    '("GValue*" "value")
+    '("const-GValue*" "value")
   )
 )
 
@@ -3533,7 +3533,7 @@
   (c-name "g_type_check_value_holds")
   (return-type "gboolean")
   (parameters
-    '("GValue*" "value")
+    '("const-GValue*" "value")
     '("GType" "type")
   )
 )
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]