#! /bin/sh
# depcomp - compile a program generating dependencies as side-effects
-scriptversion=2013-05-30.07; # UTC
+scriptversion=2016-01-11.22; # UTC
-# Copyright (C) 1999-2014 Free Software Foundation, Inc.
+# Copyright (C) 1999-2017 Free Software Foundation, Inc.
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
#!/bin/sh
# py-compile - Compile a Python program
-scriptversion=2011-06-08.12; # UTC
+scriptversion=2016-01-11.22; # UTC
-# Copyright (C) 2000-2014 Free Software Foundation, Inc.
+# Copyright (C) 2000-2017 Free Software Foundation, Inc.
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
#! /bin/sh
# ylwrap - wrapper for lex/yacc invocations.
-scriptversion=2013-01-12.17; # UTC
+scriptversion=2016-01-11.22; # UTC
-# Copyright (C) 1996-2014 Free Software Foundation, Inc.
+# Copyright (C) 1996-2017 Free Software Foundation, Inc.
#
# Written by Tom Tromey <tromey@cygnus.com>.
#
# eval: (add-hook 'write-file-hooks 'time-stamp)
# time-stamp-start: "scriptversion="
# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-time-zone: "UTC"
+# time-stamp-time-zone: "UTC0"
# time-stamp-end: "; # UTC"
# End:
#define PACKAGE_NAME "gobject-introspection"
/* Define to the full name and version of this package. */
-#define PACKAGE_STRING "gojbect-introspection 1.54.1"
+#define PACKAGE_STRING "gojbect-introspection 1.55.0"
/* Define to the one symbol short name of this package. */
#define PACKAGE_TARNAME "gobject-introspection"
#define PACKAGE_URL ""
/* Define to the version of this package. */
-#define PACKAGE_VERSION "1.54.1"
+#define PACKAGE_VERSION "1.55.0"
/* Define to the platform's shared library suffix */
#define SHLIB_SUFFIX ".dll"
#define STDC_HEADERS 1
/* Version number of package */
-#define VERSION "1.54.1"
+#define VERSION "1.55.0"
/* Define to 1 if `lex' declares `yytext' as a `char *' by default, not a
`char[]'. */
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
-# Generated by GNU Autoconf 2.69 for gobject-introspection 1.54.1.
+# Generated by GNU Autoconf 2.69 for gobject-introspection 1.55.0.
#
# Report bugs to <http://bugzilla.gnome.org/enter_bug.cgi?product=gobject-introspection>.
#
# Identity of this package.
PACKAGE_NAME='gobject-introspection'
PACKAGE_TARNAME='gobject-introspection'
-PACKAGE_VERSION='1.54.1'
-PACKAGE_STRING='gobject-introspection 1.54.1'
+PACKAGE_VERSION='1.55.0'
+PACKAGE_STRING='gobject-introspection 1.55.0'
PACKAGE_BUGREPORT='http://bugzilla.gnome.org/enter_bug.cgi?product=gobject-introspection'
PACKAGE_URL=''
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat <<_ACEOF
-\`configure' configures gobject-introspection 1.54.1 to adapt to many kinds of systems.
+\`configure' configures gobject-introspection 1.55.0 to adapt to many kinds of systems.
Usage: $0 [OPTION]... [VAR=VALUE]...
if test -n "$ac_init_help"; then
case $ac_init_help in
- short | recursive ) echo "Configuration of gobject-introspection 1.54.1:";;
+ short | recursive ) echo "Configuration of gobject-introspection 1.55.0:";;
esac
cat <<\_ACEOF
test -n "$ac_init_help" && exit $ac_status
if $ac_init_version; then
cat <<\_ACEOF
-gobject-introspection configure 1.54.1
+gobject-introspection configure 1.55.0
generated by GNU Autoconf 2.69
Copyright (C) 2012 Free Software Foundation, Inc.
This file contains any messages produced by compilers while
running configure, to aid debugging if configure makes a mistake.
-It was created by gobject-introspection $as_me 1.54.1, which was
+It was created by gobject-introspection $as_me 1.55.0, which was
generated by GNU Autoconf 2.69. Invocation command line was
$ $0 $@
# Define the identity of the package.
PACKAGE='gobject-introspection'
- VERSION='1.54.1'
+ VERSION='1.55.0'
cat >>confdefs.h <<_ACEOF
# Used in docs/reference/version.xml
-GI_VERSION=1.54.1
+GI_VERSION=1.55.0
# Check for Win32
pkg_cv_GLIB_CFLAGS="$GLIB_CFLAGS"
elif test -n "$PKG_CONFIG"; then
if test -n "$PKG_CONFIG" && \
- { { $as_echo "$as_me:${as_lineno-$LINENO}: \$PKG_CONFIG --exists --print-errors \"glib-2.0 >= 2.54.0\""; } >&5
- ($PKG_CONFIG --exists --print-errors "glib-2.0 >= 2.54.0") 2>&5
+ { { $as_echo "$as_me:${as_lineno-$LINENO}: \$PKG_CONFIG --exists --print-errors \"glib-2.0 >= 2.55.0\""; } >&5
+ ($PKG_CONFIG --exists --print-errors "glib-2.0 >= 2.55.0") 2>&5
ac_status=$?
$as_echo "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5
test $ac_status = 0; }; then
- pkg_cv_GLIB_CFLAGS=`$PKG_CONFIG --cflags "glib-2.0 >= 2.54.0" 2>/dev/null`
+ pkg_cv_GLIB_CFLAGS=`$PKG_CONFIG --cflags "glib-2.0 >= 2.55.0" 2>/dev/null`
test "x$?" != "x0" && pkg_failed=yes
else
pkg_failed=yes
pkg_cv_GLIB_LIBS="$GLIB_LIBS"
elif test -n "$PKG_CONFIG"; then
if test -n "$PKG_CONFIG" && \
- { { $as_echo "$as_me:${as_lineno-$LINENO}: \$PKG_CONFIG --exists --print-errors \"glib-2.0 >= 2.54.0\""; } >&5
- ($PKG_CONFIG --exists --print-errors "glib-2.0 >= 2.54.0") 2>&5
+ { { $as_echo "$as_me:${as_lineno-$LINENO}: \$PKG_CONFIG --exists --print-errors \"glib-2.0 >= 2.55.0\""; } >&5
+ ($PKG_CONFIG --exists --print-errors "glib-2.0 >= 2.55.0") 2>&5
ac_status=$?
$as_echo "$as_me:${as_lineno-$LINENO}: \$? = $ac_status" >&5
test $ac_status = 0; }; then
- pkg_cv_GLIB_LIBS=`$PKG_CONFIG --libs "glib-2.0 >= 2.54.0" 2>/dev/null`
+ pkg_cv_GLIB_LIBS=`$PKG_CONFIG --libs "glib-2.0 >= 2.55.0" 2>/dev/null`
test "x$?" != "x0" && pkg_failed=yes
else
pkg_failed=yes
_pkg_short_errors_supported=no
fi
if test $_pkg_short_errors_supported = yes; then
- GLIB_PKG_ERRORS=`$PKG_CONFIG --short-errors --print-errors --cflags --libs "glib-2.0 >= 2.54.0" 2>&1`
+ GLIB_PKG_ERRORS=`$PKG_CONFIG --short-errors --print-errors --cflags --libs "glib-2.0 >= 2.55.0" 2>&1`
else
- GLIB_PKG_ERRORS=`$PKG_CONFIG --print-errors --cflags --libs "glib-2.0 >= 2.54.0" 2>&1`
+ GLIB_PKG_ERRORS=`$PKG_CONFIG --print-errors --cflags --libs "glib-2.0 >= 2.55.0" 2>&1`
fi
# Put the nasty error message in config.log where it belongs
echo "$GLIB_PKG_ERRORS" >&5
- as_fn_error $? "Package requirements (glib-2.0 >= 2.54.0) were not met:
+ as_fn_error $? "Package requirements (glib-2.0 >= 2.55.0) were not met:
$GLIB_PKG_ERRORS
# report actual input values of CONFIG_FILES etc. instead of their
# values after options handling.
ac_log="
-This file was extended by gobject-introspection $as_me 1.54.1, which was
+This file was extended by gobject-introspection $as_me 1.55.0, which was
generated by GNU Autoconf 2.69. Invocation command line was
CONFIG_FILES = $CONFIG_FILES
cat >>$CONFIG_STATUS <<_ACEOF || ac_write_fail=1
ac_cs_config="`$as_echo "$ac_configure_args" | sed 's/^ //; s/[\\""\`\$]/\\\\&/g'`"
ac_cs_version="\\
-gobject-introspection config.status 1.54.1
+gobject-introspection config.status 1.55.0
configured by $0, generated by GNU Autoconf 2.69,
with options \\"\$ac_cs_config\\"
dnl the gi version number
m4_define(gi_major_version, 1)
-m4_define(gi_minor_version, 54)
-m4_define(gi_micro_version, 1)
+m4_define(gi_minor_version, 55)
+m4_define(gi_micro_version, 0)
m4_define(gi_version, gi_major_version.gi_minor_version.gi_micro_version)
AC_PREREQ([2.63])
AC_SUBST(GIR_DIR)
AC_DEFINE_UNQUOTED(GIR_DIR, "$GIR_DIR", [Director prefix for gir installation])
-PKG_CHECK_MODULES(GLIB, [glib-2.0 >= 2.54.0])
+PKG_CHECK_MODULES(GLIB, [glib-2.0 >= 2.55.0])
PKG_CHECK_MODULES(GOBJECT, [gobject-2.0])
PKG_CHECK_MODULES(GMODULE, [gmodule-2.0])
@SET_MAKE@
# -*- mode: makefile -*-
+#
+# gtk-doc.make - make rules for gtk-doc
+# Copyright (C) 2003 James Henstridge
+# 2004-2007 Damon Chaplin
+# 2007-2017 Stefan Sauer
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
####################################
# Everything below here is generic #
<p>Obtain the option group for girepository, it's used
by the dumper and for programs that wants to provide
introspection information</p>
-<p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p>
<div class="refsect3">
<a name="g-irepository-get-option-group.returns"></a><h4>Returns</h4>
<p>the option group. </p>
<a name="gi-GIArgInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIArgInfo"></a><h3>GIArgInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIArgInfo;
+</pre>
<p>Represents an argument.</p>
</div>
<hr>
<a name="gi-GICallableInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GICallableInfo"></a><h3>GICallableInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GICallableInfo;
+</pre>
<p>Represents a callable, either <a class="link" href="gi-GIFunctionInfo.html#GIFunctionInfo" title="GIFunctionInfo"><span class="type">GIFunctionInfo</span></a>, <a class="link" href="gi-GICallbackInfo.html#GICallbackInfo" title="GICallbackInfo"><span class="type">GICallbackInfo</span></a> or
<a class="link" href="gi-GIVFuncInfo.html#GIVFuncInfo" title="GIVFuncInfo"><span class="type">GIVFuncInfo</span></a>.</p>
</div>
<a name="gi-GICallbackInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GICallbackInfo"></a><h3>GICallbackInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GICallbackInfo;
+</pre>
<p>Represents a callback, eg arguments and return value.</p>
</div>
</div>
<a name="gi-GIConstantInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIConstantInfo"></a><h3>GIConstantInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIConstantInfo;
+</pre>
<p>Represents a constant.</p>
</div>
</div>
<a name="gi-GIEnumInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIEnumInfo"></a><h3>GIEnumInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIEnumInfo;
+</pre>
<p>Represents an enum or a flag.</p>
</div>
</div>
<a name="gi-GIFieldInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIFieldInfo"></a><h3>GIFieldInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIFieldInfo;
+</pre>
<p>Represents a field of a <a class="link" href="gi-GIStructInfo.html#GIStructInfo" title="GIStructInfo"><span class="type">GIStructInfo</span></a> or a <a class="link" href="gi-GIUnionInfo.html#GIUnionInfo" title="GIUnionInfo"><span class="type">GIUnionInfo</span></a>.</p>
</div>
<hr>
<a name="gi-GIFunctionInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIFunctionInfo"></a><h3>GIFunctionInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIFunctionInfo;
+</pre>
<p>Represents a function, eg arguments and return value.</p>
</div>
<hr>
<a name="gi-GIInterfaceInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIInterfaceInfo"></a><h3>GIInterfaceInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIInterfaceInfo;
+</pre>
<p>Represents an interface.</p>
</div>
</div>
<a name="gi-GIObjectInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIObjectInfo"></a><h3>GIObjectInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIObjectInfo;
+</pre>
<p>Represents an object.</p>
</div>
</div>
<a name="gi-GIPropertyInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIPropertyInfo"></a><h3>GIPropertyInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIPropertyInfo;
+</pre>
<p>Represents a property of a <a class="link" href="gi-GIObjectInfo.html#GIObjectInfo" title="GIObjectInfo"><span class="type">GIObjectInfo</span></a> or a <a class="link" href="gi-GIInterfaceInfo.html#GIInterfaceInfo" title="GIInterfaceInfo"><span class="type">GIInterfaceInfo</span></a>.</p>
</div>
</div>
<a name="gi-GIRegisteredTypeInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIRegisteredTypeInfo"></a><h3>GIRegisteredTypeInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIRegisteredTypeInfo;
+</pre>
<p>Represent a registered type.</p>
</div>
</div>
<a name="gi-GISignalInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GISignalInfo"></a><h3>GISignalInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GISignalInfo;
+</pre>
<p>Represents a signal.</p>
</div>
</div>
<a name="gi-GIStructInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIStructInfo"></a><h3>GIStructInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIStructInfo;
+</pre>
<p>Represents a struct.</p>
</div>
</div>
<a name="gi-GITypeInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GITypeInfo"></a><h3>GITypeInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GITypeInfo;
+</pre>
<p>Represents type information, direction, transfer etc.</p>
</div>
</div>
<a name="gi-GIUnionInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIUnionInfo"></a><h3>GIUnionInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIUnionInfo;
+</pre>
<p>Represents a union.</p>
</div>
</div>
<a name="gi-GIVFuncInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIVFuncInfo"></a><h3>GIVFuncInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIVFuncInfo;
+</pre>
<p>Represents a virtual function.</p>
</div>
<hr>
<a name="gi-GIValueInfo.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="GIValueInfo"></a><h3>GIValueInfo</h3>
+<pre class="programlisting">typedef GIBaseInfo GIValueInfo;
+</pre>
<p>Represents a enum value of a <a class="link" href="gi-GIEnumInfo.html#GIEnumInfo" title="GIEnumInfo"><span class="type">GIEnumInfo</span></a>.</p>
</div>
</div>
<hr>
<div class="refsect2">
<a name="GIFFIReturnValue"></a><h3>GIFFIReturnValue</h3>
+<pre class="programlisting">typedef GIArgument GIFFIReturnValue;
+</pre>
<p>TODO</p>
</div>
</div>
<div>
<div><table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="0"><tr><th valign="middle"><p class="title">GObject Introspection Reference Manual</p></th></tr></table></div>
<div><p class="releaseinfo">
- This document is for GObject Introspection version 1.54.1
+ This document is for GObject Introspection version 1.55.0
.
The latest version of this documentation can be found on-line at
<a class="ulink" href="http://developer.gnome.org/gi/unstable/" target="_top">http://developer.gnome.org/gi/unstable/</a>.
* @object_proxy: The #GDBusObjectProxy on which an interface has properties that are changing.
* @interface_proxy: The #GDBusProxy that has properties that are changing.
* @changed_properties: A #GVariant containing the properties that changed.
- * @invalidated_properties: A %NULL terminated array of properties that was invalidated.
+ * @invalidated_properties: (array zero-terminated=1) (element-type utf8): A %NULL terminated
+ * array of properties that were invalidated.
*
* Emitted when one or more D-Bus properties on proxy changes. The
* local cache has already been updated when this signal fires. Note
*
* The certificate database to use when verifying this TLS connection.
* If no certificate database is set, then the default database will be
- * used. See g_dtls_backend_get_default_database().
+ * used. See g_tls_backend_get_default_database().
*
* Since: 2.48
*/
/**
+ * GListModelInterface::get_item:
+ * @list: a #GListModel
+ * @position: the position of the item to fetch
+ *
+ * Get the item at @position. If @position is greater than the number of
+ * items in @list, %NULL is returned.
+ *
+ * %NULL is never returned for an index that is smaller than the length
+ * of the list. See g_list_model_get_n_items().
+ *
+ * Returns: (type GObject) (transfer full) (nullable): the object at @position.
+ * Since: 2.44
+ */
+
+
+/**
* GListStore:
*
* #GListStore is an opaque data structure and can only be accessed
* GMount::pre-unmount:
* @mount: the object on which the signal is emitted
*
- * This signal is emitted when the #GMount is about to be
+ * This signal may be emitted when the #GMount is about to be
* unmounted.
*
+ * This signal depends on the backend and is only emitted if
+ * GIO was used to unmount.
+ *
* Since: 2.22
*/
/**
- * GSettings:context:
+ * GSettings:backend:
*
* The name of the context that the settings are stored in.
*/
* @volume_monitor: The volume monitor emitting the signal.
* @mount: a #GMount that is being unmounted.
*
- * Emitted when a mount is about to be removed.
+ * May be emitted when a mount is about to be removed.
+ *
+ * This signal depends on the backend and is only emitted if
+ * GIO was used to unmount.
*/
* which are chained together by a #GAsyncReadyCallback. To begin
* an asynchronous operation, provide a #GAsyncReadyCallback to the
* asynchronous function. This callback will be triggered when the
- * operation has completed, and will be passed a #GAsyncResult instance
- * filled with the details of the operation's success or failure, the
- * object the asynchronous function was started for and any error codes
- * returned. The asynchronous callback function is then expected to call
- * the corresponding "_finish()" function, passing the object the
- * function was called for, the #GAsyncResult instance, and (optionally)
- * an @error to grab any error conditions that may have occurred.
+ * operation has completed, and must be run in a later iteration of
+ * the [thread-default main context][g-main-context-push-thread-default]
+ * from where the operation was initiated. It will be passed a
+ * #GAsyncResult instance filled with the details of the operation's
+ * success or failure, the object the asynchronous function was
+ * started for and any error codes returned. The asynchronous callback
+ * function is then expected to call the corresponding "_finish()"
+ * function, passing the object the function was called for, the
+ * #GAsyncResult instance, and (optionally) an @error to grab any
+ * error conditions that may have occurred.
*
* The "_finish()" function for an operation takes the generic result
* (of type #GAsyncResult) and returns the specific result that the
* - g_file_new_for_commandline_arg() for a command line argument.
* - g_file_new_tmp() to create a temporary file from a template.
* - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
+ * - g_file_new_build_filename() to create a file from path elements.
*
* One way to think of a #GFile is as an abstraction of a pathname. For
* normal files the system pathname is what is stored internally, but as
* g_mount_unmount_with_operation() with (at least) the #GMount instance and a
* #GAsyncReadyCallback. The callback will be fired when the
* operation has resolved (either with success or failure), and a
- * #GAsyncReady structure will be passed to the callback. That
+ * #GAsyncResult structure will be passed to the callback. That
* callback should then call g_mount_unmount_with_operation_finish() with the #GMount
- * and the #GAsyncReady data to see if the operation was completed
+ * and the #GAsyncResult data to see if the operation was completed
* successfully. If an @error is present when g_mount_unmount_with_operation_finish()
* is called, then it will be filled with any error information.
*/
* implementations must carefully adhere to the expectations of
* callers that are documented on each of the interface methods.
*
- * Some of the GSettingsBackend functions accept or return a #GTree.
+ * Some of the #GSettingsBackend functions accept or return a #GTree.
* These trees always have strings as keys and #GVariant as values.
* g_settings_backend_create_tree() is a convenience function to create
* suitable trees.
*
- * The GSettingsBackend API is exported to allow third-party
+ * The #GSettingsBackend API is exported to allow third-party
* implementations, but does not carry the same stability guarantees
* as the public GIO API. For this reason, you have to define the
* C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
* ...
*
* plugin->schema_source =
- * g_settings_new_schema_source_from_directory (dir,
+ * g_settings_schema_source_new_from_directory (dir,
* g_settings_schema_source_get_default (), FALSE, NULL);
*
* ...
* from the point where it is called. g_simple_async_result_complete_in_idle()
* will finish it from an idle handler in the
* [thread-default main context][g-main-context-push-thread-default]
- * . g_simple_async_result_run_in_thread() will run the
- * job in a separate thread and then deliver the result to the
- * thread-default main context.
+ * where the #GSimpleAsyncResult was created.
+ * g_simple_async_result_run_in_thread() will run the job in a
+ * separate thread and then use
+ * g_simple_async_result_complete_in_idle() to deliver the result.
*
* To set the results of an asynchronous function,
* g_simple_async_result_set_op_res_gpointer(),
* Eventually, you will call a method such as
* g_task_return_pointer() or g_task_return_error(), which will
* save the value you give it and then invoke the task's callback
- * function (waiting until the next iteration of the main
- * loop first, if necessary). The caller will pass the #GTask back
- * to the operation's finish function (as a #GAsyncResult), and
- * you can use g_task_propagate_pointer() or the like to extract
- * the return value.
+ * function in the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * where it was created (waiting until the next iteration of the main
+ * loop first, if necessary). The caller will pass the #GTask back to
+ * the operation's finish function (as a #GAsyncResult), and you can
+ * can use g_task_propagate_pointer() or the like to extract the
+ * return value.
*
* Here is an example for using GTask as a GAsyncResult:
* |[<!-- language="C" -->
* ## Asynchronous operations from synchronous ones
*
* You can use g_task_run_in_thread() to turn a synchronous
- * operation into an asynchronous one, by running it in a thread
- * which will then dispatch the result back to the caller's
- * #GMainContext when it completes.
+ * operation into an asynchronous one, by running it in a thread.
+ * When it completes, the result will be dispatched to the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * where the #GTask was created.
*
* Running a task in a thread:
* |[<!-- language="C" -->
* whether the task's callback can be invoked directly, or
* if it needs to be sent to another #GMainContext, or delayed
* until the next iteration of the current #GMainContext.)
- * - The "finish" functions for #GTask-based operations are generally
+ * - The "finish" functions for #GTask based operations are generally
* much simpler than #GSimpleAsyncResult ones, normally consisting
* of only a single call to g_task_propagate_pointer() or the like.
* Since g_task_propagate_pointer() "steals" the return value from
/**
* g_app_info_create_from_commandline:
- * @commandline: the commandline to use
+ * @commandline: (type filename): the commandline to use
* @application_name: (nullable): the application name, or %NULL to use @commandline
* @flags: flags that can specify details of the created #GAppInfo
* @error: a #GError location to store the error occurring, %NULL to ignore.
*
* Checks if two #GAppInfos are equal.
*
- * Note that the check <em>may not</em> compare each individual field, and
- * only does an identity check. In case detecting changes in the contents
- * is needed, program code must additionally compare relevant fields.
+ * Note that the check <emphasis>may not</emphasis> compare each individual
+ * field, and only does an identity check. In case detecting changes in the
+ * contents is needed, program code must additionally compare relevant fields.
*
* Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
*/
* g_app_info_launch:
* @appinfo: a #GAppInfo
* @files: (nullable) (element-type GFile): a #GList of #GFile objects
- * @launch_context: (nullable): a #GAppLaunchContext or %NULL
+ * @context: (nullable): a #GAppLaunchContext or %NULL
* @error: a #GError
*
* Launches the application. Passes @files to the launched application
- * as arguments, using the optional @launch_context to get information
+ * as arguments, using the optional @context to get information
* about the details of the launcher (like what screen it is on).
* On error, @error will be set accordingly.
*
* process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
* should it be inherited by further processes. The `DISPLAY` and
* `DESKTOP_STARTUP_ID` environment variables are also set, based
- * on information provided in @launch_context.
+ * on information provided in @context.
*
* Returns: %TRUE on successful launch, %FALSE otherwise.
*/
/**
* g_app_info_launch_default_for_uri:
* @uri: the uri to show
- * @launch_context: (nullable): an optional #GAppLaunchContext
+ * @context: (nullable): an optional #GAppLaunchContext
* @error: (nullable): return location for an error, or %NULL
*
* Utility function that launches the default application
* g_app_info_launch_default_for_uri_async:
* @uri: the uri to show
* @context: (nullable): an optional #GAppLaunchContext
- * cancellable: (nullable): a #GCancellable
+ * @cancellable: (nullable): a #GCancellable
* @callback: (nullable): a #GASyncReadyCallback to call when the request is done
* @user_data: (nullable): data to pass to @callback
*
* g_app_info_launch_uris:
* @appinfo: a #GAppInfo
* @uris: (nullable) (element-type utf8): a #GList containing URIs to launch.
- * @launch_context: (nullable): a #GAppLaunchContext or %NULL
+ * @context: (nullable): a #GAppLaunchContext or %NULL
* @error: a #GError
*
* Launches the application. This passes the @uris to the launched application
- * as arguments, using the optional @launch_context to get information
+ * as arguments, using the optional @context to get information
* about the details of the launcher (like what screen it is on).
* On error, @error will be set accordingly.
*
* This is a %NULL-terminated array of strings, where each string has
* the form `KEY=VALUE`.
*
- * Returns: (array zero-terminated=1) (transfer full): the
- * child's environment
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ * the child's environment
* Since: 2.32
*/
/**
* g_app_launch_context_setenv:
* @context: a #GAppLaunchContext
- * @variable: the environment variable to set
- * @value: the value for to set the variable to.
+ * @variable: (type filename): the environment variable to set
+ * @value: (type filename): the value for to set the variable to.
*
* Arranges for @variable to be set to @value in the child's
* environment when @context is used to launch an application.
/**
* g_app_launch_context_unsetenv:
* @context: a #GAppLaunchContext
- * @variable: the environment variable to remove
+ * @variable: (type filename): the environment variable to remove
*
* Arranges for @variable to be unset in the child's environment
* when @context is used to launch an application.
/**
* g_application_command_line_create_file_for_arg:
* @cmdline: a #GApplicationCommandLine
- * @arg: an argument from @cmdline
+ * @arg: (type filename): an argument from @cmdline
*
* Creates a #GFile corresponding to a filename that was given as part
* of the invocation of @cmdline.
* The return value is %NULL-terminated and should be freed using
* g_strfreev().
*
- * Returns: (array length=argc) (transfer full): the string array
- * containing the arguments (the argv)
+ * Returns: (array length=argc) (element-type filename) (transfer full):
+ * the string array containing the arguments (the argv)
* Since: 2.28
*/
* See g_application_command_line_getenv() if you are only interested
* in the value of a single environment variable.
*
- * Returns: (array zero-terminated=1) (transfer none): the environment
- * strings, or %NULL if they were not sent
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ * the environment strings, or %NULL if they were not sent
* Since: 2.28
*/
/**
* g_application_command_line_getenv:
* @cmdline: a #GApplicationCommandLine
- * @name: the environment variable to get
+ * @name: (type filename): the environment variable to get
*
* Gets the value of a particular environment variable of the command
* line invocation, as would be returned by g_getenv(). The strings may
* calling only the 'shutdown' function before doing so.
*
* The hold count is ignored.
+ * Take care if your code has called g_application_hold() on the application and
+ * is therefore still expecting it to exist.
+ * (Note that you may have called g_application_hold() indirectly, for example
+ * through gtk_application_add_window().)
*
* The result of calling g_application_run() again after it returns is
* unspecified.
* g_application_run:
* @application: a #GApplication
* @argc: the argc from main() (or 0 if @argv is %NULL)
- * @argv: (array length=argc) (nullable): the argv from main(), or %NULL
+ * @argv: (array length=argc) (element-type filename) (nullable):
+ * the argv from main(), or %NULL
*
* Runs the application.
*
*
* Gets the source object from a #GAsyncResult.
*
- * Returns: (transfer full): a new reference to the source object for the @res,
- * or %NULL if there is none.
+ * Returns: (transfer full) (nullable): a new reference to the source
+ * object for the @res, or %NULL if there is none.
*/
*
* Finishes an asynchronous read.
*
- * Returns: a #gssize of the read stream, or %-1 on an error.
+ * Returns: a #gssize of the read stream, or `-1` on an error.
*/
/**
* g_cancellable_disconnect:
* @cancellable: (nullable): A #GCancellable or %NULL.
- * @handler_id: Handler id of the handler to be disconnected, or %0.
+ * @handler_id: Handler id of the handler to be disconnected, or `0`.
*
* Disconnects a handler from a cancellable instance similar to
* g_signal_handler_disconnect(). Additionally, in the event that a
* signal handler is removed. See #GCancellable::cancelled for
* details on how to use this.
*
- * If @cancellable is %NULL or @handler_id is %0 this function does
+ * If @cancellable is %NULL or @handler_id is `0` this function does
* nothing.
*
* Since: 2.22
/**
* g_dbus_action_group_get:
* @connection: A #GDBusConnection
- * @bus_name: the bus name which exports the action group
+ * @bus_name: (nullable): the bus name which exports the action
+ * group or %NULL if @connection is not a message bus connection
* @object_path: the object path at which the action group is exported
*
* Obtains a #GDBusActionGroup for the action group which is exported at
* Escape @string so it can appear in a D-Bus address as the value
* part of a key-value pair.
*
- * For instance, if @string is "/run/bus-for-:0",
- * this function would return "/run/bus-for-%3A0",
+ * For instance, if @string is `/run/bus-for-:0`,
+ * this function would return `/run/bus-for-%3A0`,
* which could be used in a D-Bus address like
- * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
+ * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`.
*
* Returns: (transfer full): a copy of @string with all
* non-optionally-escaped bytes escaped
* g_dbus_error_register_error_domain:
* @error_domain_quark_name: The error domain name.
* @quark_volatile: A pointer where to store the #GQuark.
- * @entries: A pointer to @num_entries #GDBusErrorEntry struct items.
+ * @entries: (array length=num_entries): A pointer to @num_entries #GDBusErrorEntry struct items.
* @num_entries: Number of items to register.
*
* Helper function for associating a #GError error domain with D-Bus error names.
/**
* g_dbus_menu_model_get:
* @connection: a #GDBusConnection
- * @bus_name: the bus name which exports the menu model
+ * @bus_name: (nullable): the bus name which exports the menu model
+ * or %NULL if @connection is not a message bus connection
* @object_path: the object path at which the menu model is exported
*
* Obtains a #GDBusMenuModel for the menu model which is exported
* @uris: (element-type utf8): List of URIs
* @launch_context: (nullable): a #GAppLaunchContext
* @spawn_flags: #GSpawnFlags, used for each process
- * @user_setup: (scope call) (nullable): a #GSpawnChildSetupFunc, used once
+ * @user_setup: (scope async) (nullable): a #GSpawnChildSetupFunc, used once
* for each process.
* @user_setup_data: (closure user_setup) (nullable): User data for @user_setup
* @pid_callback: (scope call) (nullable): Callback for child processes
*
* Sets the certificate database that is used to verify peer certificates.
* This is set to the default database by default. See
- * g_dtls_backend_get_default_database(). If set to %NULL, then
+ * g_tls_backend_get_default_database(). If set to %NULL, then
* peer certificate validation will always set the
* %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
* #GDtlsConnection::accept-certificate will always be emitted on
/**
+ * g_file_load_bytes:
+ * @file: a #GFile
+ * @cancellable: (nullable): a #GCancellable or %NULL
+ * @etag_out: (out) (nullable) (optional): a location to place the current
+ * entity tag for the file, or %NULL if the entity tag is not needed
+ * @error: a location for a #GError or %NULL
+ *
+ * Loads the contents of @file and returns it as #GBytes.
+ *
+ * If @file is a resource:// based URI, the resulting bytes will reference the
+ * embedded resource instead of a copy. Otherwise, this is equivalent to calling
+ * g_file_load_contents() and g_bytes_new_take().
+ *
+ * For resources, @etag_out will be set to %NULL.
+ *
+ * The data contained in the resulting #GBytes is always zero-terminated, but
+ * this is not included in the #GBytes length. The resulting #GBytes should be
+ * freed with g_bytes_unref() when no longer in use.
+ *
+ * Returns: (transfer full): a #GBytes or %NULL and @error is set
+ * Since: 2.56
+ */
+
+
+/**
+ * g_file_load_bytes_async:
+ * @file: a #GFile
+ * @cancellable: (nullable): a #GCancellable or %NULL
+ * @callback: (scope async): a #GAsyncReadyCallback to call when the
+ * request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Asynchronously loads the contents of @file as #GBytes.
+ *
+ * If @file is a resource:// based URI, the resulting bytes will reference the
+ * embedded resource instead of a copy. Otherwise, this is equivalent to calling
+ * g_file_load_contents_async() and g_bytes_new_take().
+ *
+ * @callback should call g_file_load_bytes_finish() to get the result of this
+ * asynchronous operation.
+ *
+ * See g_file_load_bytes() for more information.
+ *
+ * Since: 2.56
+ */
+
+
+/**
+ * g_file_load_bytes_finish:
+ * @file: a #GFile
+ * @result: a #GAsyncResult provided to the callback
+ * @etag_out: (out) (nullable) (optional): a location to place the current
+ * entity tag for the file, or %NULL if the entity tag is not needed
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes an asynchronous request to g_file_load_bytes_async().
+ *
+ * For resources, @etag_out will be set to %NULL.
+ *
+ * The data contained in the resulting #GBytes is always zero-terminated, but
+ * this is not included in the #GBytes length. The resulting #GBytes should be
+ * freed with g_bytes_unref() when no longer in use.
+ *
+ * See g_file_load_bytes() for more information.
+ *
+ * Returns: (transfer full): a #GBytes or %NULL and @error is set
+ * Since: 2.56
+ */
+
+
+/**
* g_file_load_contents:
* @file: input #GFile
* @cancellable: optional #GCancellable object, %NULL to ignore
* g_file_load_partial_contents_async: (skip)
* @file: input #GFile
* @cancellable: optional #GCancellable object, %NULL to ignore
- * @read_more_callback: a #GFileReadMoreCallback to receive partial data
+ * @read_more_callback: (scope call) (closure user_data): a
+ * #GFileReadMoreCallback to receive partial data
* and to specify whether further data should be read
- * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @callback: (scope async) (closure user_data): a #GAsyncReadyCallback to call
+ * when the request is satisfied
* @user_data: the data to pass to the callback functions
*
* Reads the partial contents of a file. A #GFileReadMoreCallback should
/**
+ * g_file_new_build_filename:
+ * @first_element: (type filename): the first element in the path
+ * @...: remaining elements in path, terminated by %NULL
+ *
+ * Constructs a #GFile from a series of elements using the correct
+ * separator for filenames.
+ *
+ * Using this function is equivalent to calling g_build_filename(),
+ * followed by g_file_new_for_path() on the result.
+ *
+ * Returns: (transfer full): a new #GFile
+ * Since: 2.56
+ */
+
+
+/**
* g_file_new_for_commandline_arg:
- * @arg: a command line string
+ * @arg: (type filename): a command line string
*
* 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
/**
* g_file_new_for_commandline_arg_and_cwd:
- * @arg: a command line string
+ * @arg: (type filename): a command line string
* @cwd: (type filename): the current working directory of the commandline
*
* Creates a #GFile with the given argument from the command line.
*
* Sets an attribute in the file with attribute name @attribute to @value.
*
- * Some attributes can be unset by setting @attribute to
+ * Some attributes can be unset by setting @type to
* %G_FILE_ATTRIBUTE_TYPE_INVALID and @value_p to %NULL.
*
* If @cancellable is not %NULL, then the operation can be cancelled by
* %NULL is never returned for an index that is smaller than the length
* of the list. See g_list_model_get_n_items().
*
- * Returns: (transfer full) (nullable) (type GObject): the item at @position.
+ * Returns: (transfer full) (nullable): the item at @position.
* Since: 2.44
*/
/**
* g_output_stream_printf:
* @stream: a #GOutputStream.
- * @bytes_written: (out): location to store the number of bytes that was
+ * @bytes_written: (out) (optional): location to store the number of bytes that was
* written to the stream
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
/**
* g_output_stream_vprintf:
* @stream: a #GOutputStream.
- * @bytes_written: (out): location to store the number of bytes that was
+ * @bytes_written: (out) (optional): location to store the number of bytes that was
* written to the stream
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
* @stream: a #GOutputStream.
* @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
* @count: the number of bytes to write
- * @bytes_written: (out): location to store the number of bytes that was
+ * @bytes_written: (out) (optional): location to store the number of bytes that was
* written to the stream
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: location to store the error occurring, or %NULL to ignore
* g_output_stream_write_all_finish:
* @stream: a #GOutputStream
* @result: a #GAsyncResult
- * @bytes_written: (out): location to store the number of bytes that was written to the stream
+ * @bytes_written: (out) (optional): location to store the number of bytes that was written to the stream
* @error: a #GError location to store the error occurring, or %NULL to ignore.
*
* Finishes an asynchronous stream write operation started with
* If you want to use this resource in the global resource namespace you need
* to register it with g_resources_register().
*
+ * Note: @data must be backed by memory that is at least pointer aligned.
+ * Otherwise this function will internally create a copy of the memory since
+ * GLib 2.56, or in older versions fail and exit the process.
+ *
* Returns: (transfer full): a new #GResource, or %NULL on error
* Since: 2.32
*/
* g_seekable_can_truncate:
* @seekable: a #GSeekable.
*
- * Tests if the stream can be truncated.
+ * Tests if the length of the stream can be adjusted with
+ * g_seekable_truncate().
*
* Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
*/
/**
* g_seekable_truncate: (virtual truncate_fn)
* @seekable: a #GSeekable.
- * @offset: a #goffset.
+ * @offset: new length for @seekable, in bytes.
* @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
* @error: a #GError location to store the error occurring, or %NULL to
* ignore.
*
- * Truncates a stream with a given #offset.
+ * 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.
*
* If @cancellable is not %NULL, then the operation can be cancelled by
* triggering the cancellable object from another thread. If the operation
* a boolean property by that name). See g_settings_bind_writable()
* for more details about writable bindings.
*
- * Note that the lifecycle of the binding is tied to the object,
+ * Note that the lifecycle of the binding is tied to @object,
* and that you can have only one binding per object property.
* If you bind the same property twice on the same object, the second
* binding overrides the first one.
* The binding uses the provided mapping functions to map between
* settings and property values.
*
- * Note that the lifecycle of the binding is tied to the object,
+ * Note that the lifecycle of the binding is tied to @object,
* and that you can have only one binding per object property.
* If you bind the same property twice on the same object, the second
* binding overrides the first one.
* value as it passes from the setting to the object, i.e. @property
* will be set to %TRUE if the key is not writable.
*
- * Note that the lifecycle of the binding is tied to the object,
+ * Note that the lifecycle of the binding is tied to @object,
* and that you can have only one binding per object property.
* If you bind the same property twice on the same object, the second
* binding overrides the first one.
* lookups performed against the default source should probably be done
* recursively.
*
- * Returns: (transfer none): the default schema source
+ * Returns: (transfer none) (nullable): the default schema source
* Since: 2.32
*/
* @socket: a #GSocket.
* @error: #GError for error reporting, or %NULL to ignore.
*
- * Try to get the remove address of a connected socket. This is only
+ * Try to get the remote address of a connected socket. This is only
* useful for connection oriented sockets that have been connected.
*
* Returns: (transfer full): a #GSocketAddress or %NULL on error.
* in RFC 4604 is used. Note that on older platforms this may fail
* with a %G_IO_ERROR_NOT_SUPPORTED error.
*
+ * To bind to a given source-specific multicast address, use
+ * g_socket_join_multicast_group_ssm() instead.
+ *
* Returns: %TRUE on success, %FALSE on error.
* Since: 2.32
*/
/**
+ * g_socket_join_multicast_group_ssm:
+ * @socket: a #GSocket.
+ * @group: a #GInetAddress specifying the group address to join.
+ * @source_specific: (nullable): a #GInetAddress specifying the
+ * source-specific multicast address or %NULL to ignore.
+ * @iface: (nullable): Name of the interface to use, or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Registers @socket to receive multicast messages sent to @group.
+ * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
+ * been bound to an appropriate interface and port with
+ * g_socket_bind().
+ *
+ * If @iface is %NULL, the system will automatically pick an interface
+ * to bind to based on @group.
+ *
+ * If @source_specific is not %NULL, use source-specific multicast as
+ * defined in RFC 4604. Note that on older platforms this may fail
+ * with a %G_IO_ERROR_NOT_SUPPORTED error.
+ *
+ * Note that this function can be called multiple times for the same
+ * @group with different @source_specific in order to receive multicast
+ * packets from more than one source.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.56
+ */
+
+
+/**
* g_socket_leave_multicast_group:
* @socket: a #GSocket.
* @group: a #GInetAddress specifying the group address to leave.
* @socket remains bound to its address and port, and can still receive
* unicast messages after calling this.
*
+ * To unbind to a given source-specific multicast address, use
+ * g_socket_leave_multicast_group_ssm() instead.
+ *
* Returns: %TRUE on success, %FALSE on error.
* Since: 2.32
*/
/**
+ * g_socket_leave_multicast_group_ssm:
+ * @socket: a #GSocket.
+ * @group: a #GInetAddress specifying the group address to leave.
+ * @source_specific: (nullable): a #GInetAddress specifying the
+ * source-specific multicast address or %NULL to ignore.
+ * @iface: (nullable): Name of the interface to use, or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Removes @socket from the multicast group defined by @group, @iface,
+ * and @source_specific (which must all have the same values they had
+ * when you joined the group).
+ *
+ * @socket remains bound to its address and port, and can still receive
+ * unicast messages after calling this.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.56
+ */
+
+
+/**
* g_socket_listen:
* @socket: a #GSocket.
* @error: #GError for error reporting, or %NULL to ignore.
/**
* g_subprocess_launcher_getenv:
* @self: a #GSubprocess
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
*
* Returns the value of the environment variable @variable in the
* environment of processes launched from this launcher.
* On UNIX, the returned string can be an arbitrary byte string.
* On Windows, it will be UTF-8.
*
- * Returns: the value of the environment variable, %NULL if unset
+ * Returns: (type filename): the value of the environment variable,
+ * %NULL if unset
* Since: 2.40
*/
/**
- * g_subprocess_launcher_set_child_setup:
+ * g_subprocess_launcher_set_child_setup: (skip)
* @self: a #GSubprocessLauncher
* @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
* @user_data: user data for @child_setup
/**
* g_subprocess_launcher_set_environ:
* @self: a #GSubprocess
- * @env: (array zero-terminated=1): the replacement environment
+ * @env: (array zero-terminated=1) (element-type filename) (transfer none):
+ * the replacement environment
*
* Replace the entire environment of processes launched from this
* launcher with the given 'environ' variable.
/**
* g_subprocess_launcher_setenv:
* @self: a #GSubprocess
- * @variable: the environment variable to set, must not contain '='
- * @value: the new value for the variable
+ * @variable: (type filename): the environment variable to set,
+ * must not contain '='
+ * @value: (type filename): the new value for the variable
* @overwrite: whether to change the variable if it already exists
*
* Sets the environment variable @variable in the environment of
/**
* g_subprocess_launcher_spawnv:
* @self: a #GSubprocessLauncher
- * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
+ * @argv: (array zero-terminated=1) (element-type filename): Command line arguments
* @error: Error
*
* Creates a #GSubprocess given a provided array of arguments.
/**
* g_subprocess_launcher_unsetenv:
* @self: a #GSubprocess
- * @variable: the environment variable to unset, must not contain '='
+ * @variable: (type filename): the environment variable to unset,
+ * must not contain '='
*
* Removes the environment variable @variable from the environment of
* processes launched from this launcher.
/**
* g_subprocess_newv: (rename-to g_subprocess_new)
- * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
+ * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess
* @flags: flags that define the behaviour of the subprocess
* @error: (nullable): return location for an error, or %NULL
*
* Gets the source object from @task. Like
* g_async_result_get_source_object(), but does not ref the object.
*
- * Returns: (transfer none) (type GObject): @task's source object, or %NULL
+ * Returns: (transfer none) (nullable) (type GObject): @task's source object, or %NULL
* Since: 2.36
*/
* Gets the #GType of @backend’s #GDtlsClientConnection implementation.
*
* Returns: the #GType of @backend’s #GDtlsClientConnection
- * implementation.
+ * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
* Since: 2.48
*/
* Gets the #GType of @backend’s #GDtlsServerConnection implementation.
*
* Returns: the #GType of @backend’s #GDtlsServerConnection
- * implementation.
+ * implementation, or %G_TYPE_INVALID if this backend doesn’t support DTLS.
* Since: 2.48
*/
* @error: a #GError pointer, or %NULL
*
* Finish an asynchronous lookup of a certificate by its handle. See
- * g_tls_database_lookup_certificate_handle() for more information.
+ * g_tls_database_lookup_certificate_by_handle() for more information.
*
* If the handle is no longer valid, or does not point to a certificate in
* this database, then %NULL will be returned.
* adding any missing certificates to the chain.
*
* @chain is a chain of #GTlsCertificate objects each pointing to the next
- * certificate in the chain by its %issuer property. The chain may initially
+ * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially
* consist of one or more certificates. After the verification process is
* complete, @chain may be modified by adding missing certificates, or removing
* extra certificates. If a certificate anchor was found, then it is added to
/**
* g_tls_password_set_value:
* @password: a #GTlsPassword object
- * @value: the new password value
+ * @value: (array length=length): the new password value
* @length: the length of the password, or -1
*
* Set the value for this password. The @value will be copied by the password
/**
* g_tls_password_set_value_full: (virtual set_value)
* @password: a #GTlsPassword object
- * @value: the value for the password
+ * @value: (array length=length): the value for the password
* @length: the length of the password, or -1
* @destroy: (nullable): a function to use to free the password.
*
/**
+ * g_unix_is_system_device_path:
+ * @device_path: a device path, e.g. `/dev/loop0` or `nfsd`
+ *
+ * Determines if @device_path is considered a block device path which is only
+ * used in implementation of the OS. This is primarily used for hiding
+ * mounted volumes that are intended as APIs for programs to read, and system
+ * administrators at a shell; rather than something that should, for example,
+ * appear in a GUI. For example, the Linux `/proc` filesystem.
+ *
+ * The list of device paths considered ‘system’ ones may change over time.
+ *
+ * Returns: %TRUE if @device_path is considered an implementation detail of
+ * the OS.
+ * Since: 2.56
+ */
+
+
+/**
+ * g_unix_is_system_fs_type:
+ * @fs_type: a file system type, e.g. `procfs` or `tmpfs`
+ *
+ * Determines if @fs_type is considered a type of file system which is only
+ * used in implementation of the OS. This is primarily used for hiding
+ * mounted volumes that are intended as APIs for programs to read, and system
+ * administrators at a shell; rather than something that should, for example,
+ * appear in a GUI. For example, the Linux `/proc` filesystem.
+ *
+ * The list of file system types considered ‘system’ ones may change over time.
+ *
+ * Returns: %TRUE if @fs_type is considered an implementation detail of the OS.
+ * Since: 2.56
+ */
+
+
+/**
* g_unix_mount_at:
* @mount_path: (type filename): path for a possible unix mount.
* @time_read: (out) (optional): guint64 to contain a timestamp.
* g_unix_mount_is_system_internal:
* @mount_entry: a #GUnixMount.
*
- * Checks if a unix mount is a system path.
+ * Checks if a Unix mount is a system mount. This is the Boolean OR of
+ * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and
+ * g_unix_is_mount_path_system_internal() on @mount_entry’s properties.
+ *
+ * The definition of what a ‘system’ mount entry is may change over time as new
+ * file system types and device paths are ignored.
*
* Returns: %TRUE if the unix mount is for a system path.
*/
* then the expression
* |[<!-- language="C" -->
* (g_file_has_prefix (volume_activation_root, mount_root) ||
- * g_file_equal (volume_activation_root, mount_root))
+ * g_file_equal (volume_activation_root, mount_root))
* ]|
* will always be %TRUE.
*
* GDataForeachFunc:
* @key_id: the #GQuark id to identifying the data element.
* @data: the data element.
- * @user_data: user data passed to g_dataset_foreach().
+ * @user_data: (closure): user data passed to g_dataset_foreach().
*
* Specifies the type of function passed to g_dataset_foreach(). It is
* called with each #GQuark id and associated data element, together
/**
* GDuplicateFunc:
* @data: the data to duplicate
- * @user_data: user data that was specified in g_datalist_id_dup_data()
+ * @user_data: (closure): user data that was specified in
+ * g_datalist_id_dup_data()
*
* The type of functions that are used to 'duplicate' an object.
* What this means depends on the context, it could just be
* suffixes. IEC units should only be used for reporting things with
* a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
* Network and storage sizes should be reported in the normal SI units.
+ * @G_FORMAT_SIZE_BITS: set the size as a quantity in bits, rather than
+ * bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.
*
* Flags to modify the format of the string returned by g_format_size_full().
*/
*
* Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
* which is deprecated. g_test_trap_subprocess() uses
- * #GTestTrapSubprocessFlags.
+ * #GTestSubprocessFlags.
*/
/**
* G_GNUC_CHECK_VERSION:
+ * @major: major version to check against
+ * @minor: minor version to check against
*
* Expands to a a check for a compiler with __GNUC__ defined and a version
* greater than or equal to the major and minor numbers provided. For example,
/**
* G_LOG_DOMAIN:
*
- * Defines the log domain.
+ * Defines the log domain. See [Log Domains](#log-domains).
*
* Libraries should define this so that any messages
* which they log can be differentiated from messages from other
* libraries and application code. But be careful not to define
* it in any public header files.
*
- * For example, GTK+ uses this in its Makefile.am:
+ * 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`.
+ *
+ * If undefined, it defaults to the default %NULL (or `""`) log domain; this is
+ * not advisable, as it cannot be filtered against using the `G_MESSAGES_DEBUG`
+ * environment variable.
+ *
+ * For example, GTK+ uses this in its `Makefile.am`:
* |[
* AM_CPPFLAGS = -DG_LOG_DOMAIN=\"Gtk\"
* ]|
*
- * Applications can choose to leave it as the default %NULL (or "")
+ * Applications can choose to leave it as the default %NULL (or `""`)
* domain. However, defining the domain offers the same advantages as
* above.
*/
* A macro to assist with the static initialisation of a #GPrivate.
*
* This macro is useful for the case that a #GDestroyNotify function
- * should be associated the key. This is needed when the key will be
+ * should be associated with the key. This is needed when the key will be
* used to point at memory that should be deallocated when the thread
* exits.
*
* ## 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.
*
* @title: File Utilities
* @short_description: various file-related functions
*
+ * 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
* 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`
* 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,
+ * \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,
* 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);
+ * ]|
*/
* * Color output needed to be supported on the terminal, to make reading
* through logs easier.
*
- * ## Using Structured Logging
+ * ## 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
* 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}
*
* 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.
* 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 ## {#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
* so that developers can re-use the same debugging techniques and tools across
* projects.
*
- * ## Testing for Messages
+ * ## 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
* duplicating, and manipulating strings.
*
* Note that the functions g_printf(), g_fprintf(), g_sprintf(),
- * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
+ * 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
* variants over plain g_assert() is that the assertion messages can be
* more elaborate, and include the values of the compared entities.
*
- * GLib ships with two utilities called [gtester][gtester] and
- * [gtester-report][gtester-report] to facilitate running tests and producing
- * nicely formatted test reports.
- *
* A full example of creating a test suite with two tests using fixtures:
* |[<!-- language="C" -->
* #include <glib.h>
* 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://git.gnome.org/browse/glib/tree/glib-tap.mk)
+ * - [tap-test](https://git.gnome.org/browse/glib/tree/tap-test)
+ * - [tap-driver.sh](https://git.gnome.org/browse/glib/tree/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://git.gnome.org/browse/glib/tree/glib.mk) Automake
+ * template provided by GLib.
*/
* and portability
*
* GLib defines a number of commonly used types, which can be divided
- * into 4 groups:
+ * into several groups:
* - New types which are not part of standard C (but are defined in
- * various C standard library header files) - #gboolean, #gsize,
- * #gssize, #goffset, #gintptr, #guintptr.
+ * 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,
+ * 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,
+ * 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
/**
- * g_base64_decode_step:
+ * g_base64_decode_step: (skip)
* @in: (array length=len) (element-type guint8): binary input data
* @len: max length of @in data to decode
- * @out: (out) (array) (element-type guint8): output buffer
+ * @out: (out caller-allocates) (array) (element-type guint8): output buffer
* @state: (inout): Saved state between steps, initialize to 0
* @save: (inout): Saved state between steps, initialize to 0
*
/**
- * g_bookmark_file_new:
+ * g_bookmark_file_new: (constructor)
*
* Creates a new empty #GBookmarkFile object.
*
/**
+ * g_build_filename_valist:
+ * @first_element: (type filename): the first element in the path
+ * @args: va_list of remaining elements in path
+ *
+ * Behaves exactly like g_build_filename(), but takes the path elements
+ * as a va_list. This function is mainly meant for language bindings.
+ *
+ * Returns: (type filename): a newly-allocated string that must be freed
+ * with g_free().
+ * Since: 2.56
+ */
+
+
+/**
* g_build_filenamev:
* @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
* array of strings containing the path elements.
/**
* g_bytes_new_static: (skip)
* @data: (transfer full) (array length=size) (element-type guint8) (nullable):
- * the data to be used for the bytes
+ * the data to be used for the bytes
* @size: the size of @data
*
* Creates a new #GBytes from static data.
/**
* g_bytes_new_take:
* @data: (transfer full) (array length=size) (element-type guint8) (nullable):
- * the data to be used for the bytes
+ * the data to be used for the bytes
* @size: the size of @data
*
* Creates a new #GBytes from @data.
/**
* g_bytes_new_with_free_func: (skip)
* @data: (array length=size) (element-type guint8) (nullable):
- * the data to be used for the bytes
+ * the data to be used for the bytes
* @size: the size of @data
* @free_func: the function to call to release the data
* @user_data: data to pass to @free_func
* g_spawn_close_pid() in the callback function for the source.
*
* GLib supports only a single callback per process id.
+ * On POSIX platforms, the same restrictions mentioned for
+ * g_child_watch_source_new() apply to this function.
*
* This internally creates a main loop source using
* g_child_watch_source_new() and attaches it to the main loop context
* in the callback function for the source.
*
* GLib supports only a single callback per process id.
+ * On POSIX platforms, the same restrictions mentioned for
+ * g_child_watch_source_new() apply to this function.
*
* This internally creates a main loop source using
* g_child_watch_source_new() and attaches it to the main loop context
* source is still active. Typically, you will want to call
* g_spawn_close_pid() in the callback function for the source.
*
- * Note further that using g_child_watch_source_new() is not
- * compatible with calling `waitpid` with a nonpositive first
- * argument in the application. Calling waitpid() for individual
- * pids will still work fine.
+ * On POSIX platforms, the following restrictions apply to this API
+ * due to limitations in POSIX process interfaces:
+ *
+ * * @pid must be a child of this process
+ * * @pid must be positive
+ * * the application must not call `waitpid` with a non-positive
+ * first argument, for instance in another thread
+ * * the application must not wait for @pid to exit by any other
+ * mechanism, including `waitpid(pid, ...)` or a second child-watch
+ * source for the same @pid
+ * * the application must not ignore SIGCHILD
+ *
+ * If any of those conditions are not met, this and related APIs will
+ * not work correctly. This can often be diagnosed via a GLib warning
+ * stating that `ECHILD` was received by `waitpid`.
*
- * Similarly, on POSIX platforms, the @pid passed to this function must
- * be greater than 0 (i.e. this function must wait for a specific child,
- * and cannot wait for one of many children by using a nonpositive argument).
+ * Calling `waitpid` for specific processes other than @pid remains a
+ * valid thing to do.
*
* Returns: the newly-created child watch source
* Since: 2.4
/**
+ * g_clear_handle_id: (skip)
+ * @tag_ptr: (not nullable): a pointer to the handler ID
+ * @clear_func: (not nullable): the function to call to clear the handler
+ *
+ * Clears a numeric handler, such as a #GSource ID.
+ *
+ * @tag_ptr must be a valid pointer to the variable holding the handler.
+ *
+ * If the ID is zero then this function does nothing.
+ * Otherwise, clear_func() is called with the ID as a parameter, and the tag is
+ * set to zero.
+ *
+ * A macro is also included that allows this function to be used without
+ * pointer casts.
+ *
+ * Since: 2.56
+ */
+
+
+/**
* g_clear_pointer: (skip)
* @pp: (not nullable): a pointer to a variable, struct member etc. holding a
* pointer
* @fallback: UTF-8 string to use in place of character not
* present in the target encoding. (The string must be
* representable in the target encoding).
- * If %NULL, characters not in the target encoding will
- * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
+ * If %NULL, characters not in the target encoding will
+ * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
* @bytes_read: 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
/**
- * g_convert_with_iconv:
+ * g_convert_with_iconv: (skip)
* @str: the string to convert
* @len: the length of the string in bytes, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
*
* You can also make critical warnings fatal at runtime by
* setting the `G_DEBUG` environment variable (see
- * [Running GLib Applications](glib-running.html)).
+ * [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ * G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
+ *
+ * The message should typically *not* be translated to the
+ * user's language.
*
* If g_log_default_handler() is used as the log handler function, a new-line
* character will automatically be appended to @..., and need not be entered
/**
- * g_datalist_clear:
+ * g_datalist_clear: (skip)
* @datalist: a datalist.
*
* Frees all the data elements of the datalist.
/**
* g_datalist_foreach:
* @datalist: a datalist.
- * @func: the function to call for each data element.
- * @user_data: user data to pass to the function.
+ * @func: (scope call): the function to call for each data element.
+ * @user_data: (closure): user data to pass to the function.
*
* Calls the given function for each data element of the datalist. The
* function is called with each data element's #GQuark id and data,
* function is NOT thread-safe. So unless @datalist can be protected
* from any modifications during invocation of this function, it should
* not be called.
+ *
+ * @func can make changes to @datalist, but the iteration will not
+ * reflect changes made during the g_datalist_foreach() call, other
+ * than skipping over elements that are removed.
*/
* Gets a data element, using its string identifier. This is slower than
* g_datalist_id_get_data() because it compares strings.
*
- * Returns: the data element, or %NULL if it is not found.
+ * Returns: (transfer none) (nullable): the data element, or %NULL if it
+ * is not found.
*/
/**
- * g_datalist_id_dup_data:
+ * g_datalist_id_dup_data: (skip)
* @datalist: location of a datalist
* @key_id: the #GQuark identifying a data element
- * @dup_func: (nullable): function to duplicate the old value
- * @user_data: (nullable): passed as user_data to @dup_func
+ * @dup_func: (nullable) (scope call): function to duplicate the old value
+ * @user_data: (closure): passed as user_data to @dup_func
*
* This is a variant of g_datalist_id_get_data() which
* returns a 'duplicate' of the value. @dup_func defines the
* This function can be useful to avoid races when multiple
* threads are using the same datalist and the same key.
*
- * Returns: the result of calling @dup_func on the value
+ * Returns: (nullable): the result of calling @dup_func on the value
* associated with @key_id in @datalist, or %NULL if not set.
* If @dup_func is %NULL, the value is returned unmodified.
* Since: 2.34
*
* Retrieves the data element corresponding to @key_id.
*
- * Returns: the data element, or %NULL if it is not found.
+ * Returns: (transfer none) (nullable): the data element, or %NULL if
+ * it is not found.
*/
/**
- * g_datalist_id_remove_no_notify:
+ * g_datalist_id_remove_no_notify: (skip)
* @datalist: a datalist.
* @key_id: the #GQuark identifying a data element.
*
* Removes an element, without calling its destroy notification
* function.
*
- * Returns: the data previously stored at @key_id, or %NULL if none.
+ * Returns: (nullable): the data previously stored at @key_id,
+ * or %NULL if none.
*/
/**
- * g_datalist_id_replace_data:
+ * g_datalist_id_replace_data: (skip)
* @datalist: location of a datalist
* @key_id: the #GQuark identifying a data element
* @oldval: (nullable): the old value to compare against
* @newval: (nullable): the new value to replace it with
* @destroy: (nullable): destroy notify for the new value
- * @old_destroy: (nullable): destroy notify for the existing value
+ * @old_destroy: (out) (optional): destroy notify for the existing value
*
* Compares the member that is associated with @key_id in
* @datalist to @oldval, and if they are the same, replace
/**
- * g_datalist_id_set_data_full:
+ * g_datalist_id_set_data_full: (skip)
* @datalist: a datalist.
* @key_id: the #GQuark to identify the data element.
* @data: (nullable): the data element or %NULL to remove any previous element
* corresponding to @key_id.
- * @destroy_func: the function to call when the data element is
+ * @destroy_func: (nullable): the function to call when the data element is
* removed. This function will be called with the data
* element and can be used to free any memory allocated
* for it. If @data is %NULL, then @destroy_func must
/**
- * g_datalist_init:
+ * g_datalist_init: (skip)
* @datalist: a pointer to a pointer to a datalist.
*
* Resets the datalist to %NULL. It does not free any memory or call
/**
- * g_datalist_remove_no_notify:
+ * g_datalist_remove_no_notify: (skip)
* @dl: a datalist.
* @k: the string identifying the data element.
*
/**
- * g_datalist_set_data_full:
+ * g_datalist_set_data_full: (skip)
* @dl: a datalist.
* @k: the string to identify the data element.
* @d: (nullable): the data element, or %NULL to remove any previous element
* corresponding to @k.
- * @f: the function to call when the data element is removed. This
- * function will be called with the data element and can be used to
+ * @f: (nullable): the function to call when the data element is removed.
+ * This function will be called with the data element and can be used to
* free any memory allocated for it. If @d is %NULL, then @f must
* also be %NULL.
*
/**
* g_dataset_foreach:
* @dataset_location: (not nullable): the location identifying the dataset.
- * @func: the function to call for each data element.
- * @user_data: user data to pass to the function.
+ * @func: (scope call): the function to call for each data element.
+ * @user_data: (closure): user data to pass to the function.
*
* Calls the given function for each data element which is associated
* with the given location. Note that this function is NOT thread-safe.
- * So unless @datalist can be protected from any modifications during
- * invocation of this function, it should not be called.
+ * So unless @dataset_location can be protected from any modifications
+ * during invocation of this function, it should not be called.
+ *
+ * @func can make changes to the dataset, but the iteration will not
+ * reflect changes made during the g_dataset_foreach() call, other
+ * than skipping over elements that are removed.
*/
*
* Gets the data element corresponding to a string.
*
- * Returns: the data element corresponding to the string, or %NULL if
- * it is not found.
+ * Returns: (transfer none) (nullable): the data element corresponding to
+ * the string, or %NULL if it is not found.
*/
*
* Gets the data element corresponding to a #GQuark.
*
- * Returns: the data element corresponding to the #GQuark, or %NULL if
- * it is not found.
+ * Returns: (transfer none) (nullable): the data element corresponding to
+ * the #GQuark, or %NULL if it is not found.
*/
/**
- * g_dataset_id_remove_no_notify:
+ * g_dataset_id_remove_no_notify: (skip)
* @dataset_location: (not nullable): the location identifying the dataset.
* @key_id: the #GQuark ID identifying the data element.
*
* Removes an element, without calling its destroy notification
* function.
*
- * Returns: the data previously stored at @key_id, or %NULL if none.
+ * Returns: (nullable): the data previously stored at @key_id,
+ * or %NULL if none.
*/
/**
- * g_dataset_id_set_data_full:
+ * g_dataset_id_set_data_full: (skip)
* @dataset_location: (not nullable): the location identifying the dataset.
* @key_id: the #GQuark id to identify the data element.
* @data: the data element.
/**
- * g_dataset_remove_no_notify:
+ * g_dataset_remove_no_notify: (skip)
* @l: the location identifying the dataset.
* @k: the string identifying the data element.
*
/**
- * g_dataset_set_data_full:
+ * g_dataset_set_data_full: (skip)
* @l: the location identifying the dataset.
* @k: the string to identify the data element.
* @d: the data element.
/**
+ * g_date_copy:
+ * @date: a #GDate to copy
+ *
+ * Copies a GDate to a newly-allocated GDate. If the input was invalid
+ * (as determined by g_date_valid()), the invalid state will be copied
+ * as is into the new object.
+ *
+ * Returns: (transfer full): a newly-allocated #GDate initialized from @date
+ * Since: 2.56
+ */
+
+
+/**
* g_date_days_between:
* @date1: the first date
* @date2: the second date
/**
+ * g_date_time_new_from_iso8601:
+ * @text: an ISO 8601 formatted time string.
+ * @default_tz: (nullable): a #GTimeZone to use if the text doesn't contain a
+ * timezone, or %NULL.
+ *
+ * Creates a #GDateTime corresponding to the given
+ * [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601)
+ * @text. ISO 8601 strings of the form <date><sep><time><tz> are supported.
+ *
+ * <sep> is the separator and can be either 'T', 't' or ' '.
+ *
+ * <date> is in the form:
+ *
+ * - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24.
+ * - `YYYYMMDD` - Same as above without dividers.
+ * - `YYYY-DDD` - Ordinal day where DDD is from 001 to 366, e.g. 2016-237.
+ * - `YYYYDDD` - Same as above without dividers.
+ * - `YYYY-Www-D` - Week day where ww is from 01 to 52 and D from 1-7,
+ * e.g. 2016-W34-3.
+ * - `YYYYWwwD` - Same as above without dividers.
+ *
+ * <time> is in the form:
+ *
+ * - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123.
+ * - `hhmmss(.sss)` - Same as above without dividers.
+ *
+ * <tz> is an optional timezone suffix of the form:
+ *
+ * - `Z` - UTC.
+ * - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00.
+ * - `+hh` or `-hh` - Offset from UTC in hours, e.g. +12.
+ *
+ * If the timezone is not provided in @text it must be provided in @default_tz
+ * (this field is otherwise ignored).
+ *
+ * This call can fail (returning %NULL) if @text is not a valid ISO 8601
+ * formatted string.
+ *
+ * You should release the return value by calling g_date_time_unref()
+ * when you are done with it.
+ *
+ * Returns: (transfer full) (nullable): a new #GDateTime, or %NULL
+ * Since: 2.56
+ */
+
+
+/**
* g_date_time_new_from_timeval_local:
* @tv: a #GTimeVal
*
* @...: format string, followed by parameters to insert
* into the format string (as with printf())
*
- * A convenience function/macro to log a debug message.
+ * A convenience function/macro to log a debug message. The message should
+ * typically *not* be translated to the user's language.
*
* If g_log_default_handler() is used as the log handler function, a new-line
* character will automatically be appended to @..., and need not be entered
/**
* g_environ_getenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer none): an environment
- * list (eg, as returned from g_get_environ()), or %NULL
+ * @envp: (nullable) (array zero-terminated=1) (transfer none) (element-type filename):
+ * an environment list (eg, as returned from g_get_environ()), or %NULL
* for an empty environment list
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
*
* Returns the value of the environment variable @variable in the
* provided list @envp.
*
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: (type filename): the value of the environment variable, or %NULL if
* the environment variable is not set in @envp. The returned
* string is owned by @envp, and will be freed if @variable is
* set or unset again.
/**
* g_environ_setenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer full): an
- * environment list that can be freed using g_strfreev() (e.g., as
+ * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full):
+ * an environment list that can be freed using g_strfreev() (e.g., as
* returned from g_get_environ()), or %NULL for an empty
* environment list
- * @variable: the environment variable to set, must not contain '='
- * @value: the value for to set the variable to
+ * @variable: (type filename): the environment variable to set, must not
+ * contain '='
+ * @value: (type filename): the value for to set the variable to
* @overwrite: whether to change the variable if it already exists
*
* Sets the environment variable @variable in the provided list
* @envp to @value.
*
- * Returns: (array zero-terminated=1) (transfer full): the
- * updated environment list. Free it using g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ * the updated environment list. Free it using g_strfreev().
* Since: 2.32
*/
/**
* g_environ_unsetenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer full): an environment
- * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()),
- * or %NULL for an empty environment list
- * @variable: the environment variable to remove, must not contain '='
+ * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full):
+ * an environment list that can be freed using g_strfreev() (e.g., as
+ * returned from g_get_environ()), or %NULL for an empty environment list
+ * @variable: (type filename): the environment variable to remove, must not
+ * contain '='
*
* Removes the environment variable @variable from the provided
* environment @envp.
*
- * Returns: (array zero-terminated=1) (transfer full): the
- * updated environment list. Free it using g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ * the updated environment list. Free it using g_strfreev().
* Since: 2.32
*/
* @...: format string, followed by parameters to insert
* into the format string (as with printf())
*
- * A convenience function/macro to log an error message.
+ * A convenience function/macro to log an error message. The message should
+ * typically *not* be translated to the user's language.
*
* This is not intended for end user error reporting. Use of #GError is
* preferred for that instead, as it allows calling functions to perform actions
* An implementation of the standard fprintf() function which supports
* positional parameters, as specified in the Single Unix Specification.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* Returns: the number of bytes printed.
* Since: 2.2
*/
* The return value is freshly allocated and it should be freed with
* g_strfreev() when it is no longer needed.
*
- * Returns: (array zero-terminated=1) (transfer full): the list of
- * environment variables
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ * the list of environment variables
* Since: 2.28
*/
* name can be determined, a default fixed string "localhost" is
* returned.
*
+ * The encoding of the returned string is UTF-8.
+ *
* Returns: the host name of the machine.
* Since: 2.8
*/
/**
* g_getenv:
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
*
* Returns the value of an environment variable.
*
* On Windows, in case the environment variable's value contains
* references to other environment variables, they are expanded.
*
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: (type filename): the value of the environment variable, or %NULL if
* the environment variable is not found. The returned string
* may be overwritten by the next call to g_getenv(), g_setenv()
* or g_unsetenv().
/**
- * g_iconv:
+ * g_iconv: (skip)
* @converter: conversion descriptor from g_iconv_open()
* @inbuf: bytes to convert
* @inbytes_left: inout parameter, bytes remaining to convert in @inbuf
/**
- * g_iconv_close:
+ * g_iconv_close: (skip)
* @converter: a conversion descriptor from g_iconv_open()
*
* Same as the standard UNIX routine iconv_close(), but
/**
- * g_iconv_open:
+ * g_iconv_open: (skip)
* @to_codeset: destination codeset
* @from_codeset: source codeset
*
* same C runtime as GLib uses, which is msvcrt.dll. Note that in
* current Microsoft compilers it is near impossible to convince it to
* build code that would use msvcrt.dll. The last Microsoft compiler
- * version that supported using msvcrt.dll as the C runtime was version
- * 6. The GNU compiler and toolchain for Windows, also known as Mingw,
+ * version that supported using msvcrt.dll as the C runtime was version 6.
+ * The GNU compiler and toolchain for Windows, also known as Mingw,
* fully supports msvcrt.dll.
*
* If you have created a #GIOChannel for a file descriptor and started
* @user_data: user data to pass to the function
*
* Calls a function for each element of a #GList.
+ *
+ * It is safe for @func to remove the element from @list, but it must
+ * not modify any part of the list after that element.
*/
* Convenience method, which frees all the memory used by a #GList,
* and calls @free_func on every element's data.
*
+ * @free_func must not modify the list (eg, by removing the freed
+ * element from it).
+ *
* Since: 2.28
*/
* use cases for environment variables in GLib-using programs you want
* the UTF-8 encoding that this function and g_getenv() provide.
*
- * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
- * list of strings which must be freed with g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ * a %NULL-terminated list of strings which must be freed with
+ * g_strfreev().
* Since: 2.8
*/
* @user_data: data passed to the log handler
* @destroy: destroy notify for @user_data, or %NULL
*
- * Like g_log_sets_handler(), but takes a destroy notify for the @user_data.
+ * Like g_log_set_handler(), but takes a destroy notify for the @user_data.
*
* This has no effect if structured logging is enabled; see
* [Using Structured Logging][using-structured-logging].
* invocation of @function.
*
* This function is the same as g_main_context_invoke() except that it
- * lets you specify the priority incase @function ends up being
+ * lets you specify the priority in case @function ends up being
* scheduled as an idle and also lets you give a #GDestroyNotify for @data.
*
* @notify should not assume that it is called from any particular
* in GLib and GIO, because those use the GLib allocators before main is
* reached. Therefore this function is now deprecated and is just a stub.
*
- * Deprecated: 2.46: Use other memory profiling tools instead
+ * Deprecated: 2.46: This function now does nothing. Use other memory
+ * profiling tools instead
*/
* @func: the function to call for each visited node
* @data: user data to pass to the function
*
- * Calls a function for each of the children of a #GNode.
- * Note that it doesn't descend beneath the child nodes.
+ * Calls a function for each of the children of a #GNode. Note that it
+ * doesn't descend beneath the child nodes. @func must not do anything
+ * that would modify the structure of the tree.
*/
* Traverses a tree starting at the given root #GNode.
* It calls the given function for each node visited.
* The traversal can be halted at any point by returning %TRUE from @func.
+ * @func must not do anything that would modify the structure of the tree.
*/
/**
* g_option_context_get_strict_posix:
- * @context: a #GoptionContext
+ * @context: a #GOptionContext
*
* Returns whether strict POSIX code is enabled.
*
/**
* g_option_context_set_strict_posix:
- * @context: a #GoptionContext
+ * @context: a #GOptionContext
* @strict_posix: the new value
*
* Sets strict POSIX mode.
* an absolute file name one that either begins with a directory
* separator such as "\Users\tml" or begins with the root on a drive,
* for example "C:\Windows". The first case also includes UNC paths
- * such as "\\myserver\docs\foo". In all cases, either slashes or
+ * such as "\\\\myserver\docs\foo". In all cases, either slashes or
* backslashes are accepted.
*
* Note that a file name relative to the current drive root does not
* don't want to run the full main loop.
*
* Each element of @fds is a #GPollFD describing a single file
- * descriptor to poll. The %fd field indicates the file descriptor,
- * and the %events field indicates the events to poll for. On return,
- * the %revents fields will be filled with the events that actually
+ * descriptor to poll. The @fd field indicates the file descriptor,
+ * and the @events field indicates the events to poll for. On return,
+ * the @revents fields will be filled with the events that actually
* occurred.
*
* On POSIX systems, the file descriptors in @fds can be any sort of
* Windows, the easiest solution is to construct all of your
* #GPollFDs with g_io_channel_win32_make_pollfd().
*
- * Returns: the number of entries in @fds whose %revents fields
+ * Returns: the number of entries in @fds whose @revents fields
* were filled in, or 0 if the operation timed out, or -1 on error or
* if the call was interrupted.
* Since: 2.20
* new-line character to the message, so typically @format should end with its
* own new-line character.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* Returns: the number of bytes printed.
* Since: 2.2
*/
* @func: the function to call for each array element
* @user_data: user data to pass to the function
*
- * Calls a function for each element of a #GPtrArray.
+ * Calls a function for each element of a #GPtrArray. @func must not
+ * add elements to or remove elements from the array.
*
* Since: 2.4
*/
* Calls @func for each element in the queue passing @user_data to the
* function.
*
+ * It is safe for @func to remove the element from @queue, but it must
+ * not modify any part of the queue after that element.
+ *
* Since: 2.4
*/
* Convenience method, which frees all the memory used by a #GQueue,
* and calls the specified destroy function on every element's data.
*
+ * @free_func should not modify the queue (eg, by removing the freed
+ * element from it).
+ *
* Since: 2.32
*/
* to the captured subexpression with the given name. '\0' refers
* to the complete match, but '\0' followed by a number is the octal
* representation of a character. To include a literal '\' in the
- * replacement, write '\\'.
+ * replacement, write '\\\\'.
*
* There are also escapes that changes the case of the following text:
*
* thread will block. Read locks can be taken recursively.
*
* It is implementation-defined how many threads are allowed to
- * hold read locks on the same lock simultaneously.
+ * hold read locks on the same lock simultaneously. If the limit is hit,
+ * or if a deadlock is detected, a critical warning will be emitted.
*
* Since: 2.32
*/
* @user_data: user data passed to @func
*
* Calls @func for each item in the sequence passing @user_data
- * to the function.
+ * to the function. @func must not modify the sequence itself.
*
* Since: 2.14
*/
* @user_data: user data passed to @func
*
* Calls @func for each item in the range (@begin, @end) passing
- * @user_data to the function.
+ * @user_data to the function. @func must not modify the sequence
+ * itself.
*
* Since: 2.14
*/
/**
* g_setenv:
- * @variable: the environment variable to set, must not contain '='.
- * @value: the value for to set the variable to.
+ * @variable: (type filename): the environment variable to set, must not
+ * contain '='.
+ * @value: (type filename): the value for to set the variable to.
* @overwrite: whether to change the variable if it already exists.
*
* Sets an environment variable. On UNIX, both the variable's name and
/**
* g_shell_parse_argv:
- * @command_line: command line to parse
+ * @command_line: (type filename): command line to parse
* @argcp: (out) (optional): return location for number of args
- * @argvp: (out) (optional) (array length=argcp zero-terminated=1): return
- * location for array of args
+ * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
+ * return location for array of args
* @error: (optional): return location for error
*
* Parses a command line into an argument vector, in much the same way
/**
* g_shell_quote:
- * @unquoted_string: a literal string
+ * @unquoted_string: (type filename): a literal string
*
* Quotes a string so that the shell (/bin/sh) will interpret the
* quoted string to mean @unquoted_string. If you pass a filename to
* quoting style used is undefined (single or double quotes may be
* used).
*
- * Returns: quoted string
+ * Returns: (type filename): quoted string
*/
/**
* g_shell_unquote:
- * @quoted_string: shell-quoted string
+ * @quoted_string: (type filename): shell-quoted string
* @error: error return location or NULL
*
* Unquotes a string as the shell (/bin/sh) would. Only handles
* be escaped with backslash. Otherwise double quotes preserve things
* literally.
*
- * Returns: an unquoted string
+ * Returns: (type filename): an unquoted string
*/
* @block_size: the number of bytes to allocate
*
* Allocates a block of memory from the slice allocator.
- * The block adress handed out can be expected to be aligned
+ * The block address handed out can be expected to be aligned
* to at least 1 * sizeof (void*),
* though in general slices are 2 * sizeof (void*) bytes aligned,
* if a malloc() fallback implementation is used instead,
* @user_data: user data to pass to the function
*
* Calls a function for each element of a #GSList.
+ *
+ * It is safe for @func to remove the element from @list, but it must
+ * not modify any part of the list after that element.
*/
* Convenience method, which frees all the memory used by a #GSList, and
* calls the specified destroy function on every element's data.
*
+ * @free_func must not modify the list (eg, by removing the freed
+ * element from it).
+ *
* Since: 2.28
*/
/**
* g_spawn_async:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's
- * @argv: (array zero-terminated=1): child's argument vector
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's
+ * @working_directory: (type filename) (nullable): child's current working
+ * directory, or %NULL to inherit parent's
+ * @argv: (array zero-terminated=1) (element-type filename):
+ * child's argument vector
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ * child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (nullable): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
* If you are writing a GTK+ application, and the program you are spawning is a
* graphical application too, then to ensure that the spawned program opens its
* windows on the right screen, you may want to use #GdkAppLaunchContext,
- * #GAppLaunchcontext, or set the %DISPLAY environment variable.
+ * #GAppLaunchContext, or set the %DISPLAY environment variable.
*
* Note that the returned @child_pid on Windows is a handle to the child
* process and not its identifier. Process handles and process identifiers
/**
* g_spawn_async_with_pipes:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
- * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
+ * @working_directory: (type filename) (nullable): child's current working
+ * directory, or %NULL to inherit parent's, in the GLib file name encoding
+ * @argv: (array zero-terminated=1) (element-type filename): child's argument
+ * vector, in the GLib file name encoding
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ * child's environment, or %NULL to inherit parent's, in the GLib file
+ * name encoding
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (nullable): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
* If you are writing a GTK+ application, and the program you are spawning is a
* graphical application too, then to ensure that the spawned program opens its
* windows on the right screen, you may want to use #GdkAppLaunchContext,
- * #GAppLaunchcontext, or set the %DISPLAY environment variable.
+ * #GAppLaunchContext, or set the %DISPLAY environment variable.
*
* Returns: %TRUE on success, %FALSE if an error was set
*/
/**
* g_spawn_command_line_async:
- * @command_line: a command line
+ * @command_line: (type filename): a command line
* @error: return location for errors
*
* A simple version of g_spawn_async() that parses a command line with
/**
* g_spawn_command_line_sync:
- * @command_line: a command line
+ * @command_line: (type filename): a command line
* @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output
* @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors
* @exit_status: (out) (optional): return location for child exit status, as returned by waitpid()
/**
* g_spawn_sync:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's
- * @argv: (array zero-terminated=1): child's argument vector
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's
+ * @working_directory: (type filename) (nullable): child's current working
+ * directory, or %NULL to inherit parent's
+ * @argv: (array zero-terminated=1) (element-type filename):
+ * child's argument vector
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ * child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
* @child_setup: (scope async) (nullable): function to run in the child just before exec()
* @user_data: (closure): user data for @child_setup
* the child is stored there; see the documentation of
* g_spawn_check_exit_status() for how to use and interpret this.
* Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
- * @flags.
+ * @flags, and on POSIX platforms, the same restrictions as for
+ * g_child_watch_source_new() apply.
*
* If an error occurs, no data is returned in @standard_output,
* @standard_error, or @exit_status.
* Note that it is usually better to use g_snprintf(), to avoid the
* risk of buffer overflow.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* See also g_strdup_printf().
*
* Returns: the number of bytes printed.
* call g_str_tokenize_and_fold() on the search term and
* perform lookups into that index.
*
- * As some examples, searching for "fred" would match the potential hit
- * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match
- * "Frédéric" but not "Frederic" (due to the one-directional nature of
- * accent matching). Searching "fo" would match "Foo" and "Bar Foo
- * Baz", but not "SFO" (because no word as "fo" as a prefix).
+ * As some examples, searching for ‘fred’ would match the potential hit
+ * ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match
+ * ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
+ * accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
+ * Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).
*
* Returns: %TRUE if @potential_hit is a hit
* Since: 2.40
* g_test_init(). See the g_test_run() documentation for more
* information on the order that tests are run in.
*
- *
* g_test_run_suite() or g_test_run() may only be called once
* in a program.
*
* g_unix_fd_add:
* @fd: a file descriptor
* @condition: IO conditions to watch for on @fd
- * @function: a #GPollFDFunc
+ * @function: a #GUnixFDSourceFunc
* @user_data: data to pass to @function
*
* Sets a function to be called when the IO condition, as specified by
/**
* g_unsetenv:
- * @variable: the environment variable to remove, must not contain '='
+ * @variable: (type filename): the environment variable to remove, must
+ * not contain '='
*
* Removes an environment variable from the environment.
*
* string to hold the output, instead of putting the output in a buffer
* you allocate in advance.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* Returns: the number of bytes printed.
* Since: 2.4
*/
* An implementation of the standard fprintf() function which supports
* positional parameters, as specified in the Single Unix Specification.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* Returns: the number of bytes printed.
* Since: 2.2
*/
* An implementation of the standard vprintf() function which supports
* positional parameters, as specified in the Single Unix Specification.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* Returns: the number of bytes printed.
* Since: 2.2
*/
* An implementation of the standard vsprintf() function which supports
* positional parameters, as specified in the Single Unix Specification.
*
+ * `glib/gprintf.h` must be explicitly included in order to use this function.
+ *
* Returns: the number of bytes printed.
* Since: 2.2
*/
* @...: format string, followed by parameters to insert
* into the format string (as with printf())
*
- * A convenience function/macro to log a warning message.
+ * A convenience function/macro to log a warning message. The message should
+ * typically *not* be translated to the user's language.
*
* This is not intended for end user error reporting. Use of #GError is
* preferred for that instead, as it allows calling functions to perform actions
*
* You can make warnings fatal at runtime by setting the `G_DEBUG`
* environment variable (see
- * [Running GLib Applications](glib-running.html)).
+ * [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ * G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
*
* If g_log_default_handler() is used as the log handler function,
* a newline character will automatically be appended to @..., and
* 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.
*
* Creates a new closure which invokes @callback_func with @user_data as
* the last parameter.
*
- * Returns: a new #GCClosure
+ * Returns: (transfer none): a floating reference to a new #GCClosure
*/
* Creates a new closure which invokes @callback_func with @user_data as
* the first parameter.
*
- * Returns: (transfer full): a new #GCClosure
+ * Returns: (transfer none): a floating reference to a new #GCClosure
*/
* }
* ]|
*
- * Returns: (transfer full): a newly allocated #GClosure
+ * Returns: (transfer none): a floating reference to a new #GClosure
*/
/**
- * g_object_dup_data:
+ * g_object_dup_data: (skip)
* @object: the #GObject to store user data on
* @key: a string, naming the user data pointer
* @dup_func: (nullable): function to dup the value
/**
- * g_object_dup_qdata:
+ * g_object_dup_qdata: (skip)
* @object: the #GObject to store user data on
* @quark: a #GQuark, naming the user data pointer
* @dup_func: (nullable): function to dup the value
*
* Gets a named field from the objects table of associations (see g_object_set_data()).
*
- * Returns: (transfer none): the data if found, or %NULL if no such data exists.
+ * Returns: (transfer none) (nullable): the data if found,
+ * or %NULL if no such data exists.
*/
* This function gets back user data pointers stored via
* g_object_set_qdata().
*
- * Returns: (transfer none): The user data pointer set, or %NULL
+ * Returns: (transfer none) (nullable): The user data pointer set, or %NULL
*/
/**
- * g_object_replace_data:
+ * g_object_replace_data: (skip)
* @object: the #GObject to store user data on
* @key: a string, naming the user data pointer
* @oldval: (nullable): the old value to compare against
* @newval: (nullable): the new value
* @destroy: (nullable): a destroy notify for the new value
- * @old_destroy: (nullable): destroy notify for the existing value
+ * @old_destroy: (out) (optional): destroy notify for the existing value
*
* Compares the user data for the key @key on @object with
* @oldval, and if they are the same, replaces @oldval with
/**
- * g_object_replace_qdata:
+ * g_object_replace_qdata: (skip)
* @object: the #GObject to store user data on
* @quark: a #GQuark, naming the user data pointer
* @oldval: (nullable): the old value to compare against
* @newval: (nullable): the new value
* @destroy: (nullable): a destroy notify for the new value
- * @old_destroy: (nullable): destroy notify for the existing value
+ * @old_destroy: (out) (optional): destroy notify for the existing value
*
* Compares the user data for the key @quark on @object with
* @oldval, and if they are the same, replaces @oldval with
* g_object_set_data:
* @object: #GObject containing the associations.
* @key: name of the key
- * @data: data to associate with that key
+ * @data: (nullable): data to associate with that key
*
* Each object carries around a table of associations from
* strings to pointers. This function lets you set an association.
* g_object_set_data_full: (skip)
* @object: #GObject containing the associations
* @key: name of the key
- * @data: data to associate with that key
- * @destroy: function to call when the association is destroyed
+ * @data: (nullable): data to associate with that key
+ * @destroy: (nullable): function to call when the association is destroyed
*
* Like g_object_set_data() except it adds notification
* for when the association is destroyed, either by setting it
* g_object_set_qdata: (skip)
* @object: The GObject to set store a user data pointer
* @quark: A #GQuark, naming the user data pointer
- * @data: An opaque user data pointer
+ * @data: (nullable): An opaque user data pointer
*
* This sets an opaque, named pointer on an object.
* The name is specified through a #GQuark (retrived e.g. via
* g_object_set_qdata_full: (skip)
* @object: The GObject to set store a user data pointer
* @quark: A #GQuark, naming the user data pointer
- * @data: An opaque user data pointer
- * @destroy: Function to invoke with @data as argument, when @data
+ * @data: (nullable): An opaque user data pointer
+ * @destroy: (nullable): Function to invoke with @data as argument, when @data
* needs to be freed
*
* This function works like g_object_set_qdata(), but in addition,
* Remove a specified datum from the object's data associations,
* without invoking the association's destroy handler.
*
- * Returns: (transfer full): the data if found, or %NULL if no such data exists.
+ * Returns: (transfer full) (nullable): the data if found, or %NULL
+ * if no such data exists.
*/
* and thus the partial string list would have been freed upon
* g_object_set_qdata_full().
*
- * Returns: (transfer full): The user data pointer set, or %NULL
+ * Returns: (transfer full) (nullable): The user data pointer set, or %NULL
*/
*
* Gets the default value of @pspec as a pointer to a #GValue.
*
- * The #GValue will remain value for the life of @pspec.
+ * The #GValue will remain valid for the life of @pspec.
*
* Returns: a pointer to a #GValue which must not be modified
* Since: 2.38
* @struct_offset in the class structure of the interface or classed type
* identified by @itype.
*
- * Returns: a new #GCClosure
+ * Returns: (transfer none): a floating reference to a new #GCClosure
*/
/**
- * g_value_array_free:
+ * g_value_array_free: (skip)
* @value_array: #GValueArray to free
*
* Free a #GValueArray including its contents.
};
/**
- * g_irepository_get_option_group: (skip)
+ * g_irepository_get_option_group:
*
* Obtain the option group for girepository, it's used
* by the dumper and for programs that wants to provide
Name: gobject-introspection
Description: GObject Introspection
-Version: 1.54.1
+Version: 1.55.0
Name: gobject-introspection
Description: GObject Introspection
-Version: 1.54.1
+Version: 1.55.0
# -*- mode: makefile -*-
+#
+# gtk-doc.make - make rules for gtk-doc
+# Copyright (C) 2003 James Henstridge
+# 2004-2007 Damon Chaplin
+# 2007-2017 Stefan Sauer
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
####################################
# Everything below here is generic #
-dnl -*- mode: autoconf -*-
+# -*- mode: autoconf -*-
+#
+# gtk-doc.m4 - configure macro to check for gtk-doc
+# Copyright (C) 2003 James Henstridge
+# 2007-2017 Stefan Sauer
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http://www.gnu.org/licenses/>.
+#
+# As a special exception, the above copyright owner gives unlimited
+# permission to copy, distribute and modify the configure scripts that
+# are the output of Autoconf when processing the Macro. You need not
+# follow the terms of the GNU General Public License when using or
+# distributing such scripts, even though portions of the text of the
+# Macro appear in them. The GNU General Public License (GPL) does govern
+# all other use of the material that constitutes the Autoconf Macro.
# serial 2
<Link>
<AdditionalDependencies>gio-2.0.lib;gobject-2.0.lib;gmodule-2.0.lib;gthread-2.0.lib;glib-2.0.lib;%(AdditionalDependencies)</AdditionalDependencies>
<AdditionalLibraryDirectories>$(GlibEtcInstallRoot)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='11.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='12.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='14.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='15.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
</Link>
</ItemDefinitionGroup>
<ItemGroup>
<PythonDirX64>$(PythonDir).x64</PythonDirX64>
<IntrospectPythonParam>PYTHON=$(PythonDir)\python.exe</IntrospectPythonParam>
<IntrospectPythonParamX64>PYTHON=$(PythonDirX64)\python.exe</IntrospectPythonParamX64>
- <GIVersion>1.54.1</GIVersion>
+ <GIVersion>1.55.0</GIVersion>
<BASE_GI_DIR>$(SolutionDir)\..\..</BASE_GI_DIR>
<ApiVersion>1.0</ApiVersion>
<DefDir>$(SolutionDir)$(Configuration)\$(Platform)\obj\$(ProjectName)</DefDir>
<Link>
<AdditionalDependencies>gio-2.0.lib;gobject-2.0.lib;gmodule-2.0.lib;gthread-2.0.lib;glib-2.0.lib;%(AdditionalDependencies)</AdditionalDependencies>
<AdditionalLibraryDirectories>$(GlibEtcInstallRoot)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='11.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='12.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='14.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='15.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
</Link>
</ItemDefinitionGroup>
<ItemGroup>
<PythonDirX64>$(PythonDir).x64</PythonDirX64>
<IntrospectPythonParam>PYTHON=$(PythonDir)\python.exe</IntrospectPythonParam>
<IntrospectPythonParamX64>PYTHON=$(PythonDirX64)\python.exe</IntrospectPythonParamX64>
- <GIVersion>1.54.1</GIVersion>
+ <GIVersion>1.55.0</GIVersion>
<BASE_GI_DIR>$(SolutionDir)\..\..</BASE_GI_DIR>
<ApiVersion>1.0</ApiVersion>
<DefDir>$(SolutionDir)$(Configuration)\$(Platform)\obj\$(ProjectName)</DefDir>
<Link>
<AdditionalDependencies>gio-2.0.lib;gobject-2.0.lib;gmodule-2.0.lib;gthread-2.0.lib;glib-2.0.lib;%(AdditionalDependencies)</AdditionalDependencies>
<AdditionalLibraryDirectories>$(GlibEtcInstallRoot)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='11.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='12.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='14.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='15.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
</Link>
</ItemDefinitionGroup>
<ItemGroup>
<PythonDirX64>$(PythonDir).x64</PythonDirX64>
<IntrospectPythonParam>PYTHON=$(PythonDir)\python.exe</IntrospectPythonParam>
<IntrospectPythonParamX64>PYTHON=$(PythonDirX64)\python.exe</IntrospectPythonParamX64>
- <GIVersion>1.54.1</GIVersion>
+ <GIVersion>1.55.0</GIVersion>
<BASE_GI_DIR>$(SolutionDir)\..\..</BASE_GI_DIR>
<ApiVersion>1.0</ApiVersion>
<DefDir>$(SolutionDir)$(Configuration)\$(Platform)\obj\$(ProjectName)</DefDir>
<Link>
<AdditionalDependencies>gio-2.0.lib;gobject-2.0.lib;gmodule-2.0.lib;gthread-2.0.lib;glib-2.0.lib;%(AdditionalDependencies)</AdditionalDependencies>
<AdditionalLibraryDirectories>$(GlibEtcInstallRoot)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='11.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='12.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='14.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='15.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
</Link>
</ItemDefinitionGroup>
<ItemGroup>
<PythonDirX64>$(PythonDir).x64</PythonDirX64>
<IntrospectPythonParam>PYTHON=$(PythonDir)\python.exe</IntrospectPythonParam>
<IntrospectPythonParamX64>PYTHON=$(PythonDirX64)\python.exe</IntrospectPythonParamX64>
- <GIVersion>1.54.1</GIVersion>
+ <GIVersion>1.55.0</GIVersion>
<BASE_GI_DIR>$(SolutionDir)\..\..</BASE_GI_DIR>
<ApiVersion>1.0</ApiVersion>
<DefDir>$(SolutionDir)$(Configuration)\$(Platform)\obj\$(ProjectName)</DefDir>
<Link>
<AdditionalDependencies>gio-2.0.lib;gobject-2.0.lib;gmodule-2.0.lib;gthread-2.0.lib;glib-2.0.lib;%(AdditionalDependencies)</AdditionalDependencies>
<AdditionalLibraryDirectories>$(GlibEtcInstallRoot)\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='11.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='12.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='14.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
+ <AdditionalOptions Condition="'$(VisualStudioVersion)|$(Platform)'=='15.0|x64'">/HIGHENTROPYVA %(AdditionalOptions)</AdditionalOptions>
</Link>
</ItemDefinitionGroup>
<ItemGroup>
<PythonDirX64>$(PythonDir).x64</PythonDirX64>
<IntrospectPythonParam>PYTHON=$(PythonDir)\python.exe</IntrospectPythonParam>
<IntrospectPythonParamX64>PYTHON=$(PythonDirX64)\python.exe</IntrospectPythonParamX64>
- <GIVersion>1.54.1</GIVersion>
+ <GIVersion>1.55.0</GIVersion>
<BASE_GI_DIR>$(SolutionDir)\..\..</BASE_GI_DIR>
<ApiVersion>1.0</ApiVersion>
<DefDir>$(SolutionDir)$(Configuration)\$(Platform)\obj\$(ProjectName)</DefDir>
/>
<UserMacro
Name="GIVersion"
- Value="1.54.1"
+ Value="1.55.0"
/>
<UserMacro
Name="BASE_GI_DIR"
projects / platform / upstream / gobject-introspection.git / commitdiff